Gemini API を OpenTelemetry でトレースする本番運用ガイド — 1リクエストの内側を全部見せる

# gemini_traced.py
# Gemini API 呼び出しを OpenTelemetry の span でラップし、
# GenAI Semantic Conventions に沿った属性を自動で付与する。
# 目的: モデル・トークン・終了理由を全 span に統一して載せ、
#       後段の集計（コスト・遅延・失敗の相関分析）を可能にする。
 
from google import genai
from google.genai import types
from opentelemetry import trace
from opentelemetry.trace import Status, StatusCode
 
tracer = trace.get_tracer("gemini.client", "1.0.0")
client = genai.Client()  # GOOGLE_API_KEY または GEMINI_API_KEY を環境変数で
 
def generate_traced(
    *,
    model: str,
    contents: str | list,
    config: types.GenerateContentConfig | None = None,
    user_id: str | None = None,
):
    """OTel span でラップした Gemini 呼び出し。"""
    with tracer.start_as_current_span(
        name=f"gemini.generate_content {model}",
        attributes={
            "gen_ai.system": "google.gemini",
            "gen_ai.request.model": model,
            "gen_ai.operation.name": "generate_content",
            **({"enduser.id": user_id} if user_id else {}),
        },
    ) as span:
        try:
            cfg = config or types.GenerateContentConfig()
            if cfg.temperature is not None:
                span.set_attribute("gen_ai.request.temperature", cfg.temperature)
            if cfg.max_output_tokens is not None:
                span.set_attribute("gen_ai.request.max_tokens", cfg.max_output_tokens)
 
            res = client.models.generate_content(
                model=model, contents=contents, config=cfg
            )
 
            # 使用トークンを規約属性で記録（後段で集計しやすい）
            if res.usage_metadata:
                u = res.usage_metadata
                span.set_attribute("gen_ai.usage.input_tokens", u.prompt_token_count or 0)
                span.set_attribute("gen_ai.usage.output_tokens", u.candidates_token_count or 0)
                if getattr(u, "cached_content_token_count", None):
                    span.set_attribute("gen_ai.usage.cached_input_tokens", u.cached_content_token_count)
 
            # 終了理由（配列で持つのが規約）
            if res.candidates:
                fr = [c.finish_reason.name for c in res.candidates if c.finish_reason]
                if fr:
                    span.set_attribute("gen_ai.response.finish_reasons", fr)
 
            span.set_attribute("gen_ai.response.model", res.model_version or model)
            span.set_status(Status(StatusCode.OK))
            return res
        except Exception as e:
            span.record_exception(e)
            span.set_status(Status(StatusCode.ERROR, str(e)[:200]))
            raise

# tracing_setup.py
# 起動時に 1 度だけ呼ぶ。Resource にサービス情報を持たせ、
# 「どのサービスのどのバージョンが何 ms かかったか」を後から絞り込めるようにする。
 
import os
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.sdk.resources import Resource
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
 
def setup_tracing():
    resource = Resource.create({
        "service.name": os.getenv("OTEL_SERVICE_NAME", "gemini-app"),
        "service.version": os.getenv("APP_VERSION", "0.1.0"),
        "deployment.environment": os.getenv("APP_ENV", "production"),
    })
    provider = TracerProvider(resource=resource)
    exporter = OTLPSpanExporter(
        endpoint=os.getenv("OTEL_EXPORTER_OTLP_ENDPOINT", "http://localhost:4318/v1/traces"),
    )
    provider.add_span_processor(BatchSpanProcessor(exporter))
    trace.set_tracer_provider(provider)

// telemetry.ts
// Node アプリの最初に require/import で読み込むこと。
// HTTP・Express の自動計装と Gemini 用の Tracer を共存させる構成。
 
import { NodeSDK } from "@opentelemetry/sdk-node";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
import { Resource } from "@opentelemetry/resources";
import { SemanticResourceAttributes } from "@opentelemetry/semantic-conventions";
 
const sdk = new NodeSDK({
  resource: new Resource({
    [SemanticResourceAttributes.SERVICE_NAME]: process.env.OTEL_SERVICE_NAME ?? "gemini-app",
    [SemanticResourceAttributes.SERVICE_VERSION]: process.env.APP_VERSION ?? "0.1.0",
  }),
  traceExporter: new OTLPTraceExporter({
    url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT ?? "http://localhost:4318/v1/traces",
  }),
  instrumentations: [getNodeAutoInstrumentations()],
});
sdk.start();
process.on("SIGTERM", () => sdk.shutdown());

// geminiTraced.ts
// generateContent 呼び出しを span でラップする。
// SDK 例外時は span に exception event を残し、ステータスを ERROR にする。
 
import { GoogleGenAI } from "@google/genai";
import { trace, SpanStatusCode } from "@opentelemetry/api";
 
const tracer = trace.getTracer("gemini.client", "1.0.0");
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY! });
 
export async function generateTraced(opts: {
  model: string;
  contents: string;
  userId?: string;
  temperature?: number;
}) {
  return tracer.startActiveSpan(`gemini.generate_content ${opts.model}`, async (span) => {
    span.setAttributes({
      "gen_ai.system": "google.gemini",
      "gen_ai.request.model": opts.model,
      "gen_ai.operation.name": "generate_content",
      ...(opts.temperature != null ? { "gen_ai.request.temperature": opts.temperature } : {}),
      ...(opts.userId ? { "enduser.id": opts.userId } : {}),
    });
    try {
      const res = await ai.models.generateContent({
        model: opts.model,
        contents: opts.contents,
        config: { temperature: opts.temperature },
      });
      const u = res.usageMetadata;
      if (u) {
        span.setAttribute("gen_ai.usage.input_tokens", u.promptTokenCount ?? 0);
        span.setAttribute("gen_ai.usage.output_tokens", u.candidatesTokenCount ?? 0);
      }
      const fr = res.candidates?.map((c) => c.finishReason).filter(Boolean) as string[] | undefined;
      if (fr?.length) span.setAttribute("gen_ai.response.finish_reasons", fr);
      span.setStatus({ code: SpanStatusCode.OK });
      return res;
    } catch (e: any) {
      span.recordException(e);
      span.setStatus({ code: SpanStatusCode.ERROR, message: String(e?.message ?? e).slice(0, 200) });
      throw e;
    } finally {
      span.end();
    }
  });
}

# generate_content_stream を span event つきでラップする部分（要点のみ抜粋）。
# 目的: TTFT・チャンク数・総バイトを 1 span に集約し、UI 体感とサーバ実測を一致させる。
 
with tracer.start_as_current_span("gemini.generate_content_stream") as span:
    span.set_attribute("gen_ai.request.model", model)
    first = True
    chunks = 0
    for chunk in client.models.generate_content_stream(model=model, contents=contents):
        chunks += 1
        if first:
            span.add_event("first_token")
            first = False
        # 1 chunk ごとに event を打つと cardinality が爆発するので
        # 100 chunk 単位で間引くのが運用上の現実解。
        if chunks % 100 == 0:
            span.add_event("chunk_progress", attributes={"chunks": chunks})
        yield chunk.text or ""
    span.set_attribute("gen_ai.response.chunk_count", chunks)