这次我们来看一个面向 GenAI 应用的可观测性开源项目。它的核心目标很直接从 OpenTelemetry 链路追踪数据中自动提取并生成有业务意义的 GenAI 指标比如提示词长度、模型响应延迟、Token 消耗等并直接对接 Prometheus 和 Grafana 进行监控告警。对于正在开发或运维 AI 应用如聊天机器人、内容生成、智能客服的团队来说手动埋点统计这些指标既繁琐又容易遗漏。这个项目试图解决的就是这个问题——它不是一个全新的监控系统而是一个基于现有 OpenTelemetry 生态的“指标提取器”和“边界定义器”。你不需要改造大量业务代码只需要确保你的 GenAI 调用比如通过 LangChain、LlamaIndex 或直接调用 OpenAI/ Anthropic API接入了 OpenTelemetry 分布式追踪这个工具就能从追踪数据中“读懂”你的 AI 交互过程并产出关键指标。本文将带你快速了解这个项目的核心能力、适用场景并重点演示如何在一个模拟的 GenAI 应用环境中从零搭建 OpenTelemetry Collector配置这个处理器最终在 Grafana 面板上看到实时的提示词性能与成本指标。整个过程会重点关注其部署门槛、配置方式、指标效果以及如何集成到现有监控体系。如果你关心如何低成本、无侵入地对 AI 应用进行精细化监控这篇文章值得一看。1. 核心能力速览能力项说明项目类型OpenTelemetry Collector 处理器Processor核心功能解析 OpenTelemetry Trace提取 GenAI 相关语义信息如原始提示词、模型名称、Token 数并生成 Prometheus 格式的指标。输入依赖必须已有生成 OpenTelemetry Trace 的 GenAI 应用。支持通过 SDK如opentelemetry-sdk或自动插桩如opentelemetry-instrumentation-openai产生的追踪数据。输出目标生成 Prometheus 可抓取的指标端点/metrics或通过 OTLP 导出器转发。关键指标预计包含请求延迟、Token 消耗输入/输出、提示词长度、模型调用次数、错误率等并可基于原始提示词内容进行分组或过滤。部署模式作为 OpenTelemetry Collector 的一个组件运行支持二进制、Docker 容器化部署。配置复杂度中等。需要理解 OpenTelemetry Collector 配置语法并正确设置处理器链。适合场景需要对 GenAI 应用进行生产级监控、成本分析、性能调优和提示词工程效果评估的团队。2. 适用场景与使用边界这个工具不是万能的它精准地定位于一个细分领域为已经采用 OpenTelemetry 进行链路追踪的 GenAI 应用补充业务视角的指标监控。它非常适合以下场景成本监控与优化团队需要监控不同模型、不同提示词模板的 Token 消耗以优化使用策略和控制 API 成本。性能与稳定性监控实时查看模型调用的延迟、错误率快速定位是模型服务方问题还是自身应用逻辑问题。提示词工程分析通过关联指标与原始提示词或其哈希值分析不同提示词长度、结构对响应质量和延迟的影响。SLA 保障为面向用户的 AI 功能定义服务等级指标如 P99 延迟 2s并配置告警。它的使用边界也很清晰非侵入式但有前提它不要求修改核心业务逻辑但要求应用必须先接入 OpenTelemetry Tracing。如果你的应用还没有链路追踪需要先完成这一步。指标而非日志它产出的是聚合后的指标如每秒请求数、平均延迟而不是包含完整上下文和错误的原始日志。深度调试仍需结合 Jaeger 等链路查询工具和应用的日志。依赖现有生态它本身不存储数据指标需要由 Prometheus 抓取再由 Grafana 展示。因此你需要一个基本的 Prometheus Grafana 监控栈。隐私与安全该工具会处理原始的提示词raw prompts。在生产环境中必须谨慎考虑数据脱敏。通常建议对提示词进行哈希处理后再作为指标标签以避免在监控系统中泄露敏感信息。3. 环境准备与前置条件在开始部署和测试之前请确保你的环境满足以下基础要求。我们将以一个本地测试环境为例进行说明。操作系统支持 Linux、macOS 和 Windows。本文演示基于 Ubuntu 22.04但步骤具有普适性。容器运行时可选但推荐Docker 和 Docker Compose。这能极大简化 OpenTelemetry Collector、Prometheus 和 Grafana 的部署。目标监控应用一个能够产生 OpenTelemetry 追踪数据的 GenAI 应用。作为演示我们可以使用一个简单的 Python 脚本它使用openai库并通过opentelemetry-instrumentation-openai自动插桩。网络与端口OpenTelemetry Collector: 默认需要开放接收 Trace 的端口如4318用于 OTLP/gRPC4317用于 OTLP/http。Prometheus: 默认端口9090用于抓取 Collector 暴露的指标。Grafana: 默认端口3000用于可视化。确保这些端口在本地或测试服务器上可用无冲突。基础工具git用于克隆项目curl或wget用于测试 以及文本编辑器。4. 安装部署与启动方式整个系统的架构如下GenAI 应用-OpenTelemetry Collector (包含 Bounded GenAI Metrics Processor)-Prometheus-Grafana。我们将使用 Docker Compose 一键部署 Collector、Prometheus 和 Grafana。你需要手动准备 Collector 的配置文件。步骤 1获取 OpenTelemetry Collector 配置首先你需要编写一个otel-collector-config.yaml文件。关键点在于在processors部分添加这个genai-metrics处理器并在pipelines中启用它。# otel-collector-config.yaml receivers: otlp: protocols: grpc: endpoint: 0.0.0.0:4317 http: endpoint: 0.0.0.0:4318 processors: # 批处理处理器优化性能 batch: # 核心GenAI 指标处理器 # 注意处理器名称和具体配置参数需根据项目实际文档调整 genai-metrics: # 示例配置启用对 OpenAI 和 Anthropic 调用的解析 enabled_platforms: [openai, anthropic] # 将原始提示词作为标签时进行哈希保护隐私 hash_prompt: true # 要提取的指标列表 metrics: - name: genai.request.duration type: histogram unit: ms description: “GenAI 请求耗时” - name: genai.token.usage.input type: counter unit: token description: “输入 Token 消耗” - name: genai.token.usage.output type: counter unit: token description: “输出 Token 消耗” exporters: # 将处理后的 Trace 继续向后传递如到 Jaeger otlp/traces: endpoint: jaeger:4317 tls: insecure: true # 将生成的指标以 Prometheus 格式暴露出来 prometheus: endpoint: “0.0.0.0:8889” namespace: otel_genai # 也可以将指标通过 OTLP 导出 debug: service: pipelines: traces: receivers: [otlp] processors: [batch, genai-metrics] # 在此处加入 genai-metrics 处理器 exporters: [debug, otlp/traces] metrics: receivers: [otlp] processors: [batch] exporters: [debug, prometheus]步骤 2创建 Docker Compose 文件创建一个docker-compose.yaml文件定义三个服务。# docker-compose.yaml version: ‘3.8’ services: otel-collector: image: otel/opentelemetry-collector-contrib:latest container_name: otel-collector-genai command: [“--config/etc/otel-collector-config.yaml”] volumes: - ./otel-collector-config.yaml:/etc/otel-collector-config.yaml ports: - “4317:4317” # OTLP gRPC - “4318:4318” # OTLP HTTP - “8889:8889” # Prometheus metrics endpoint networks: - monitoring-net prometheus: image: prom/prometheus:latest container_name: prometheus-genai volumes: - ./prometheus.yml:/etc/prometheus/prometheus.yml command: - ‘--config.file/etc/prometheus/prometheus.yml’ - ‘--web.enable-lifecycle’ ports: - “9090:9090” networks: - monitoring-net depends_on: - otel-collector grafana: image: grafana/grafana:latest container_name: grafana-genai ports: - “3000:3000” environment: - GF_SECURITY_ADMIN_PASSWORDadmin volumes: - grafana-storage:/var/lib/grafana networks: - monitoring-net depends_on: - prometheus networks: monitoring-net: volumes: grafana-storage:步骤 3配置 Prometheus创建prometheus.yml配置文件让它去抓取 Collector 暴露的指标。# prometheus.yml global: scrape_interval: 15s evaluation_interval: 15s scrape_configs: - job_name: ‘otel-collector’ static_configs: - targets: [‘otel-collector:8889’] # 注意这里使用 Docker 服务名步骤 4启动所有服务在包含以上三个配置文件的目录下运行命令docker-compose up -d启动后你可以通过以下命令检查服务状态docker-compose ps如果一切正常你应该能看到三个服务都处于Up状态。此时OpenTelemetry Collector 已在运行并加载了我们配置的 GenAI 指标处理器。5. 功能测试与效果验证现在我们需要一个能产生追踪数据的 GenAI 应用来验证整个流程。这里用一个简单的 Python 脚本模拟调用 OpenAI API实际调用可替换为测试模型或模拟响应。步骤 1准备测试应用环境创建一个新的 Python 虚拟环境并安装依赖。mkdir genai-test-app cd genai-test-app python -m venv venv source venv/bin/activate # Linux/macOS # venv\Scripts\activate # Windows pip install opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp opentelemetry-instrumentation-openai # 安装 openai 库如果你有真实的 API Key 想测试 # pip install openai步骤 2编写测试脚本创建一个test_genai_trace.py文件。这个脚本使用 OpenTelemetry 的自动插桩来包装 OpenAI 客户端并将追踪数据发送到我们刚启动的 Collector。# test_genai_trace.py import time from opentelemetry import trace 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.instrumentation.openai import OpenAIInstrumentor # 设置追踪提供商和导出器 trace.set_tracer_provider(TracerProvider()) otlp_exporter OTLPSpanExporter(endpoint“http://localhost:4318/v1/traces”) # 指向本地 Collector span_processor BatchSpanProcessor(otlp_exporter) trace.get_tracer_provider().add_span_processor(span_processor) # 自动插桩 OpenAI 客户端 OpenAIInstrumentor().instrument() # 模拟一个 GenAI 调用这里不真实调用 API而是模拟一个 span tracer trace.get_tracer(__name__) with tracer.start_as_current_span(“genai_chat_completion”) as span: # 在 Span 属性中设置 GenAI 相关的语义属性 # 这些属性会被后端的 genai-metrics 处理器识别并提取为指标 span.set_attribute(“genai.system”, “openai”) span.set_attribute(“genai.request.model”, “gpt-4”) span.set_attribute(“genai.request.prompt”, “Explain quantum computing in simple terms.”) span.set_attribute(“genai.request.prompt_length”, 10) # 模拟提示词长度 span.set_attribute(“genai.response.id”, “chatcmpl-123”) # 模拟处理时间 time.sleep(0.5) span.set_attribute(“genai.response.finish_reason”, “stop”) span.set_attribute(“genai.usage.prompt_tokens”, 15) span.set_attribute(“genai.usage.completion_tokens”, 150) span.set_attribute(“genai.usage.total_tokens”, 165) print(“模拟的 GenAI 追踪 Span 已创建并发送。”) # 保持程序运行一段时间让数据被导出 time.sleep(2) print(“测试完成。”)步骤 3运行测试脚本运行脚本它会向http://localhost:4318发送一个包含 GenAI 语义属性的追踪 Span。python test_genai_trace.py步骤 4验证指标生成首先检查 Collector 的指标端点是否已有数据。访问http://localhost:8889/metrics你应该能看到一个 Prometheus 格式的指标页面。搜索genai_或otel_genai根据配置的 namespace开头的指标例如otel_genai_genai_request_duration_bucketotel_genai_genai_token_usage_input_totalotel_genai_genai_token_usage_output_total如果能看到这些指标说明genai-metrics处理器工作正常成功从 Trace 中生成了指标。步骤 5在 Prometheus 中查询访问http://localhost:9090进入 Prometheus 的 Graph 页面。在查询框中输入otel_genai_genai_request_duration_sum或rate(otel_genai_genai_token_usage_input_total[5m])等表达式尝试执行查询。如果能看到数据说明 Prometheus 已成功从 Collector 抓取指标。步骤 6在 Grafana 中可视化访问http://localhost:3000使用admin/admin登录。添加数据源选择 PrometheusURL 填写http://prometheus:9090注意在 Docker 网络内使用服务名保存并测试。创建仪表板新建一个 Dashboard添加一个 Panel。在 Panel 的 Query 中选择刚才添加的 Prometheus 数据源输入 PromQL 查询语句例如sum(rate(otel_genai_genai_token_usage_input_total[5m])) by (genai_request_model)。这可以按模型查看输入 Token 的消耗速率。配置图表类型如图表、统计面板等、标题和单位。保存仪表板。至此你已完成了从 GenAI 应用发出一条追踪到在 Grafana 上看到业务指标的全流程验证。6. 接口 API 与批量任务本项目本身不提供额外的对外 API它的“接口”就是标准的 OpenTelemetry Collector 的 OTLP 接收端口4317/4318和 Prometheus 指标暴露端口如8889。指标接口调用示例任何能访问 Collector 服务的 Prometheus 客户端或工具如curl都可以拉取指标。# 直接拉取原始的 Prometheus 指标数据 curl http://localhost:8889/metrics | grep genai对于批量任务监控关键在于你的 GenAI 应用本身。如果你有一个批量处理任务例如用 AI 批量总结1000篇文档你需要确保该任务的每次 AI 调用都生成了 OpenTelemetry Trace。genai-metrics处理器会自动聚合这些调用的指标。批量任务集成建议在任务中初始化全局 TracerProvider确保所有子调用都在同一个 Trace 上下文中或生成独立的 Spans。为关键属性打标在 Span 中设置清晰的属性如batch_id、document_id、task_type这些属性可以被处理器提取为指标标签便于在 Grafana 中按不同维度筛选和聚合。监控任务队列结合其他指标如通过batch处理器或自定义指标监控待处理队列长度、任务处理速率等。7. 资源占用与性能观察作为 OpenTelemetry Collector 的一个处理器其资源占用主要取决于 Trace 的吞吐量和配置的指标复杂度。观察方法Collector 自身指标OpenTelemetry Collector 默认会暴露自身的运行指标端口8888。你可以配置 Prometheus 也抓取这个目标监控otelcol_processor相关的指标如otelcol_processor_refused_spans、otelcol_processor_batch_batch_send_size等来观察genai-metrics处理器是否有异常。系统资源监控使用docker stats或宿主机监控工具如htop观察otel-collector容器的 CPU 和内存使用情况。docker stats otel-collector-genai处理延迟在 Trace 流水线中加入genai-metrics处理器会引入轻微的处理延迟。可以通过对比处理器前后 Span 的时间戳来评估但这通常需要更细致的测试。性能优化建议合理使用批处理确保在genai-metrics处理器之前或之后配置batch处理器可以有效减少对外部系统的写入压力提升吞吐量。精简指标和标签在genai-metrics处理器配置中只生成你真正关心的指标。避免将非常高基数的数据如完整的、未哈希的提示词作为标签这会导致 Prometheus 时序爆炸。调整 Collector 资源限制在 Docker Compose 或 K8s 部署中为otel-collector服务设置合理的 CPU 和内存限制与请求。8. 常见问题与排查方法在部署和集成过程中你可能会遇到以下问题问题现象可能原因排查方式解决方案Collector 启动失败配置文件错误YAML 格式错误或处理器名称/配置项不正确。查看 Collector 容器日志docker logs otel-collector-genai。错误信息通常会明确指出哪一行配置有问题。根据日志修正otel-collector-config.yaml文件。确保处理器名称与项目提供的名称一致。访问http://localhost:8889/metrics无genai_指标1. 处理器未正确加入tracespipeline。2. 测试应用没有发送 Trace 数据。3. Trace 数据中没有包含处理器能识别的 GenAI 语义属性。1. 确认配置中pipelines.traces.processors包含genai-metrics。2. 检查测试应用是否运行并确认 OTLP 端点地址正确。3. 查看 Collector 的debug导出器日志如果配置了确认收到的 Span 及其属性。1. 修正 pipeline 配置。2. 确保测试应用网络可通并重新运行。3. 确保 Span 中设置了正确的属性如genai.system,genai.request.model等属性名需与处理器期望的匹配。Prometheus 抓取不到指标UP状态为0Prometheus 配置中的 target 地址错误或网络不通。1. 访问 Prometheus UI (:9090)进入Status - Targets页面查看otel-collectorjob 的状态。2. 进入 Prometheus 容器内部尝试curl http://otel-collector:8889/metrics。1. 检查prometheus.yml中targets地址是否正确。在 Docker Compose 中应使用服务名otel-collector。2. 确保prometheus和otel-collector服务在同一个 Docker 网络monitoring-net中。Grafana 中查询不到数据1. Grafana 数据源配置错误。2. PromQL 查询语句错误。3. 时间范围选择不对。1. 在 Grafana 中测试 Prometheus 数据源连接。2. 先在 Prometheus UI 中验证相同的查询语句是否能返回数据。3. 检查 Grafana 面板右上角的时间范围是否覆盖了数据产生的时间。1. 修正数据源 URL 为http://prometheus:9090。2. 从简单的查询开始如up{job“otel-collector”}。3. 将时间范围调整为“最近1小时”或更宽。处理器导致 Collector 内存或 CPU 占用过高1. Trace 流量过大。2. 配置了过多或过于复杂的指标提取规则。3. 标签基数过高。1. 监控容器资源使用情况。2. 查看 Collector 的debug日志看是否有大量错误或警告。3. 检查生成的指标数量在 Prometheus 的http://localhost:9090/metrics端点查看。1. 考虑对 Trace 进行采样。2. 简化处理器配置只保留核心指标。3. 对高基数标签如提示词进行哈希或移除。9. 最佳实践与使用建议将 GenAI 指标监控引入生产环境除了技术集成还需考虑工程实践和合规性。从关键指标开始不要试图一开始就监控所有维度。优先关注延迟Latency、错误率Error Rate、Token 消耗Token Usage和调用量Throughput。这些是衡量服务健康度和成本的核心。定义清晰的属性规范在开发 GenAI 应用时团队应约定一套标准的 Span 属性命名规范如genai.request.model,genai.user.id_hash。这能确保处理器能稳定地提取指标也便于后续查询。重视数据脱敏与隐私原始提示词可能包含用户隐私、商业机密或 PII 信息。强烈建议在处理器配置中启用提示词哈希如hash_prompt: true或完全不将其作为标签仅用于聚合计算。合规性应放在首位。与现有告警体系集成在 Grafana 中为关键指标如 P95延迟 5s错误率 1%设置告警规则并通知到你的团队常用渠道如 Slack、钉钉、PagerDuty。进行容量规划估算你的 Trace 吞吐量并据此为 OpenTelemetry Collector 和 Prometheus 分配合适的计算和存储资源。高基数的指标标签会显著增加 Prometheus 的存储压力。建立监控仪表板创建专门的 GenAI 服务监控看板将延迟、Token 成本、模型使用分布、错误类型等视图放在一起为研发、运维和产品团队提供统一的可观测性视角。10. 总结与下一步这个基于 OpenTelemetry Trace 生成 GenAI 指标的项目为监控 AI 应用性能与成本提供了一个优雅且低侵入性的解决方案。它最大的价值在于复用现有的、日益普及的 OpenTelemetry 可观测性体系避免了为 AI 调用单独搭建一套监控的重复劳动。通过本文的演示你应该已经掌握了从零部署、配置到验证的完整流程。最值得尝试的第一步是在你的开发或测试环境中将一个简单的 AI 调用接入 OpenTelemetry并配置本文所述的流水线亲眼看到业务指标在 Grafana 上出现。这个闭环的打通是构建更复杂 AI 可观测性能力的基础。最容易踩的坑主要集中在配置环节OTLP 端口是否正确、处理器是否加入正确的 Pipeline、Span 属性命名是否匹配。按照第8部分的排查清单大部分问题都能快速定位。接下来你可以探索更深入的方向指标深化根据业务需求定制提取更多维度的指标如不同功能模块聊天 vs. 总结的 Token 成本对比。与 LLM 评估集成将监控指标与 LLM 响应质量的人工评估或自动评估结果关联分析提示词修改对成本和质量的综合影响。多环境管理将这套监控方案集成到你的 CI/CD 或 Kubernetes 集群中实现不同环境开发、预发、生产的统一监控。将可观测性融入 GenAI 应用的开发运维流程不再是“可有可无”而是保障服务稳定性、优化用户体验和控制成本的关键实践。这个项目提供了一个扎实的起点。
基于OpenTelemetry的GenAI应用监控：从链路追踪到业务指标自动生成
这次我们来看一个面向 GenAI 应用的可观测性开源项目。它的核心目标很直接从 OpenTelemetry 链路追踪数据中自动提取并生成有业务意义的 GenAI 指标比如提示词长度、模型响应延迟、Token 消耗等并直接对接 Prometheus 和 Grafana 进行监控告警。对于正在开发或运维 AI 应用如聊天机器人、内容生成、智能客服的团队来说手动埋点统计这些指标既繁琐又容易遗漏。这个项目试图解决的就是这个问题——它不是一个全新的监控系统而是一个基于现有 OpenTelemetry 生态的“指标提取器”和“边界定义器”。你不需要改造大量业务代码只需要确保你的 GenAI 调用比如通过 LangChain、LlamaIndex 或直接调用 OpenAI/ Anthropic API接入了 OpenTelemetry 分布式追踪这个工具就能从追踪数据中“读懂”你的 AI 交互过程并产出关键指标。本文将带你快速了解这个项目的核心能力、适用场景并重点演示如何在一个模拟的 GenAI 应用环境中从零搭建 OpenTelemetry Collector配置这个处理器最终在 Grafana 面板上看到实时的提示词性能与成本指标。整个过程会重点关注其部署门槛、配置方式、指标效果以及如何集成到现有监控体系。如果你关心如何低成本、无侵入地对 AI 应用进行精细化监控这篇文章值得一看。1. 核心能力速览能力项说明项目类型OpenTelemetry Collector 处理器Processor核心功能解析 OpenTelemetry Trace提取 GenAI 相关语义信息如原始提示词、模型名称、Token 数并生成 Prometheus 格式的指标。输入依赖必须已有生成 OpenTelemetry Trace 的 GenAI 应用。支持通过 SDK如opentelemetry-sdk或自动插桩如opentelemetry-instrumentation-openai产生的追踪数据。输出目标生成 Prometheus 可抓取的指标端点/metrics或通过 OTLP 导出器转发。关键指标预计包含请求延迟、Token 消耗输入/输出、提示词长度、模型调用次数、错误率等并可基于原始提示词内容进行分组或过滤。部署模式作为 OpenTelemetry Collector 的一个组件运行支持二进制、Docker 容器化部署。配置复杂度中等。需要理解 OpenTelemetry Collector 配置语法并正确设置处理器链。适合场景需要对 GenAI 应用进行生产级监控、成本分析、性能调优和提示词工程效果评估的团队。2. 适用场景与使用边界这个工具不是万能的它精准地定位于一个细分领域为已经采用 OpenTelemetry 进行链路追踪的 GenAI 应用补充业务视角的指标监控。它非常适合以下场景成本监控与优化团队需要监控不同模型、不同提示词模板的 Token 消耗以优化使用策略和控制 API 成本。性能与稳定性监控实时查看模型调用的延迟、错误率快速定位是模型服务方问题还是自身应用逻辑问题。提示词工程分析通过关联指标与原始提示词或其哈希值分析不同提示词长度、结构对响应质量和延迟的影响。SLA 保障为面向用户的 AI 功能定义服务等级指标如 P99 延迟 2s并配置告警。它的使用边界也很清晰非侵入式但有前提它不要求修改核心业务逻辑但要求应用必须先接入 OpenTelemetry Tracing。如果你的应用还没有链路追踪需要先完成这一步。指标而非日志它产出的是聚合后的指标如每秒请求数、平均延迟而不是包含完整上下文和错误的原始日志。深度调试仍需结合 Jaeger 等链路查询工具和应用的日志。依赖现有生态它本身不存储数据指标需要由 Prometheus 抓取再由 Grafana 展示。因此你需要一个基本的 Prometheus Grafana 监控栈。隐私与安全该工具会处理原始的提示词raw prompts。在生产环境中必须谨慎考虑数据脱敏。通常建议对提示词进行哈希处理后再作为指标标签以避免在监控系统中泄露敏感信息。3. 环境准备与前置条件在开始部署和测试之前请确保你的环境满足以下基础要求。我们将以一个本地测试环境为例进行说明。操作系统支持 Linux、macOS 和 Windows。本文演示基于 Ubuntu 22.04但步骤具有普适性。容器运行时可选但推荐Docker 和 Docker Compose。这能极大简化 OpenTelemetry Collector、Prometheus 和 Grafana 的部署。目标监控应用一个能够产生 OpenTelemetry 追踪数据的 GenAI 应用。作为演示我们可以使用一个简单的 Python 脚本它使用openai库并通过opentelemetry-instrumentation-openai自动插桩。网络与端口OpenTelemetry Collector: 默认需要开放接收 Trace 的端口如4318用于 OTLP/gRPC4317用于 OTLP/http。Prometheus: 默认端口9090用于抓取 Collector 暴露的指标。Grafana: 默认端口3000用于可视化。确保这些端口在本地或测试服务器上可用无冲突。基础工具git用于克隆项目curl或wget用于测试 以及文本编辑器。4. 安装部署与启动方式整个系统的架构如下GenAI 应用-OpenTelemetry Collector (包含 Bounded GenAI Metrics Processor)-Prometheus-Grafana。我们将使用 Docker Compose 一键部署 Collector、Prometheus 和 Grafana。你需要手动准备 Collector 的配置文件。步骤 1获取 OpenTelemetry Collector 配置首先你需要编写一个otel-collector-config.yaml文件。关键点在于在processors部分添加这个genai-metrics处理器并在pipelines中启用它。# otel-collector-config.yaml receivers: otlp: protocols: grpc: endpoint: 0.0.0.0:4317 http: endpoint: 0.0.0.0:4318 processors: # 批处理处理器优化性能 batch: # 核心GenAI 指标处理器 # 注意处理器名称和具体配置参数需根据项目实际文档调整 genai-metrics: # 示例配置启用对 OpenAI 和 Anthropic 调用的解析 enabled_platforms: [openai, anthropic] # 将原始提示词作为标签时进行哈希保护隐私 hash_prompt: true # 要提取的指标列表 metrics: - name: genai.request.duration type: histogram unit: ms description: “GenAI 请求耗时” - name: genai.token.usage.input type: counter unit: token description: “输入 Token 消耗” - name: genai.token.usage.output type: counter unit: token description: “输出 Token 消耗” exporters: # 将处理后的 Trace 继续向后传递如到 Jaeger otlp/traces: endpoint: jaeger:4317 tls: insecure: true # 将生成的指标以 Prometheus 格式暴露出来 prometheus: endpoint: “0.0.0.0:8889” namespace: otel_genai # 也可以将指标通过 OTLP 导出 debug: service: pipelines: traces: receivers: [otlp] processors: [batch, genai-metrics] # 在此处加入 genai-metrics 处理器 exporters: [debug, otlp/traces] metrics: receivers: [otlp] processors: [batch] exporters: [debug, prometheus]步骤 2创建 Docker Compose 文件创建一个docker-compose.yaml文件定义三个服务。# docker-compose.yaml version: ‘3.8’ services: otel-collector: image: otel/opentelemetry-collector-contrib:latest container_name: otel-collector-genai command: [“--config/etc/otel-collector-config.yaml”] volumes: - ./otel-collector-config.yaml:/etc/otel-collector-config.yaml ports: - “4317:4317” # OTLP gRPC - “4318:4318” # OTLP HTTP - “8889:8889” # Prometheus metrics endpoint networks: - monitoring-net prometheus: image: prom/prometheus:latest container_name: prometheus-genai volumes: - ./prometheus.yml:/etc/prometheus/prometheus.yml command: - ‘--config.file/etc/prometheus/prometheus.yml’ - ‘--web.enable-lifecycle’ ports: - “9090:9090” networks: - monitoring-net depends_on: - otel-collector grafana: image: grafana/grafana:latest container_name: grafana-genai ports: - “3000:3000” environment: - GF_SECURITY_ADMIN_PASSWORDadmin volumes: - grafana-storage:/var/lib/grafana networks: - monitoring-net depends_on: - prometheus networks: monitoring-net: volumes: grafana-storage:步骤 3配置 Prometheus创建prometheus.yml配置文件让它去抓取 Collector 暴露的指标。# prometheus.yml global: scrape_interval: 15s evaluation_interval: 15s scrape_configs: - job_name: ‘otel-collector’ static_configs: - targets: [‘otel-collector:8889’] # 注意这里使用 Docker 服务名步骤 4启动所有服务在包含以上三个配置文件的目录下运行命令docker-compose up -d启动后你可以通过以下命令检查服务状态docker-compose ps如果一切正常你应该能看到三个服务都处于Up状态。此时OpenTelemetry Collector 已在运行并加载了我们配置的 GenAI 指标处理器。5. 功能测试与效果验证现在我们需要一个能产生追踪数据的 GenAI 应用来验证整个流程。这里用一个简单的 Python 脚本模拟调用 OpenAI API实际调用可替换为测试模型或模拟响应。步骤 1准备测试应用环境创建一个新的 Python 虚拟环境并安装依赖。mkdir genai-test-app cd genai-test-app python -m venv venv source venv/bin/activate # Linux/macOS # venv\Scripts\activate # Windows pip install opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp opentelemetry-instrumentation-openai # 安装 openai 库如果你有真实的 API Key 想测试 # pip install openai步骤 2编写测试脚本创建一个test_genai_trace.py文件。这个脚本使用 OpenTelemetry 的自动插桩来包装 OpenAI 客户端并将追踪数据发送到我们刚启动的 Collector。# test_genai_trace.py import time from opentelemetry import trace 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.instrumentation.openai import OpenAIInstrumentor # 设置追踪提供商和导出器 trace.set_tracer_provider(TracerProvider()) otlp_exporter OTLPSpanExporter(endpoint“http://localhost:4318/v1/traces”) # 指向本地 Collector span_processor BatchSpanProcessor(otlp_exporter) trace.get_tracer_provider().add_span_processor(span_processor) # 自动插桩 OpenAI 客户端 OpenAIInstrumentor().instrument() # 模拟一个 GenAI 调用这里不真实调用 API而是模拟一个 span tracer trace.get_tracer(__name__) with tracer.start_as_current_span(“genai_chat_completion”) as span: # 在 Span 属性中设置 GenAI 相关的语义属性 # 这些属性会被后端的 genai-metrics 处理器识别并提取为指标 span.set_attribute(“genai.system”, “openai”) span.set_attribute(“genai.request.model”, “gpt-4”) span.set_attribute(“genai.request.prompt”, “Explain quantum computing in simple terms.”) span.set_attribute(“genai.request.prompt_length”, 10) # 模拟提示词长度 span.set_attribute(“genai.response.id”, “chatcmpl-123”) # 模拟处理时间 time.sleep(0.5) span.set_attribute(“genai.response.finish_reason”, “stop”) span.set_attribute(“genai.usage.prompt_tokens”, 15) span.set_attribute(“genai.usage.completion_tokens”, 150) span.set_attribute(“genai.usage.total_tokens”, 165) print(“模拟的 GenAI 追踪 Span 已创建并发送。”) # 保持程序运行一段时间让数据被导出 time.sleep(2) print(“测试完成。”)步骤 3运行测试脚本运行脚本它会向http://localhost:4318发送一个包含 GenAI 语义属性的追踪 Span。python test_genai_trace.py步骤 4验证指标生成首先检查 Collector 的指标端点是否已有数据。访问http://localhost:8889/metrics你应该能看到一个 Prometheus 格式的指标页面。搜索genai_或otel_genai根据配置的 namespace开头的指标例如otel_genai_genai_request_duration_bucketotel_genai_genai_token_usage_input_totalotel_genai_genai_token_usage_output_total如果能看到这些指标说明genai-metrics处理器工作正常成功从 Trace 中生成了指标。步骤 5在 Prometheus 中查询访问http://localhost:9090进入 Prometheus 的 Graph 页面。在查询框中输入otel_genai_genai_request_duration_sum或rate(otel_genai_genai_token_usage_input_total[5m])等表达式尝试执行查询。如果能看到数据说明 Prometheus 已成功从 Collector 抓取指标。步骤 6在 Grafana 中可视化访问http://localhost:3000使用admin/admin登录。添加数据源选择 PrometheusURL 填写http://prometheus:9090注意在 Docker 网络内使用服务名保存并测试。创建仪表板新建一个 Dashboard添加一个 Panel。在 Panel 的 Query 中选择刚才添加的 Prometheus 数据源输入 PromQL 查询语句例如sum(rate(otel_genai_genai_token_usage_input_total[5m])) by (genai_request_model)。这可以按模型查看输入 Token 的消耗速率。配置图表类型如图表、统计面板等、标题和单位。保存仪表板。至此你已完成了从 GenAI 应用发出一条追踪到在 Grafana 上看到业务指标的全流程验证。6. 接口 API 与批量任务本项目本身不提供额外的对外 API它的“接口”就是标准的 OpenTelemetry Collector 的 OTLP 接收端口4317/4318和 Prometheus 指标暴露端口如8889。指标接口调用示例任何能访问 Collector 服务的 Prometheus 客户端或工具如curl都可以拉取指标。# 直接拉取原始的 Prometheus 指标数据 curl http://localhost:8889/metrics | grep genai对于批量任务监控关键在于你的 GenAI 应用本身。如果你有一个批量处理任务例如用 AI 批量总结1000篇文档你需要确保该任务的每次 AI 调用都生成了 OpenTelemetry Trace。genai-metrics处理器会自动聚合这些调用的指标。批量任务集成建议在任务中初始化全局 TracerProvider确保所有子调用都在同一个 Trace 上下文中或生成独立的 Spans。为关键属性打标在 Span 中设置清晰的属性如batch_id、document_id、task_type这些属性可以被处理器提取为指标标签便于在 Grafana 中按不同维度筛选和聚合。监控任务队列结合其他指标如通过batch处理器或自定义指标监控待处理队列长度、任务处理速率等。7. 资源占用与性能观察作为 OpenTelemetry Collector 的一个处理器其资源占用主要取决于 Trace 的吞吐量和配置的指标复杂度。观察方法Collector 自身指标OpenTelemetry Collector 默认会暴露自身的运行指标端口8888。你可以配置 Prometheus 也抓取这个目标监控otelcol_processor相关的指标如otelcol_processor_refused_spans、otelcol_processor_batch_batch_send_size等来观察genai-metrics处理器是否有异常。系统资源监控使用docker stats或宿主机监控工具如htop观察otel-collector容器的 CPU 和内存使用情况。docker stats otel-collector-genai处理延迟在 Trace 流水线中加入genai-metrics处理器会引入轻微的处理延迟。可以通过对比处理器前后 Span 的时间戳来评估但这通常需要更细致的测试。性能优化建议合理使用批处理确保在genai-metrics处理器之前或之后配置batch处理器可以有效减少对外部系统的写入压力提升吞吐量。精简指标和标签在genai-metrics处理器配置中只生成你真正关心的指标。避免将非常高基数的数据如完整的、未哈希的提示词作为标签这会导致 Prometheus 时序爆炸。调整 Collector 资源限制在 Docker Compose 或 K8s 部署中为otel-collector服务设置合理的 CPU 和内存限制与请求。8. 常见问题与排查方法在部署和集成过程中你可能会遇到以下问题问题现象可能原因排查方式解决方案Collector 启动失败配置文件错误YAML 格式错误或处理器名称/配置项不正确。查看 Collector 容器日志docker logs otel-collector-genai。错误信息通常会明确指出哪一行配置有问题。根据日志修正otel-collector-config.yaml文件。确保处理器名称与项目提供的名称一致。访问http://localhost:8889/metrics无genai_指标1. 处理器未正确加入tracespipeline。2. 测试应用没有发送 Trace 数据。3. Trace 数据中没有包含处理器能识别的 GenAI 语义属性。1. 确认配置中pipelines.traces.processors包含genai-metrics。2. 检查测试应用是否运行并确认 OTLP 端点地址正确。3. 查看 Collector 的debug导出器日志如果配置了确认收到的 Span 及其属性。1. 修正 pipeline 配置。2. 确保测试应用网络可通并重新运行。3. 确保 Span 中设置了正确的属性如genai.system,genai.request.model等属性名需与处理器期望的匹配。Prometheus 抓取不到指标UP状态为0Prometheus 配置中的 target 地址错误或网络不通。1. 访问 Prometheus UI (:9090)进入Status - Targets页面查看otel-collectorjob 的状态。2. 进入 Prometheus 容器内部尝试curl http://otel-collector:8889/metrics。1. 检查prometheus.yml中targets地址是否正确。在 Docker Compose 中应使用服务名otel-collector。2. 确保prometheus和otel-collector服务在同一个 Docker 网络monitoring-net中。Grafana 中查询不到数据1. Grafana 数据源配置错误。2. PromQL 查询语句错误。3. 时间范围选择不对。1. 在 Grafana 中测试 Prometheus 数据源连接。2. 先在 Prometheus UI 中验证相同的查询语句是否能返回数据。3. 检查 Grafana 面板右上角的时间范围是否覆盖了数据产生的时间。1. 修正数据源 URL 为http://prometheus:9090。2. 从简单的查询开始如up{job“otel-collector”}。3. 将时间范围调整为“最近1小时”或更宽。处理器导致 Collector 内存或 CPU 占用过高1. Trace 流量过大。2. 配置了过多或过于复杂的指标提取规则。3. 标签基数过高。1. 监控容器资源使用情况。2. 查看 Collector 的debug日志看是否有大量错误或警告。3. 检查生成的指标数量在 Prometheus 的http://localhost:9090/metrics端点查看。1. 考虑对 Trace 进行采样。2. 简化处理器配置只保留核心指标。3. 对高基数标签如提示词进行哈希或移除。9. 最佳实践与使用建议将 GenAI 指标监控引入生产环境除了技术集成还需考虑工程实践和合规性。从关键指标开始不要试图一开始就监控所有维度。优先关注延迟Latency、错误率Error Rate、Token 消耗Token Usage和调用量Throughput。这些是衡量服务健康度和成本的核心。定义清晰的属性规范在开发 GenAI 应用时团队应约定一套标准的 Span 属性命名规范如genai.request.model,genai.user.id_hash。这能确保处理器能稳定地提取指标也便于后续查询。重视数据脱敏与隐私原始提示词可能包含用户隐私、商业机密或 PII 信息。强烈建议在处理器配置中启用提示词哈希如hash_prompt: true或完全不将其作为标签仅用于聚合计算。合规性应放在首位。与现有告警体系集成在 Grafana 中为关键指标如 P95延迟 5s错误率 1%设置告警规则并通知到你的团队常用渠道如 Slack、钉钉、PagerDuty。进行容量规划估算你的 Trace 吞吐量并据此为 OpenTelemetry Collector 和 Prometheus 分配合适的计算和存储资源。高基数的指标标签会显著增加 Prometheus 的存储压力。建立监控仪表板创建专门的 GenAI 服务监控看板将延迟、Token 成本、模型使用分布、错误类型等视图放在一起为研发、运维和产品团队提供统一的可观测性视角。10. 总结与下一步这个基于 OpenTelemetry Trace 生成 GenAI 指标的项目为监控 AI 应用性能与成本提供了一个优雅且低侵入性的解决方案。它最大的价值在于复用现有的、日益普及的 OpenTelemetry 可观测性体系避免了为 AI 调用单独搭建一套监控的重复劳动。通过本文的演示你应该已经掌握了从零部署、配置到验证的完整流程。最值得尝试的第一步是在你的开发或测试环境中将一个简单的 AI 调用接入 OpenTelemetry并配置本文所述的流水线亲眼看到业务指标在 Grafana 上出现。这个闭环的打通是构建更复杂 AI 可观测性能力的基础。最容易踩的坑主要集中在配置环节OTLP 端口是否正确、处理器是否加入正确的 Pipeline、Span 属性命名是否匹配。按照第8部分的排查清单大部分问题都能快速定位。接下来你可以探索更深入的方向指标深化根据业务需求定制提取更多维度的指标如不同功能模块聊天 vs. 总结的 Token 成本对比。与 LLM 评估集成将监控指标与 LLM 响应质量的人工评估或自动评估结果关联分析提示词修改对成本和质量的综合影响。多环境管理将这套监控方案集成到你的 CI/CD 或 Kubernetes 集群中实现不同环境开发、预发、生产的统一监控。将可观测性融入 GenAI 应用的开发运维流程不再是“可有可无”而是保障服务稳定性、优化用户体验和控制成本的关键实践。这个项目提供了一个扎实的起点。
