Google Gemini 基于 OpenTelemetry 的监控与可观测性
本指南将带你使用 OpenTelemetry 为 Google Gemini API 配置监控与可观测性,并将日志、追踪(traces)和指标导出至 SigNoz。通过此集成,你可以观察模型性能、捕获请求/响应详情,并在 SigNoz 中跟踪系统级指标,从而实时掌握 Gemini 应用的延迟、错误率及使用情况趋势。
在 LLM 应用中为 Gemini 添加遥测数据可实现 AI 工作流的全方位可观测性,便于调试问题、优化性能并理解用户交互。借助 SigNoz,你可以在统一仪表盘中分析关联的追踪、日志和指标,配置告警,并获取可操作的洞察,从而持续提升系统的可靠性、响应速度和用户体验。
前提条件
- SigNoz 环境(二选一):
- 拥有有效数据摄入密钥的 SigNoz Cloud 账户
- 自托管的 SigNoz 实例
- 互联网访问权限,用于向 SigNoz Cloud 发送遥测数据
- 一个可用的 Google Gemini API 账户及 API 密钥
- 已安装
pip用于管理 Python 包 - (可选,但推荐) 创建 Python 虚拟环境以隔离依赖
监控 Google Gemini
Python 无代码(推荐)代码推荐采用无代码自动插桩进行快速配置,它只需极少代码改动。当你希望在无需修改应用代码的情况下快速启用可观测性,且正在使用标准插桩库时,这种方式尤为理想。
步骤 1: 在 Python 环境中安装必要的包。
Copypip install \
opentelemetry-distro \
opentelemetry-exporter-otlp \
opentelemetry-instrumentation-httpx \
opentelemetry-instrumentation-system-metrics \
google-genai \
openinference-instrumentation-google-genai
步骤 2: 添加自动插桩
Copyopentelemetry-bootstrap --action=install
步骤 3: 配置日志级别
为确保日志被正确捕获和导出,请将根记录器配置为输出 INFO 级别或更高的日志:
Copyimport logging
logging.getLogger().setLevel(logging.INFO)
这会将根日志记录器的最低日志级别设置为 INFO,确保 logger.info() 及更高级别的日志(WARNING、ERROR、CRITICAL)能被 OpenTelemetry 日志自动埋点捕获并发送到 SigNoz。
步骤 4:运行示例
Copyfrom google import genai
client = genai.Client()
response = client.models.generate_content(
model="gemini-2.5-flash",
contents="What is SigNoz?",
)
print(response.text)📌 注意:运行代码前,请确保已将
GEMINI_API_KEY环境变量正确配置为你的 API key。
步骤 5:以自动埋点方式运行应用
CopyOTEL_RESOURCE_ATTRIBUTES="service.name=<service_name>" \
OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.<region>.signoz.cloud:443" \
OTEL_EXPORTER_OTLP_HEADERS="signoz-ingestion-key=<your-ingestion-key>" \
OTEL_EXPORTER_OTLP_PROTOCOL=grpc \
OTEL_TRACES_EXPORTER=otlp \
OTEL_METRICS_EXPORTER=otlp \
OTEL_LOGS_EXPORTER=otlp \
OTEL_PYTHON_LOG_CORRELATION=true \
OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true \
opentelemetry-instrument <your_run_command><service_name>:你的服务名称<region>:你的 SigNoz Cloud 区域<your-ingestion-key>:你的 SigNoz ingestion key- 将
<your_run_command>替换为你实际运行应用的命令,例如python main.py
使用自托管 SigNoz?大部分步骤相同,只需按 Cloud → Self-Hosted 的说明修改 endpoint 并去掉 ingestion key 请求头即可。
基于代码的手动埋点可以对遥测配置进行细粒度控制。当你需要自定义 resource 属性、采样策略,或与现有可观测性基础设施集成时,建议采用这种方式。
步骤 1:在 Python 环境中安装所需的包。
Copypip install \
opentelemetry-api \
opentelemetry-sdk \
opentelemetry-exporter-otlp \
opentelemetry-instrumentation-system-metrics \
opentelemetry-instrumentation-httpx \
google-genai \
openinference-instrumentation-google-genai
第二步:在 Python 应用中导入必要的模块
Traces(追踪):
Copyfrom openinference.instrumentation.google_genai import GoogleGenAIInstrumentor
from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
Logs(日志):
Copyfrom opentelemetry.sdk._logs import LoggerProvider, LoggingHandler
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter
from opentelemetry._logs import set_logger_provider
import logging
Metrics(指标):
Copyfrom opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.exporter.otlp.proto.http.metric_exporter import OTLPMetricExporter
from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
from opentelemetry import metrics
from opentelemetry.instrumentation.system_metrics import SystemMetricsInstrumentor
from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor
第三步:配置 OpenTelemetry Tracer Provider,将 Traces 直接发送至 SigNoz Cloud
Copyfrom opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry import trace
import os
resource = Resource.create({"service.name": "<service_name>"})
provider = TracerProvider(resource=resource)
span_exporter = OTLPSpanExporter(
endpoint= os.getenv("OTEL_EXPORTER_TRACES_ENDPOINT"),
headers={"signoz-ingestion-key": os.getenv("SIGNOZ_INGESTION_KEY")},
)
processor = BatchSpanProcessor(span_exporter)
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)
<service_name>为你的服务名称OTEL_EXPORTER_TRACES_ENDPOINT→ SigNoz Cloud 的 trace 端点,并使用对应的区域:https://ingest.<region>.signoz.cloud:443/v1/tracesSIGNOZ_INGESTION_KEY→ 你的 SigNoz ingestion key
使用自托管(Self-Hosted)SigNoz?大部分步骤都一样。只需按 Cloud → Self-Hosted 中的说明修改端点并移除 ingestion key 请求头即可。
步骤 4:使用 GoogleGenAIInstrumentor 和已配置的 Tracer Provider 对 Google Gemini 进行插桩
from openinference.instrumentation.google_genai import GoogleGenAIInstrumentor
GoogleGenAIInstrumentor().instrument(tracer_provider=provider)📌 注意:请将这段代码放在应用逻辑的最开头,即在任何 Gemini 函数被调用之前,以确保遥测数据能被正确采集。
步骤 5:配置日志
Copyimport logging
import os
from opentelemetry._logs import set_logger_provider
from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter
logger_provider = LoggerProvider(resource=resource)
set_logger_provider(logger_provider)
otlp_log_exporter = OTLPLogExporter(
endpoint= os.getenv("OTEL_EXPORTER_LOGS_ENDPOINT"),
headers={"signoz-ingestion-key": os.getenv("SIGNOZ_INGESTION_KEY")},
)
logger_provider.add_log_record_processor(
BatchLogRecordProcessor(otlp_log_exporter)
)
# Attach OTel logging handler to root logger
handler = LoggingHandler(level=logging.INFO, logger_provider=logger_provider)
logging.basicConfig(level=logging.INFO, handlers=[handler])
logger = logging.getLogger(__name__)Expand 22 lines<service_name>是你的服务名称OTEL_EXPORTER_LOGS_ENDPOINT→ SigNoz Cloud 的日志端点,并使用对应的区域:https://ingest.<region>.signoz.cloud:443/v1/logsSIGNOZ_INGESTION_KEY→ 你的 SigNoz ingestion key
使用自托管 SigNoz?大部分步骤相同。若要适配本指南,请按照 Cloud → Self-Hosted 中的说明更新 endpoint 并移除 ingestion key 请求头。
步骤 6:配置 Metrics
Copyfrom opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.exporter.otlp.proto.http.metric_exporter import OTLPMetricExporter
from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
from opentelemetry import metrics
from opentelemetry.instrumentation.system_metrics import SystemMetricsInstrumentor
from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor
import os
resource = Resource.create({"service.name": "<service-name>"})
metric_exporter = OTLPMetricExporter(
endpoint= os.getenv("OTEL_EXPORTER_METRICS_ENDPOINT"),
headers={"signoz-ingestion-key": os.getenv("SIGNOZ_INGESTION_KEY")},
)
reader = PeriodicExportingMetricReader(metric_exporter)
metric_provider = MeterProvider(metric_readers=[reader], resource=resource)
metrics.set_meter_provider(metric_provider)
meter = metrics.get_meter(__name__)
# 开启开箱即用的 metrics
SystemMetricsInstrumentor().instrument()
HTTPXClientInstrumentor().instrument()Expand 23 lines<service_name>是你的服务名称OTEL_EXPORTER_METRICS_ENDPOINT→ SigNoz Cloud metrics endpoint,需使用正确的 region:https://ingest.<region>.signoz.cloud:443/v1/metricsSIGNOZ_INGESTION_KEY→ 你的 SigNoz ingestion key
📌 注意:SystemMetricsInstrumento
![]()
![]()
![]()
![]()
![]()
![]()
![]()
![]()
