@countly/ai-sdk-google-genai

Countly AI observability adapter for the Google GenAI TypeScript SDK.

Part of the Countly AI SDK — provider-agnostic LLM observability for every AI stack.

Install

npm install @countly/ai-sdk-google-genai

@countly/ai-sdk-core is pulled in automatically.

Peer dependency

@google/genai >= 1.0.0

Quick Start

import { GoogleGenAI } from "@google/genai";
import { observeGoogleGenAI } from "@countly/ai-sdk-google-genai";
import { AsyncLocalStorage } from "node:async_hooks";

const userStore = new AsyncLocalStorage<{ userId: string }>();

app.use((req, res, next) => {
  userStore.run({ userId: req.user.id }, next);
});

const client = observeGoogleGenAI(new GoogleGenAI({ apiKey: "..." }), {
  appKey: "YOUR_APP_KEY",
  url: "https://your-countly-server.com",
  getDeviceId: () => userStore.getStore()?.userId,
});

const response = await client.models.generateContent({
  model: "gemini-2.5-pro",
  contents: "Explain quantum computing",
});

Streaming

const stream = await client.models.generateContentStream({
  model: "gemini-2.5-flash",
  contents: "Hello",
});

for await (const chunk of stream) {
  process.stdout.write(chunk.text || "");
}

Streamed responses are accumulated across chunks: text is concatenated, every functionCall part is collected (they arrive before the final chunk), and usageMetadata is taken from the last chunk that reports it — it is cumulative, so it is never summed. Breaking out of the loop early still emits a row for the tokens the request consumed.

Chat sessions

const chat = client.chats.create({ model: "gemini-2.5-flash" });
const answer = await chat.sendMessage({ message: "Hello" });

chats.create() is wrapped too, so sendMessage / sendMessageStream produce the same [CLY]_llm_interaction rows as models.generateContent. Each message is counted exactly once.

What's captured

• Token usage. usage_input is the provider's total input count (promptTokenCount, which already includes cachedContentTokenCount, plus the separately-reported toolUsePromptTokenCount); usage_output is the inclusive output total, i.e. candidatesTokenCount + thoughtsTokenCount — Gemini is the only provider that reports those two as disjoint buckets, and folding them keeps thinking tokens from being billed at $0 on the pro models. usage_total is derived by core from the two.
• Reasoning tokens (thoughtsTokenCount) as the usage_reasoning subset, and cache reads (cachedContentTokenCount) as usage_cache_read.
• Audio / image token buckets from promptTokensDetails / candidatesTokensDetails; the cost is then marked priced_modality_approx rather than presented as exact.
• Cost, computed from model pricing. When the model has no price entry the cost fields are absent and cost_priced says unpriced_model; when the provider reported no usage at all the token fields are absent and usage_state says not_reported. Neither is ever reported as a 0.
• Latency in whole milliseconds (total + TTFT for streaming).
• api_host_type / api_host — the class of endpoint (vendor_direct, gateway, local_infra, …) and its bare hostname, read from the client's resolved baseUrl. The path and query are never emitted, so an API key in the URL cannot leak.
• Finish reason normalized to stop | length | tool_calls | content_filter | error | other | not_reported (from STOP, MAX_TOKENS, SAFETY, RECITATION, …). A prompt rejected before generation (promptFeedback.blockReason) is recorded as status: "incomplete".
• Function calls, with call_id when the model supplies one. Their status is "unknown": the response carries the model's request for a call, never its outcome, so the adapter does not claim success it never observed.
• Error tracking with categorization. Instrumentation is isolated from the provider call — a bug in this SDK degrades to a missing row, never to a fabricated provider error and never to an exception in your code.
• APM traces, per-user aggregation.

Not tracked

| Surface | Status | |---|---| | models.generateContent / generateContentStream | tracked | | chats.create().sendMessage / sendMessageStream | tracked | | models.embedContent, countTokens, generateImages, generateVideos | not tracked — not generations | | live.* (bidirectional sessions) | not tracked | | caches.*, files.*, tunings.*, operations.* | not tracked |

Content-bearing metadata (groundingMetadata, citationMetadata, logprobsResult, safetyRatings) ships only at observabilityLevel: 2, alongside the text previews. At lower levels only derived counts (grounding_chunk_count, citation_count, safety_blocked_count, avg_logprobs) are emitted.

Caller-supplied prompt_id

By default every tracked call is stamped with an auto-generated prompt_id. If your app already has an identifier for the interaction (a chat message id, a request id, a trace id), supply it with getPromptId and the adapter uses it verbatim for the [CLY]_llm_interaction event instead of generating one. This lets you correlate Countly analytics with your own logs and store feedback against an id you already control:

import { AsyncLocalStorage } from "node:async_hooks";

const requestStore = new AsyncLocalStorage<{ promptId: string }>();

const ai = observeGoogleGenAI(new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY }), {
  appKey: "YOUR_APP_KEY",
  url: "https://your-countly-server.com",
  // Return your own id; return undefined to fall back to the generated one.
  getPromptId: () => requestStore.getStore()?.promptId,
});

getPromptId is called once per tracked call (generateContent, generateContentStream, chats.sendMessage*), before the request runs. When it is absent or returns undefined, the adapter falls back to the generated id (identical behavior to not setting it). The resolved id is exactly what surfaces through the onPrompt callback below, so caller-supplied ids flow straight into feedback correlation.

Your id is now the turn identity: it is emitted as run_id on every row of the turn (interaction, tool, tool-parameter), and it is the join column the dashboard groups by. PromptInfo.prompt_id still returns it, so the feedback flow below is unchanged; PromptInfo.event_id is the id of that one generation's row, should you want to rate a single answer instead of the whole turn.

Feedback

User feedback (thumbs up/down, ratings, comments) is not auto-collected — wire it from your UI. Capture the prompt_id of each tracked interaction via the onPrompt callback, then record feedback against it with createFeedbackTracker (re-exported from this package, so no extra install is needed):

import { GoogleGenAI } from "@google/genai";
import { observeGoogleGenAI, createFeedbackTracker, type PromptInfo } from "@countly/ai-sdk-google-genai";

const countly = { appKey: "YOUR_APP_KEY", url: "https://your-countly-server.com" };

let lastPrompt: PromptInfo | undefined;
const ai = observeGoogleGenAI(new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY }), {
  ...countly,
  onPrompt: (info) => { lastPrompt = info; }, // fires after every tracked call
});

const feedback = createFeedbackTracker(countly, { sdk_adapter: "google-genai" });

const response = await ai.models.generateContent({
  model: "gemini-2.0-flash",
  contents: "Explain quantum computing",
});

// ...later, when the user rates the answer:
feedback.track({
  prompt_id: lastPrompt!.prompt_id,
  rating: "thumbs_up", // or "thumbs_down", or any custom string
  score: 0.9, // optional 0-1 numeric score
  category: "helpful", // optional: hallucination, irrelevant, harmful, ...
  comment: "Great answer", // optional free-form text
  deviceId: user.id, // attribute to the same user as the interaction
});

Each track() call emits a [CLY]_llm_interaction_feedback event whose prompt_id links back to the [CLY]_llm_interaction event — powering prompt → feedback funnels and per-model satisfaction breakdowns in Countly. In a real app, store prompt_id alongside the rendered message (or return it to your client) and read it back when the user rates the answer. Feedback is batched like interaction events; call feedback.flush() to send immediately, or feedback.shutdown() on process exit.

Full documentation

See the Countly AI SDK repository for the schema v2 wire contract (one row per generation, RULE A dimensions, RULE B measures with their usage_state / cost_priced markers, and the common envelope), the adapter capability matrix, observability levels (0/1/2), cost calculation, privacy controls, and Countly plugin integration (Drill, Funnels, Cohorts, APM, Crash Analytics).

License

MIT