Getting Started (Developer Guide)
This guide walks through installing the AI Observly SDK, initializing it in your application, and logging your first usage event.
Getting Started with the AI Observly SDK
This guide walks through installing the AI Observly SDK, initializing it in your application, and logging your first usage event.
Installation
Install the SDK using your package manager of choice:
npm install ai-observlyQuick Start
Initialize the SDK
Initialize AI Observly once across your application:
1
Initialize the SDK
import AIObservly from "ai-observly";
const observly = new AIObservly({
apiKey: process.env.AI_OBSERVLY_KEY!,
environment: process.env.NODE_ENV || "production", // Optional global default
appVersion: "v2.1.0", // Optional version tag
});2
Log Usage After LLM Calls
observly.logUsage({
customerId: "cust_acme_123",
featureLabel: "chatbot",
model: "gpt-4o",
inputTokens: completion.usage?.prompt_tokens || 0,
outputTokens: completion.usage?.completion_tokens || 0,
});Full example (prompt caching, latency & error guardrails):
import express from "express";
import { OpenAI } from "openai";
import AIObservly from "ai-observly";
const app = express();
const openai = new OpenAI();
const observly = new AIObservly({
apiKey: process.env.AI_OBSERVLY_KEY!,
});
app.post("/api/v1/summarize", async (req, res) => {
const currentCustomer = req.user;
const startTime = Date.now();
try {
const completion = await openai.chat.completions.create({
model: "gpt-4o",
messages: [{ role: "user", content: req.body.text }],
});
const latencyMs = Date.now() - startTime;
// Fire-and-forget telemetry logging
observly.logUsage({
customerId: currentCustomer.id,
customerName: currentCustomer.name,
featureLabel: "doc_summarizer",
model: completion.model,
provider: "openai",
inputTokens: completion.usage?.prompt_tokens || 0,
outputTokens: completion.usage?.completion_tokens || 0,
cachedInputTokens: completion.usage?.prompt_tokens_details?.cached_tokens || 0,
latencyMs,
finishReason: completion.choices[0]?.finish_reason || "stop",
sessionId: req.body.sessionId,
environment: process.env.NODE_ENV,
});
return res.json({ result: completion.choices[0].message.content });
} catch (error: any) {
// Log failed calls to track wasted spend and rate limits
observly.logUsage({
customerId: currentCustomer.id,
featureLabel: "doc_summarizer",
model: "gpt-4o",
isError: true,
statusCode: error.status || 500,
errorCode: error.code || "api_error",
latencyMs: Date.now() - startTime,
});
return res.status(500).json({ error: "Summarization failed" });
}
});