可观测性开箱即用：Archestra中OpenTelemetry追踪、Prometheus指标与日志体系全解析
【免费下载链接】archestraEnterprise AI Platform with guardrails, MCP registry, gateway & orchestrator项目地址: https://gitcode.com/gh_mirrors/ar/archestra
Archestra 是企业级 AI 平台（带 AI 护栏、MCP 注册中心、网关与编排器），它的可观测性开箱即用：内置 OpenTelemetry 分布式追踪、Prometheus 指标暴露与 OTLP 日志导出，配合官方 Grafana 仪表盘，无需自研监控代码，就能看清每一次 LLM 调用的延迟、Token 消耗与成本。本文带你完整走查这套 可观测性体系 的三大支柱。
为什么 AI 平台需要一套完整的可观测性
传统 Web 应用看 QPS 和错误率就够了，但 AI 平台多了一个"钱袋子"和"黑盒子"：
- 💰成本不可见：一次对话可能触发多轮 LLM 调用和 MCP 工具执行，不追踪就不知道哪个 Agent 在烧钱
- 🐢延迟难归因：用户抱怨"慢"，到底是模型首 Token 慢，还是平台自身的鉴权、护栏、工具调度慢？
- 🔍行为难审计：Agent 调用了哪些工具、传了什么参数、模型回了什么，出问题时拿不出证据
Archestra 用 OpenTelemetry（OTel）+ Prometheus + Loki 这套业界标准组合回答了以上三个问题，且全部以标准协议导出——你可以接 Jaeger、Tempo、Grafana Cloud 等任意 OTLP 兼容后端。
一张图看懂：指标、追踪、日志三条管道
Archestra 的可观测性数据流向如下：
- Web 进程在
http://localhost:9050/metrics暴露 Prometheus 格式指标；独立的Worker 进程（Helm 部署默认形态）在:9000/metrics暴露任务队列与知识库流水线指标 - 追踪与日志统一通过 OTLP 协议发到 OpenTelemetry Collector（默认
http://localhost:4318，追踪走/v1/traces，日志走/v1/logs） - Collector 将追踪写入Grafana Tempo、日志写入Loki，再由 Grafana 统一呈现
仓库里附带了一套开箱即用的开发环境编排，一条命令拉起 Tempo、Loki、OTel Collector、Prometheus、Grafana 全家桶：
- 编排文件：docker-compose.observability.yml
- Prometheus 抓取配置：prometheus.yml（每 10 秒抓取一次 Archestra 指标）
- Collector 管道配置：otel-collector-config.yaml
Prometheus 指标全解：LLM 成本与延迟一眼看清
核心 LLM 指标（建议优先关注）
| 指标名 | 含义 |
|---|---|
llm_request_duration_seconds | LLM 请求耗时，可按 provider、model、agent、状态码细分 |
llm_tokens_total | Token 消耗（input/output 分开计数） |
llm_cost_total | 美元成本估算，真实计费口径用sum(llm_cost_total{billing_mode="metered"}) |
llm_time_to_first_token_seconds | 首 Token 时间（TTFT），挑低延迟模型的好依据 |
llm_time_to_first_byte_seconds | 首字节时间，含平台自身鉴权/护栏开销，与 TTFT 对比即可分离"平台慢"还是"模型慢" |
llm_tokens_per_second | 输出吞吐（tokens/s） |
llm_active_users | 24h/7d 活跃用户数（跨副本聚合请用max()而非sum()） |
💡 小技巧：llm_cache_tokens_total、llm_cache_savings_total还能单独追踪提示词缓存省了多少钱，对重度使用长 System Prompt 的团队很实用。
其他值得接入告警的指标组
- MCP 指标：
mcp_tool_calls_total、mcp_tool_call_duration_seconds追踪工具调用成功率与耗时；mcp_server_deployment_status可统计自托管 MCP 服务器处于 running / hibernated 等状态的数量 - RAG / 知识库指标：
rag_connector_syncs_total、rag_embedding_batches_total、rag_query_duration_seconds覆盖同步、向量化到检索的全链路 - 任务队列指标：
task_queue_tasks_dead_total（进入死信队列）是最该告警的信号 - 应用层指标：HTTP 请求直方图、Node.js 事件循环滞后（
nodejs_eventloop_lag_seconds）、V8 堆内存、进程 CPU/内存
OpenTelemetry 分布式追踪：LLM 调用的全链路视角
只需一个环境变量开启
ARCHESTRA_OTEL_EXPORTER_OTLP_ENDPOINT=http://your-collector:4318支持 Bearer / Basic 认证（ARCHESTRA_OTEL_EXPORTER_OTLP_AUTH_*系列变量），不配置则匿名导出。
默认追踪什么
默认只采集 GenAI 相关的"干净"追踪，避免噪音：
- LLM API 调用——专属 Span 记录模型、Token、耗时，命名如
chat gpt-4o-mini - MCP 工具调用——
execute_tool {tool_name}，含被护栏拦截（mcp.blocked=true）的决策记录 - 知识库操作——Embedding / Rerank 调用同样有 Span 与成本追踪
- Skill 沙箱执行——Rust 原生运行时导出
service.name=archestra-sandbox-rs的 Span - 需要看 HTTP 路由等基础设施细节时，设置
ARCHESTRA_OTEL_VERBOSE_TRACING=true
会话级统一追踪：一次对话一棵树
内置 Chat 的每轮对话会生成一棵统一的追踪树：
chat {agentName} ← 父 Span ├── chat {model} ← LLM 调用 ├── execute_tool {工具名} ← MCP 工具执行 └── chat {model} ← 工具结果后的追问通过X-Archestra-Session-Id头传入会话 ID，即可按gen_ai.conversation.id把同一 Agent 会话的所有调用聚合到一条时间线上；无论入口是 Chat UI、A2A 协议、MS Teams 还是 Email，route.category与archestra.trigger.source都能帮你按渠道过滤。
两个实用特性
- 📸内容捕获：默认把 Prompt / Completion / 工具参数与结果记录为 Span 事件（单事件截断至 10,000 字符），便于完整审计；可用
ARCHESTRA_OTEL_CAPTURE_CONTENT=false关闭。若启用了静态内容加密，该项默认自动关闭，防止密文数据库的内容以明文外泄 - 🔗指标跳追踪（Exemplars）：所有 LLM 与 MCP 指标都携带追踪示例点，在 Grafana 中点击某个指标数据点可直接跳转到 Tempo 中对应的 Trace——从"发现异常"到"定位请求"只需一次点击
日志体系：从 OTel Collector 到 Loki 的闭环
Archestra 的日志不走"各容器 stdout 各自为政"的老路：OTel Collector 统一接收 OTLP 日志并转发到 Loki（Loki 3.x 原生支持 OTLP 摄取），开发环境的管道在 otel-collector-config.yaml 中定义。Grafana 数据源配置还开启了traces-to-logs 双向跳转：从一条追踪按service.name标签直接捞出相关日志，见 datasources.yml。
真用户监控（RUM）：把"用户怎么用"也变成日志
除基础设施遥测外，Archestra 还支持Real User Monitoring（企业版功能）：浏览器端事件经后端转发为你的 OTLP 日志记录，只需设置
ARCHESTRA_RUM_EXPORTER_OTLP_ENDPOINT=http://your-collector:4318捕获的事件是封闭白名单——session.start、page_view、Core Web Vitals（LCP/CLS/INP）、主线程长任务、客户端错误指纹、API 请求耗时等，且不包含聊天内容、姓名、原始 URL 等敏感信息，隐私友好。在 Grafana + Loki 中按{service_name="Archestra Web"}查询即可搭建用量看板：
5 个官方 Grafana 仪表盘，克隆即用
平台内置 5 个覆盖全场景的仪表盘 JSON，位于 platform/dev/grafana/dashboards/：
| 仪表盘 | 关注点 |
|---|---|
| GenAI Observability | LLM 请求、Token、成本、延迟与追踪 |
| MCP Monitoring | 工具调用成功率、错误率、耗时 |
| Agent Sessions | 会话级审计，可下钻 LLM 调用 / 工具调用 / 关联日志 |
| Application Metrics | HTTP 流量、Node.js 健康、任务队列、PostgreSQL |
| RAG & Knowledge Base | 连接器同步、Embedding 管道、检索性能 |
配合 install-dashboards.sh 脚本可一键导入全部仪表盘（幂等，可重复执行），并通过--postgres-provider适配 OTel Collector / Cloud SQL / Azure 等不同数据库指标来源。
快速上手：三步搭好最小可观测性环境
- 启动全家桶：运行
docker compose -f platform/dev/docker-compose.observability.yml up -d，Grafana 监听 3002 端口 - 指向 Collector：给 Archestra 后端设置
ARCHESTRA_OTEL_EXPORTER_OTLP_ENDPOINT（本地开发时默认http://localhost:4318即可） - 验证闭环：发起一次 Chat 对话 → 打开 Grafana 的 GenAI Observability 面板 → 点击
llm_request_duration_seconds的某个数据点 → 通过 Exemplar 直达 Tempo 中的完整追踪 → 再按 trace ID 捞出 Loki 日志
🎯 生产环境（Helm 部署）提醒：worker 是独立进程，请确保抓取配置同时覆盖 web 的:9050与 worker 的:9000两个指标端点，否则任务队列与知识库流水线指标会缺失。
小结
Archestra 把企业级 AI 平台最头疼的"看得见、算得清、查得到"做成了默认能力：Prometheus 指标回答"花了多少钱、快不快"，OpenTelemetry 追踪回答"这次调用到底发生了什么"，Loki 日志与 RUM回答"用户和产品实际表现如何"。三者共享同一套 OTLP 管道与 Grafana 呈现层，标准协议意味着你可以随时替换后端，而不必改动一行平台代码。
📖 更多细节请查阅官方文档：platform-observability.md，部署相关环境变量见 platform-deployment.md 的Observability & Metrics章节。
【免费下载链接】archestraEnterprise AI Platform with guardrails, MCP registry, gateway & orchestrator项目地址: https://gitcode.com/gh_mirrors/ar/archestra
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
