AI导哈

OpenTelemetry 追踪访问服务

otel-mcp 是一个为AI代理提供应用程序OpenTelemetry追踪数据访问的服务，支持查询追踪、查找错误和识别慢操作。

  • by moondef
  • TypeScript
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 moondef/otel-mcp

使用说明

Otel mcp

MCP服务器，允许AI代理访问应用程序的OpenTetry跟踪。

Agent calls: list_traces { has_errors: true }

Recent Traces (2 of 847)

TRACE ID          SERVICE        DURATION     SPANS  ERRORS  ROOT
a]b7f2e9d4c8      checkout-api      2.34s        12       1  POST /checkout
f3e1a8b2c6d9      checkout-api      1.87s         8       1  POST /checkout

Agent calls: get_trace { trace_id: "a]b7f2e9d4c8" }

Trace ab7f2e9d4c8

Services: checkout-api, inventory-service, postgres
Duration: 2.34s
Spans: 12, 1 error

SPAN TREE
----------------------------------------------------------------
[2.34s] POST /checkout
  [1.92s] OrderService.create
    [1.87s] InventoryService.reserve  ← HTTP 500
      [45ms] POST inventory-service/reserve
    [23ms] pg.query SELECT * FROM products...
  [412ms] PaymentService.charge
    [401ms] stripe.charges.create

该代理可以查询跟踪、查找错误、识别慢速操作，而无需将日志复制到聊天中。

为什么存在

AI代理可以读取代码，但看不到它是如何执行的。在本地调试时，您最终会自己检查跟踪并解释发现的内容。这就是瓶颈。

otel mcp通过让代理直接查询执行数据来消除这一步骤。

阅读更多：

建筑

flowchart LR
    subgraph app["Your Application"]
        OTel["OpenTelemetry SDK"]
    end

    subgraph otel-mcp
        Receiver["OTLP Receiver\n/v1/traces"]
        Store[("Trace Store\n(in-memory)")]
        MCP["MCP Server\n(stdio)"]
        HTTP["HTTP API\n/mcp/*"]
    end

    subgraph client["Client Mode"]
        MCP2["MCP Server\n(stdio)"]
    end

    Agent["AI Agent\n(Claude, Cursor)"]

    OTel -->|"OTLP/HTTP\n:4318"| Receiver
    Receiver --> Store
    Store --> MCP
    Store --> HTTP
    MCP <-->|"MCP protocol"| Agent
    HTTP <-->|"HTTP proxy"| MCP2
    MCP2 <-->|"MCP protocol"| Agent

主要模式：第一个实例运行OTLP接收器和MCP服务器。通过LRU驱逐将痕迹存储在内存中。

客户端模式：其他实例通过健康检查和HTTP上的代理MCP工具调用检测主实例。多个AI代理可以共享相同的跟踪数据。

快速开始

先决条件：Node.js 18+

1.添加到您的MCP客户端

Cursor

首选 光标设置 → 主控程序 → 添加新的全局MCP服务器 并粘贴：

{
  "mcpServers": {
    "otel": { "command": "npx", "args": ["otel-mcp"] }
  }
}

或添加到 ~/.cursor/mcp.json 直接。

Claude Code 
claude mcp add otel -- npx otel-mcp
Other MCP clients

添加到MCP配置中：

{
  "mcpServers": {
    "otel": { "command": "npx", "args": ["otel-mcp"] }
  }
}

2.试试看

运行示例应用程序以生成测试跟踪：

# Clone and run example
git clone https://github.com/moondef/otel-mcp.git
cd otel-mcp/examples/node-app
npm install && npm start

然后问你的AI代理： “显示最近的痕迹” 或 “有什么错误吗？”

3.检测你的应用程序

将您的OpenTetry导出器指向 http://localhost:4318/v1/traces:

Node.js 
import { NodeSDK } from '@opentelemetry/sdk-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';

const sdk = new NodeSDK({
  traceExporter: new OTLPTraceExporter({
    url: 'http://localhost:4318/v1/traces',
  }),
  instrumentations: [getNodeAutoInstrumentations()],
});
sdk.start();
Python 
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
exporter = OTLPSpanExporter(endpoint="http://localhost:4318/v1/traces")
New to OpenTelemetry?

OpenTetry是从应用程序收集跟踪的标准。跟踪显示了请求在系统中的路径——运行了哪些函数，每个函数花了多长时间，失败了什么。

开始： Node.js · python · 去 · Java

工具

工具 说明
list_traces 列出最近的痕迹。筛选依据 service, has_errors, min_duration_ms, since_minutes.
get_trace 获取跟踪ID的span树（支持前缀匹配）。
query_spans 搜索范围为 where 表达： duration > 100, status = error, http.status_code >= 400.
get_summary 服务概述，包括跟踪计数和最近的错误。
clear_traces 清除所有收集到的痕迹。

多个会话

多个MCP客户端共享相同的跟踪。第一个实例在端口4318上运行收集器，其他实例连接到它。按以下条件筛选 service 专注于特定的应用程序。

配置

变量 默认值 描述
OTEL_MCP_PORT 4318 收集器端口
OTEL_MCP_MAX_TRACES 1000 要保留的最大痕迹数
OTEL_MCP_MAX_SPANS 10000 要保留的最大跨度

许可证

麻省理工学院

相关 MCP