AI导哈

APM查询服务器

CubeAPM MCP服务器是一个模型上下文协议服务器，允许AI助手通过自然语言查询CubeAPM的观测数据（包括日志、指标和追踪）。

  • by TechnicalRhino
  • JavaScript
  • 本地部署
  • 更新于
在 GitHub 查看 TechnicalRhino/cubeapm-mcp

使用说明

CubeAPM MCP服务器

A. 模型上下文协议（MCP） 服务器 CubeAPM -使像Claude这样的人工智能助手能够查询您的可观察性数据，包括跟踪、指标和日志。

这是什么？

此MCP服务器将AI助手（如Claude）连接到您的CubeAPM实例，允许您：

  • 查询日志 使用翻译成LogsQL的自然语言
  • 分析指标 与PromQL兼容的查询
  • 搜索和检查痕迹 调试分布式系统
  • 监控您的服务 通过对话式界面

安装

来自NPM（推荐）

npm install -g cubeapm-mcp

源自源头

git clone https://github.com/TechnicalRhino/cubeapm-mcp.git
cd cubeapm-mcp
npm install
npm run build

快速开始

1.配置克劳德代码

添加到您的克劳德代码设置(~/.claude/settings.json):

{
  "mcpServers": {
    "cubeapm": {
      "command": "npx",
      "args": ["-y", "cubeapm-mcp"],
      "env": {
        "CUBEAPM_HOST": "your-cubeapm-server.com"
      }
    }
  }
}

2.重新启动克劳德代码

更新设置后，重新启动Claude Code以加载MCP服务器。

3.开始查询

现在，您可以向Claude提出以下问题：

  • “显示最近一小时支付服务的错误日志”
  • “签出API的p99延迟是多少？”
  • “查找生产中持续时间>5s的痕迹”
  • “获取跟踪ID abc123def456的完整跟踪”

配置

环境变量 默认值 描述
CUBEAPM_URL - CubeAPM的完整URL（例如。， https://cube.example.com).优先于HOST/PORT设置。
CUBEAPM_HOST localhost CubeAPM服务器主机名或IP（如果未设置CUBEAM_URL，则使用）
CUBEAPM_QUERY_PORT 3140 用于查询API（跟踪、指标、日志）的端口
CUBEAPM_INGEST_PORT 3130 摄入API端口

示例配置

地方发展：

{
  "mcpServers": {
    "cubeapm": {
      "command": "npx",
      "args": ["-y", "cubeapm-mcp"],
      "env": {
        "CUBEAPM_HOST": "localhost"
      }
    }
  }
}

生产（带完整URL）：

{
  "mcpServers": {
    "cubeapm": {
      "command": "npx",
      "args": ["-y", "cubeapm-mcp"],
      "env": {
        "CUBEAPM_URL": "https://cubeapm.internal.company.com"
      }
    }
  }
}

生产（带主机/端口）：

{
  "mcpServers": {
    "cubeapm": {
      "command": "npx",
      "args": ["-y", "cubeapm-mcp"],
      "env": {
        "CUBEAPM_HOST": "cubeapm.internal.company.com",
        "CUBEAPM_QUERY_PORT": "3140"
      }
    }
  }
}

可用工具

日志

工具 说明
query_logs 使用带有时间范围和限制的LogsQL语法查询日志

参数：

  • query -LogsQL查询字符串（例如。， {service="api"} error)
  • start -开始时间（RFC3339或Unix时间戳）
  • end -结束时间（RFC3339或Unix时间戳）
  • limit -返回的最大条目数（默认值：100）

指标

工具 说明
query_metrics_instant 在单个时间点执行PromQL查询
query_metrics_range 在一定时间范围内执行PromQL查询

即时查询参数：

  • query -PromQL表达式
  • time -评估时间戳
  • step -可选时间窗口（秒）

范围查询参数：

  • query -PromQL表达式
  • start / end -时间范围
  • step -分辨率（秒）

痕迹

工具 说明
search_traces 按服务、环境或自定义查询搜索跟踪
get_trace 按跟踪ID获取完整的跟踪详细信息

搜索参数（必填）：

  • query -搜索查询（默认值： * 对于通配符）
  • env -环境过滤器（默认值： UNSET)
  • service -服务名称筛选器(必需的，区分大小写）
  • start / end -时间范围（RFC3339或Unix时间戳）

搜索参数（可选）：

  • limit -最大结果（默认值：20）
  • spanKind -按跨度类型筛选： server, client, consumer, producer
  • sortBy -排序方式： duration （可用于查找慢速痕迹）

获取跟踪参数：

  • trace_id -十六进制编码的跟踪ID
  • start / end -搜索时间范围

摄入

工具 说明
ingest_metrics_prometheus 以Prometheus文本展示格式发送指标

提示

常见可观察性任务的预定义模板：

提示 描述
investigate-service 全面的服务调查-检查错误、延迟和跟踪
check-latency 获取服务的P50、P95、P99延迟百分比
find-slow-traces 查找最慢的跟踪以识别性能瓶颈

使用示例：

Use the investigate-service prompt for Kratos-Prod

资源

公开CubeAPM数据和配置的可读资源：

资源URI 描述
cubeapm://config 当前CubeAPM连接配置
cubeapm://query-patterns 查询模式和命名约定参考

CubeAPM查询模式

度量（PromQL/MetricsQL）

CubeAPM使用与标准OpenTetry不同的特定命名约定：

什么 CubeAPM会议
公制前缀 cube_apm_* （例如。， cube_apm_calls_total, cube_apm_latency_bucket)
服务标签 service （不是 server 或 service_name)
常见标签 env, service, span_kind, status_code, http_code

直方图查询（P50、P90、P95、P99）

CubeAPM使用 VictoriaMetrics风格直方图 随着 vmrange 标签而不是普罗米修斯 le 水桶：

# ✅ Correct - Use histogram_quantiles() with vmrange
histogram_quantiles("phi", 0.95, sum by (vmrange, service) (
  increase(cube_apm_latency_bucket{service="MyService", span_kind="server"}[5m])
))

# ❌ Wrong - Standard Prometheus syntax won't work
histogram_quantile(0.95, sum by (le) (rate(http_request_duration_bucket[5m])))

注： 延迟值在中返回 秒 （0.05=50ms）

日志（LogsQL）

流选择器

日志标签因来源而异。使用 * 首先查询以发现可用标签：

来源 常用标签
Lambda函数 faas.name, faas.arn, env, aws.lambda_request_id
服务项目 service_name, level, host 
# Discover all labels
*

# Lambda function logs
{faas.name="my-lambda-prod"}

# Regex match
{faas.name=~".*-prod"}

# Text filter with boolean operators
{faas.name=~".*"} AND "error" AND NOT "retry"

管道操作员

任何查询后的链 |:

管道 语法 描述
copy | copy src AS dst 复制字段值
drop | drop field1, field2 从输出中删除字段
extract_regexp | extract_regexp "(?P<name>re)" 通过指定的捕获组提取
join | join by (field) (...subquery...) 使用子查询结果连接
keep | keep field1, field2 仅保留指定字段
limit | limit N 最多返回N个结果
math | math result = f1 + f2 算术（+、-、*、/、%）
rename | rename src AS dst 重命名字段
replace | replace (field, "old", "new") 更换变电站
replace_regexp | replace_regexp (field, "re", "repl") 正则表达式替换
sort | sort by (field) [asc|desc] 对结果进行排序
stats | stats <func> as alias [by (fields)] 汇总结果
unpack_json | unpack_json 从JSON正文中提取字段

统计功能

与 | stats 管道：

功能 说明
avg(field) 算术平均值
count() 匹配条目总数
count_empty(field) 字段为空的条目
count_uniq(field) 独特的价值观
max(field) 最大值
median(field) 中位数（第50百分位）
min(field) 最小值
quantile(p, field) 第p分位数（例如。， quantile(0.95, duration))
sum(field) 值之和

日志查询示例

# Count errors per Lambda function
{faas.name=~".*"} AND "error" | stats count() as errors by (faas.name)

# Top 10 slowest requests
{service_name="my-service"} | sort by (duration) desc | limit 10

# Extract and aggregate from JSON logs
{service_name="api"} | unpack_json | stats avg(response_time) as avg_rt by (endpoint)

痕迹

跟踪查询使用与日志相同的管道语法： {stream_selector} | pipe1 | pipe2

重要提示：

  • query, env, service 是必需的参数
  • 持续时间为 毫秒 （不是像指标那样的秒数）
  • p95 不是有效的统计函数--使用 quantile(0.95, duration)
  • 服务名称区分大小写（例如。， "Kratos-Prod" 不 "kratos")

跟踪查询示例

# P95 latency for a service
{service="Kratos-Prod", span_kind="server"} | stats quantile(0.95, duration) as p95_ms

# Error count by endpoint
{service="Kratos-Prod", status_code="ERROR"} | stats count() as errors by (http_route)

# Slowest spans
{service="Kratos-Prod"} | sort by (duration) desc | limit 20

自然语言查询示例

日志

"Show me logs from webhook-lambda-prod"
"Find all logs containing 'timeout' in the last hour"
"Count errors per Lambda function in the last 24h"

指标

"What's the P95 latency for Kratos-Prod service?"
"Show me error rate for all services"
"List all available services in CubeAPM"

痕迹

"Find the P95 latency for Kratos-Prod using trace stats"
"Show me traces with errors in the production environment"
"Get the full waterfall for trace ID abc123"

发展

# Clone the repository
git clone https://github.com/TechnicalRhino/cubeapm-mcp.git
cd cubeapm-mcp

# Install dependencies
npm install

# Run in development mode (with hot reload)
npm run dev

# Build for production
npm run build

# Test the build
npm start

运作原理

┌─────────────────┐     MCP Protocol     ┌─────────────────┐     HTTP API     ┌─────────────────┐
│  Claude / AI    │◄───────────────────►│  cubeapm-mcp    │◄────────────────►│    CubeAPM      │
│   Assistant     │   (stdio transport)  │   MCP Server    │   (REST calls)   │    Server       │
└─────────────────┘                      └─────────────────┘                  └─────────────────┘

MCP服务器：

  1. 通过stdio接收来自AI助手的工具调用
  2. 将它们转换为CubeAPM HTTP API请求
  3. 将格式化的结果返回给助手

需求

  • Node.js 18+
  • CubeAPM 实例（自托管或云）
  • 克劳德代码 或任何MCP兼容客户端

相关链接

贡献

欢迎投稿！请随时提交拉取请求。

许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

相关 MCP