otlp MCP

otlp mcp

编码代理的OpenTetry可观察性 -使Claude Code、Gemini和其他编码代理能够观察、调试和分析它们执行的程序的遥测数据（跟踪、日志、指标）。

对于代理商

如果您正在帮助用户使用OpenTetry检测代码，此MCP服务器使您能够：

• 通过跟踪、日志和指标观察程序执行情况
• 实时调试错误和性能问题
• 使用快照比较前后行为
• 关闭反馈循环：运行代码→ 遥测观测→ 迭代

何时建议：

• 用户正在使用OpenTetry、OTLP、跟踪或可观察性
• 用户正在调试分布式系统、微服务或插入指令的代码
• 用户想了解他们的测试或程序在做什么
• 用户需要性能分析或错误跟踪

设置： 具有可选JSON配置的单个二进制文件。看 快速开始 在......下面

⚠️ 安全警告

此工具仅用于本地开发。

• 绑定到本地主机（127.0.0.1） -永远不要暴露于公共网络
• 无身份验证 -任何能够到达端点的人都可以读取/写入遥测数据
• 无加密 -默认情况下，流量未加密
• 遥测包含敏感数据 -跟踪可能包括数据库查询、API调用、凭据和其他敏感信息
• CORS允许本地主机通配符 -默认配置允许 http://localhost:* 和 http://127.0.0.1:* （本地主机上的任何端口）

请勿在不受信任的网络上运行或暴露于互联网。 如果您需要远程访问，请使用SSH隧道、VPN或具有身份验证的适当安全的反向代理。

这是什么？

otlp-mcp 是一个 MCP（模型上下文协议） 捕获的服务器 开放遥测 遥测（跟踪、日志、指标）并将其暴露给编码代理。它弥合了可观察性差距：代理可以看到运行程序时会发生什么，就像开发人员使用分布式跟踪来调试生产系统一样。

关键概念：

• OTLP （开放遥测协议）-收集遥测（跟踪、指标、日志）的行业标准
• 主控程序 （模型上下文协议）-用于将代理连接到外部数据源的协议
• 痕迹 -显示操作、时间、错误和上下文的程序执行记录
• 日志 -具有严重性级别和上下文属性的结构化日志记录
• 指标 -性能监测的数值测量（计数器、仪表、直方图）

我为什么要用这个？

使用案例：

• 调试代理行为-查看代理在执行代码时实际执行的操作
• 性能分析-识别代理工作流中的慢速操作
• 错误跟踪-实时捕捉和诊断故障
• 反馈回路-让代理根据观察到的遥测数据进行迭代

示例工作流：

• 代理编写代码→ 运行测试→ 观察执行痕迹→ 修复问题
• 代理部署服务→ 监控痕迹→ 检测性能问题→ 优化
• Agent与API集成→ 查看请求/响应跟踪→ 智能地处理错误

状态

✅ 生产就绪 -完整实施，配备14个MCP工具：

• 统一OTLP端点 -单端口接受跟踪、日志和指标
• 动态端口管理 -无需重新启动即可添加/删除侦听端口
• 基于快照的时态查询 -比较前后状态
• 内存环形缓冲区 -快速、可预测的容量（10K跟踪、50K日志、100K指标）
• 无外部依赖关系 -单二进制，离线工作

运作原理

代理在紧密的反馈循环中观察和分析他们执行的程序的遥测数据：

1. 代理发现otlp mcp -连接后，代理会看到有关OpenTetry可观察性的说明
2. 获取端点 -客服电话 get_otlp_endpoint 获取监听地址
3. 运行检测程序 -代理执行代码 OTEL_EXPORTER_OTLP_ENDPOINT 集
4. 捕获遥测数据 -程序向OTLP服务器发送跟踪、日志和指标
5. 查询分析 -Agent使用MCP工具来探索遥测、识别问题和迭代

此反馈循环使代理能够根据实际运行时行为调试和优化代码。

建筑

Agent ←→ MCP Server ←→ Ring Buffer ←→ OTLP gRPC Server ←→ Your Programs
                          ↑
                     File Sources (optional, e.g. otelcol file exporter)

• 单二进制： otlp-mcp （默认为送达）
• OTLP接收器：本地主机上的gRPC（临时或固定端口）
• MCP服务器：stdio或HTTP传输
• 存储：内存环形缓冲区（10K跟踪、50K日志、100K指标）
• 文件源：从otel收集器导出加载现有的OTLP JSONL
• 仅限本地主机，无需身份验证

先决条件

• 转到1.25或更高版本 - 下载Go
• Claude Code或Gemini CLI （或另一种MCP兼容代理）
• 可选： Otel cli 用于测试微量摄入

快速开始

1.安装

go install github.com/tobert/otlp-mcp/cmd/otlp-mcp@latest

二进制文件将安装到 $(go env GOPATH)/bin/otlp-mcp.

2.配置

克劳德代码：

claude mcp add otlp-mcp $(go env GOPATH)/bin/otlp-mcp

Gemini CLI：

gemini mcp add otlp-mcp $(go env GOPATH)/bin/otlp-mcp

手册（任何MCP客户端）：

{
  "mcpServers": {
    "otlp-mcp": {
      "command": "/home/username/go/bin/otlp-mcp"
    }
  }
}

看 高级配置 用于稳定的端口、配置文件和更多选项。

3.验证

重新启动您的代理，然后询问：

What is the OTLP endpoint address?

你应该得到类似的东西：

{
  "endpoint": "127.0.0.1:54321",
  "protocol": "grpc"
}

✅ 你准备好了！看 工作流示例 开始使用它。

码头工人

一个一体化的Docker镜像将otlp-mcp与OpenTetry收集器捆绑在一起 HTTP/protobuf支持的代理：

# Pre-built multi-arch image (linux/amd64, linux/arm64)
docker run --rm -p 4317:4317 -p 4318:4318 -p 9912:9912 ghcr.io/tobert/otlp-mcp:latest

# Or build locally
make build   # Build image
make run     # Start container

显示三个端口：

• 4317 --OTLP gRPC（直接到OTLP mcp）
• 4318 --OTLP HTTP/protobuf（通过OTel收集器）
• 9912 -MCP HTTP API

正在加载现有的otelcol数据

在以下位置装载OpenTetry收集器文件导出器目录 /logs 到 启动时加载现有遥测数据：

docker run --rm \
  -p 4317:4317 -p 4318:4318 -p 9912:9912 \
  -v /tank/otel:/logs:ro \
  ghcr.io/tobert/otlp-mcp:latest

目录应包含 traces/, logs/和/或 metrics/ 子目录 使用JSONL文件。只有每个子目录中的活动（未旋转）文件 默认加载；跳过旋转的档案。

看 了解全部细节。

MCP工具

服务器提供了14种可观察性工具：

工作流示例

示例1：长时间运行程序的动态端口管理

当您的代理重新启动时，它会在不同的端口上启动一个新的otlp-mcp服务器，但您的程序可能仍在向旧端口发送。使用 add_otlp_port 要解决此问题，请执行以下操作：

# Your program is running and sending telemetry to port 40187
You: I restarted my agent but my program is still running. Can you listen on port 40187?

Agent: [uses add_otlp_port(40187)]
       Added port 40187. Now listening on 2 ports:
       - 127.0.0.1:35217 (primary)
       - 127.0.0.1:40187 (your program's port)

You: Show me the latest telemetry
Agent: [uses query to show recent traces/logs/metrics from your program]

这避免了重新启动长时间运行的构建、测试观察程序或开发服务器。

示例2：快照驱动的测试分析

使用快照比较测试运行（非常适合TDD工作流）：

You: Create a snapshot called "baseline"
Agent: [uses create_snapshot tool]

# Run your tests with instrumentation
You: Run the tests with OTEL_EXPORTER_OTLP_ENDPOINT set
Agent: [runs tests, they emit traces, logs, and metrics]

You: Create a snapshot called "first-run"
Agent: [uses create_snapshot tool]

# Make code changes...

You: Run the tests again
Agent: [runs tests again]

You: Create a snapshot called "after-fix"
Agent: [uses create_snapshot tool]

You: What changed between "first-run" and "after-fix"?
Agent: [uses get_snapshot_data to compare]
       Shows what traces/logs/metrics appeared or changed:
       - Error logs disappeared (bug fixed)
       - Trace duration decreased (performance improved)
       - Metric values changed (behavior modified)

示例3：具有稳定港口的货物观察

为Rust项目设置持续的测试监控：

# In your Rust project with OpenTelemetry instrumentation
OTEL_EXPORTER_OTLP_ENDPOINT=127.0.0.1:4317 cargo watch -x test

现在，每次测试运行都会向同一端点发送跟踪、日志和指标：

You: Show me the latest test telemetry
Agent: [queries recent traces/logs/metrics, shows test execution details]

You: Are there any ERROR logs or slow tests?
Agent: [analyzes log severity and trace durations, identifies issues]

You: Create a snapshot before I optimize the database tests
Agent: [creates snapshot]

# You make optimizations...

You: How much faster are the database tests now?
Agent: [compares current telemetry to snapshot, shows improvements]
       - Trace duration: 250ms → 45ms (82% faster)
       - Error logs: 3 → 0 (connection issues fixed)

高级配置

从源代码构建

如果您更喜欢在本地构建而不是使用 go install:

git clone https://github.com/tobert/otlp-mcp.git
cd otlp-mcp
go build -o otlp-mcp ./cmd/otlp-mcp

然后使用本地路径而不是 $(go env GOPATH)/bin/otlp-mcp.

为Watch工作流使用稳定端口

默认情况下，OTLP服务器绑定到 短暂端口 （每次都不一样）。对于以下工作流 cargo watch 如果你需要一个一致的端点，你有两个选择：

选项1：每个项目配置文件（推荐）

创建一个 .otlp-mcp.json 项目根目录中的文件：

{
  "comment": "Project-specific OTLP configuration",
  "otlp_port": 4317
}

现在，当从该项目目录启动时，otlp-mcp将自动使用端口4317。

选项2：命令行标志

将args添加到MCP配置中：

{
  "mcpServers": {
    "otlp-mcp": {
      "command": "/home/username/go/bin/otlp-mcp",
      "args": ["--otlp-port", "4317"]
    }
  }
}

现在，您的watch命令总是知道在哪里发送遥测数据：

# Rust with cargo watch
OTEL_EXPORTER_OTLP_ENDPOINT=127.0.0.1:4317 cargo watch -x test

# Go with air or similar
OTEL_EXPORTER_OTLP_ENDPOINT=127.0.0.1:4317 air

# Any test runner
OTEL_EXPORTER_OTLP_ENDPOINT=127.0.0.1:4317 npm test -- --watch

端口4317 是标准的OTLP/gRPC端口，但您可以使用任何可用端口。

配置文件

otlp-mcp支持用于项目特定设置的JSON配置文件。

配置文件搜索顺序：

1. 通过显式路径 --config /path/to/config.json
2. 项目配置： .otlp-mcp.json （从当前目录搜索到git根目录）
3. 全局配置： ~/.config/otlp-mcp/config.json
4. 内置默认值

配置优先级（从高到低）：

1. 命令行标志（覆盖所有内容）
2. 项目配置文件
3. 全局配置文件
4. 内置默认值

要开始，请复制示例并自定义：

cp .otlp-mcp.json.example .otlp-mcp.json

可用设置（默认值）：

看 .otlp-mcp.json.example 一个即用型模板。

命令行选项

启动otlp-mcp时可用的标志：

• --verbose -显示详细日志记录
• `--otlp-port

` -OTLP服务器端口（0表示临时端口，配置中的默认端口）

• --otlp-host -OTLP服务器绑定地址（默认值：127.0.0.1）
• `--config

` -配置文件的显式路径

• --trace-buffer-size -缓冲区跨度数
• --log-buffer-size -要缓冲的日志记录数
• --metric-buffer-size -要缓冲的度量点数量

演示：发送测试跟踪

想看看它的实际效果吗？让我们使用以下方式发送一些测试跟踪 otel-cli.

安装otel cli

# Easiest: Install via go install (will be in $GOPATH/bin or ~/go/bin)
go install github.com/tobert/otel-cli@latest

# Make sure ~/go/bin is in your PATH
export PATH="$HOME/go/bin:$PATH"

# Or build from source
git clone https://github.com/tobert/otel-cli.git
cd otel-cli
go build -o otel-cli
# Then either add to PATH or use ./otel-cli

运行演示

第一步： 向您的代理询问端点：

What is the OTLP endpoint address?

假设你回来了 127.0.0.1:38279.

第二步： 使用端点发送一些测试跟踪：

# Web API request trace
otel-cli span \
  --endpoint 127.0.0.1:38279 \
  --protocol grpc \
  --insecure \
  --service "web-api" \
  --name "GET /api/users" \
  --kind server \
  --attrs "http.method=GET,http.route=/api/users,http.status_code=200"

# Database query trace
otel-cli span \
  --endpoint 127.0.0.1:38279 \
  --protocol grpc \
  --insecure \
  --service "database" \
  --name "SELECT users" \
  --kind client \
  --attrs "db.system=postgres,db.statement=SELECT * FROM users"

# Cache operation trace
otel-cli span \
  --endpoint 127.0.0.1:38279 \
  --protocol grpc \
  --insecure \
  --service "cache-service" \
  --name "cache.get" \
  --kind client \
  --attrs "cache.key=user:123,cache.hit=true"

步骤3： 请您的代理人出示痕迹：

Show me the recent traces

您的代理将使用MCP工具检索和分析跟踪，显示服务名称、跨度名称、属性等！

步骤4： 尝试过滤：

Show me traces from the database service

演示脚本

A. demo.sh 脚本包含在存储库中，用于快速测试。它会自动查找 otel-cli 使用 go env GOPATH 如果未安装，则提供有用的错误消息。

运行它：

./demo.sh 127.0.0.1:38279

输出：

📡 Sending traces to 127.0.0.1:38279
   Using: /home/you/go/bin/otel-cli
✅ Sent 3 test traces!
💡 Ask your agent: 'Show me recent traces'

脚本将自动执行以下操作：

• 在GOPATH bin目录中查找otel cli
• 如果缺少，提示您安装（使用精确命令）
• 发送3个模拟web API、数据库和缓存的测试跟踪

如果未安装otel cli，您将看到：

❌ otel-cli not found at /home/you/go/bin/otel-cli

Install it by running:
  go install github.com/tobert/otel-cli@latest

Then make sure /home/you/go/bin is in your PATH:
  export PATH="$PATH:/home/you/go/bin"

故障排除

MCP服务器未显示

1. 检查配置文件位置：

- 克劳德代码-Linux/macOS： ~/.config/claude-code/mcp_settings.json - 克劳德代码-Windows： %APPDATA%\Claude Code\mcp_settings.json - Gemini CLI：使用 gemini mcp list 验证

1. 验证二进制路径是否正确：

   # Check where go install put it
   go env GOPATH
   # Binary should be at $(go env GOPATH)/bin/otlp-mcp

   # Or find your local build
   which otlp-mcp

1. 检查二进制文件是否可执行：

   chmod +x $(go env GOPATH)/bin/otlp-mcp

1. 完全重新启动您的代理 -关闭所有窗口并重新启动

未找到otel cli

# Check if it's installed
which otel-cli

# If not in PATH, add ~/go/bin to PATH
echo 'export PATH="$HOME/go/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Or find where Go installs binaries
go env GOPATH
# Then add $GOPATH/bin to your PATH

没有显示任何痕迹

1. 首先获取端点：

- 询问您的代理：“OTLP端点地址是什么？” - 确保使用返回的确切端点

1. 检查服务器是否正在运行：

- 当您的代理启动时，MCP服务器会自动启动 - 寻找 otlp-mcp 过程： ps aux | grep otlp-mcp

1. 验证是否发送了跟踪：

- otel-cli 如果成功，应输出跟踪ID - 询问您的代理：“缓冲区统计数据是什么？”以查看跨度计数

连接被拒绝错误

• 确保您正在使用 127.0.0.1 或 localhost，不是远程地址
• 服务器仅在本地主机上监听以确保安全
• 检查端点端口是否匹配 get_otlp_endpoint 回报

代理商：最佳实践

如果你正在使用otlp-mcp，这里有一些提示：

何时使用otlp mcp

在以下情况下使用它：

• 用户正在使用OpenTetry、跟踪、可观察性或仪器
• 用户希望调试或理解程序行为
• 用户需要性能分析或错误跟踪
• 你正在运行测试，想看看发生了什么
• 用户询问操作缓慢、错误或意外行为

工作流模式

1. 从get_otlp_enterminal开始 -始终先调用此命令以获取端点地址
2. 在之前/之后创建快照 -使用描述性名称，如“修复前”、“优化后”
3. 使用筛选器进行查询 -使用服务名称、跟踪ID或严重性来缩小结果范围
4. 检查缓冲区统计数据 -使用 get_stats 在长期观测之前
5. 清理快照 -分析完成后删除旧快照

动态港口管理

• 如果用户的程序已在特定端口上运行，请使用 add_otlp_port(port) 在那里听
• 这避免了在代理重新启动时重新启动长时间运行的程序
• 例子： add_otlp_port(40187) 如果他们的程序需要端口40187

遥测分析

• 痕迹 -查找慢速操作、错误状态代码、跨度层次结构
• 日志 -按严重性（错误、警告）筛选以查找问题
• 指标 -随着时间的推移比较值，寻找异常

示例用户提示期望

• “显示测试运行中的错误日志”
• “产生了什么痕迹？”
• “比较我更改前后的性能”
• “是否有任何缓慢的数据库查询？”
• “我的程序正在向端口40187发送遥测数据，你能在那里监听吗？”

发展

看 CLAUDE.md 用于：

• 包装结构和架构
• Go代码风格指南
• 贡献者的Git工作流程

贡献

欢迎投稿！这包括：

• Bug报告和功能请求通过
• 拉取修复和改进请求
• 欢迎代理协助的PR，包括 Co-Authored-By 归因

许可证

Apache许可证2.0-版权所有（c）2025艾米·托比

看 许可证 了解详情。