星战科技xingzhan.cloud
返回市场
云监控-MCP

云监控-MCP

作者：kitagry7 星标更新：2025-06-30
安装使用来源：spider==github.com

项目介绍

GCP Telemetry MCP Server

这是一个用于Google Cloud Platform遥测服务的Model Context Protocol (MCP)服务器，提供与GCP可观测性工具的无缝集成。

功能

Cloud Logging

  • ✅ 使用结构化数据写入日志条目
  • ✅ 支持多种严重级别（DEBUG, INFO, WARNING, ERROR, CRITICAL）
  • ✅ 自定义标签和结构化负载
  • ✅ 带过滤和分页的日志条目列表

Cloud Monitoring

  • ✅ 创建自定义指标描述符
  • ✅ 写入时间序列数据点
  • ✅ 使用高级过滤查询时间序列数据
  • ✅ 支持所有指标类型（GAUGE, DELTA, CUMULATIVE）
  • ✅ 支持所有值类型（BOOL, INT64, DOUBLE, STRING, DISTRIBUTION）
  • ✅ 高级聚合选项（对齐周期，归约器）
  • ✅ 删除自定义指标描述符
  • ✅ 列出自定义指标描述符
  • ✅ 发现可用的Google Cloud服务指标

Cloud Trace

  • ✅ 带高级过滤和分页的跟踪列表
  • ✅ 根据跟踪ID获取特定跟踪
  • ✅ 更新/修补跟踪跨度的新数据
  • ✅ 支持分布式跟踪分析

Cloud Profiler

  • ✅ 为应用程序创建新的剖析会话
  • ✅ 使用现有剖析数据创建离线剖析
  • ✅ 更新剖析元数据和数据
  • ✅ 带分页的剖析列表
  • ✅ 支持多种剖析类型（CPU, HEAP, THREADS, CONTENTION, WALL）

先决条件

  • Go 1.24.2或更高版本
  • 启用了适当API的Google Cloud项目
  • 配置身份验证凭据（参见身份验证）

安装

从源代码安装

git clone https://github.com/kitagry/gcp-telemetry-mcp.git
cd gcp-telemetry-mcp
go build -o gcp-telemetry-mcp

身份验证

此服务器使用Google Cloud身份验证。配置以下之一：

  1. 服务账户密钥文件：

    export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json"

  2. 应用默认凭据（如果在GCP上运行）：

    gcloud auth application-default login

  3. 工作负载身份（针对GKE/Cloud Run部署）

配置

设置所需的环境变量：

export GOOGLE_CLOUD_PROJECT="your-project-id"

使用方法

运行服务器

./gcp-telemetry-mcp

或者使用Go：

go run main.go

MCP工具

服务器提供了以下MCP工具：

Cloud Logging工具

write_log_entry

向Cloud Logging写入日志条目。

参数：

  • log_name (字符串，必需)：要写入的日志名称
  • severity (字符串，必需)：日志严重级别（DEBUG, INFO, WARNING, ERROR, CRITICAL）
  • message (字符串，必需)：日志消息
  • labels (对象，可选)：日志标签的键值对
  • payload (对象，可选)：结构化数据负载

示例：

{
  "log_name": "my-application-log",
  "severity": "INFO",
  <message": "用户登录成功",
  "labels": {
    "user_id": "12345",
    "environment": "生产"
  },
  "payload": {
    "event": "user_login",
    "timestamp": "2024-01-01T12:00:00Z",
    "ip_address": "192.168.1.1"
  }
}

list_log_entries

列出Cloud Logging中的日志条目。

参数：

  • filter (字符串，可选)：Cloud Logging过滤表达式
  • limit (数字，可选)：返回的最大条目数（默认：50）

示例：

{
  "filter": "severity>=ERROR",
  "limit": 100
}

Cloud Monitoring工具

create_metric_descriptor

在Cloud Monitoring中创建自定义指标描述符。

参数：

  • type (字符串，必需)：指标类型（例如，'custom.googleapis.com/my_metric'）
  • metric_kind (字符串，必需)：指标类型（GAUGE, DELTA 或 CUMULATIVE）
  • value_type (字符串，必需)：值类型（BOOL, INT64, DOUBLE, STRING 或 DISTRIBUTION）
  • description (字符串，必需)：指标描述
  • display_name (字符串，可选)：指标显示名称

示例：

{
  "type": "custom.googleapis.com/app/response_time",
  "metric_kind": "GAUGE",
  "value_type": "DOUBLE",
  "description": "应用程序响应时间（秒）",
  "display_name": "App Response Time"
}

write_time_series

向Cloud Monitoring写入时间序列数据。

参数：

  • metric_type (字符串，必需)：要写入数据的指标类型
  • resource_type (字符串，必需)：资源类型（例如，'global', 'gce_instance'）
  • value (数字，必需)：要写入的指标值
  • metric_labels (对象，可选)：可选的指标标签
  • timestamp (字符串，可选)：数据点的时间戳（ISO 8601格式，默认为当前时间）

示例：

{
  "metric_type": "custom.googleapis.com/app/response_time",
  "resource_type": "global",
  "value": 0.125,
  "metric_labels": {
    "service": "api",
    "version": "v1.2.0"
  },
  "timestamp": "2024-01-01T12:00:00Z"
}

list_time_series

列出Cloud Monitoring中的时间序列数据。

参数：

  • filter (字符串，必需)：监控过滤表达式
  • start_time (字符串，必需)：查询的开始时间（ISO 8601格式）
  • end_time (字符串，必需)：查询的结束时间（ISO 8601格式）
  • aggregation (对象，可选)：聚合配置

示例：

{
  "filter": "metric.type=\"compute.googleapis.com/instance/cpu/usage\"",
  "start_time": "2024-01-01T10:00:00Z",
  "end_time": "2024-01-01T12:00:00Z",
  "aggregation": {
    "alignment_period": "60s",
    "per_series_aligner": "ALIGN_MEAN",
    "cross_series_reducer": "REDUCE_MEAN",
    "group_by_fields": ["resource.zone"]
  }
}

list_metric_descriptors

列出Cloud Monitoring中的指标描述符。

参数：

  • filter (字符串，可选)：指标描述符的过滤表达式

示例：

{
  "filter": "metric.type=starts_with(\"custom.googleapis.com/\")"
}

delete_metric_descriptor

从Cloud Monitoring中删除自定义指标描述符。

参数：

  • metric_type (字符串，必需)：要删除的指标类型

示例：

{
  "metric_type": "custom.googleapis.com/my_old_metric"
}

list_available_metrics

列出Cloud Monitoring中的可用指标，包括Google Cloud服务指标。

参数：

  • filter (字符串，可选)：指标的过滤表达式（例如，'metric.type=starts_with("compute.googleapis.com/")'）
  • page_size (数字，可选)：返回的最大指标数（默认：100）
  • page_token (字符串，可选)：分页的页面标记

示例：

{
  "filter": "metric.type=starts_with(\"compute.googleapis.com/\")",
  "page_size": 50
}

Cloud Trace工具

list_traces

列出Cloud Trace中的跟踪。

参数：

  • start_time (字符串，必需)：查询的开始时间（ISO 8601格式）
  • end_time (字符串，必需)：查询的结束时间（ISO 8601格式）
  • filter (字符串，可选)：过滤表达式（例如，'span_name_prefix:"api"'）
  • order_by (字符串，可选)：按字段排序（例如，'start_time desc'）
  • page_size (数字，可选)：返回的最大跟踪数（默认：100）
  • page_token (字符串，可选)：分页的页面标记

示例：

{
  "start_time": "2024-01-01T10:00:00Z",
  "end_time": "2024-01-01T12:00:00Z",
  "filter": "span_name_prefix:\"api\"",
  "order_by": "start_time desc",
  "page_size": 50
}

get_trace

从Cloud Trace中获取特定跟踪。

参数：

  • trace_id (字符串，必需)：要检索的跟踪ID

示例：

{
  "trace_id": "1234567890abcdef1234567890abcdef"
}

patch_traces

更新Cloud Trace中的跟踪跨度。

参数：

  • trace_id (字符串，必需)：要更新的跟踪ID
  • spans (数组，必需)：要更新或创建的跨度对象数组

示例：

{
  "trace_id": "1234567890abcdef1234567890abcdef",
  "spans": [
    {
      "span_id": "span123",
      "name": "updated-operation",
      "start_time": "2024-01-01T12:00:00Z",
      "end_time": "2024-01-01T12:00:05Z",
      "parent_id": "parent123",
      "kind": "RPC_CLIENT",
      "labels": {
        "service": "api",
        "version": "v2.0"
      }
    }
  ]
}

Cloud Profiler工具

create_profile

在Cloud Profiler中创建新的剖析。

参数：

  • target (字符串，必需)：目标部署名称
  • profile_type (字符串，必需)：剖析类型（CPU, HEAP, THREADS, CONTENTION 或 WALL）
  • duration (字符串，可选)：剖析持续时间（例如，'60s', '5m'，默认为 '60s'）
  • labels (对象，可选)：剖析的可选标签

示例：

{
  "target": "my-app-v1",
  "profile_type": "CPU",
  "duration": "60s",
  "labels": {
    "service": "web-server",
    "version": "v1.2.0"
  }
}

create_offline_profile

使用现有剖析数据在Cloud Profiler中创建离线剖析。

参数：

  • target (字符串，必需)：目标部署名称
  • profile_type (字符串，必需)：剖析类型（CPU, HEAP, THREADS, CONTENTION 或 WALL）
  • profile_data (字符串，必需)：Base64编码的剖析数据
  • duration (字符串，可选)：剖析持续时间（例如，'60s', '5m'）
  • labels (对象，可选)：剖析的可选标签

示例：

{
  "target": "my-app-v1",
  "profile_type": "HEAP",
  "profile_data": "base64encodedprofiledata==",
  "duration": "30s",
  "labels": {
    "service": "api-server",
    "environment": "production"
  }
}

update_profile

更新Cloud Profiler中的剖析。

参数：

  • profile_name (字符串，必需)：要更新的剖析名称
  • profile_data (字符串，可选)：更新后的Base64编码的剖析数据
  • labels (对象，可选)：更新后的剖析标签
  • update_mask (字符串，可选)：要更新的字段（例如，'labels,profile_bytes'）

示例：

{
  "profile_name": "projects/my-project/profiles/12345",
  "profile_data": "newbase64encodeddata==",
  "labels": {
    "service": "updated-service",
    "version": "v1.3.0"
  },
  "update_mask": "labels,profile_bytes"
}

list_profiles

列出Cloud Profiler中的剖析。

参数：

  • page_size (数字，可选)：返回的最大剖析数（默认：100）
  • page_token (字符串，可选)：分页的页面标记

示例：

{
  "page_size": 50,
  "page_token": "next_page_token_here"
}

开发

运行测试

go test ./...

项目结构

.
├── main.go              # MCP服务器实现和工具处理器
├── logging/
│   ├── client.go        # Cloud Logging客户端实现
│   └── client_test.go   # 日志客户端测试
├── monitoring/
│   ├── client.go        # Cloud Monitoring客户端实现
│   └── client_test.go   # 监控客户端测试
├── trace/
│   ├── client.go        # Cloud Trace客户端实现
│   └── client_test.go   # 跟踪客户端测试
├── profiler/
│   ├── client.go        # Cloud Profiler客户端实现
│   └── client_test.go   # 剖析客户端测试
├── go.mod               # Go模块定义
├── go.sum               # Go依赖校验和
└── README.md           # 本文件

错误处理

服务器为常见问题提供了详细的错误信息：

  • 缺少GOOGLE_CLOUD_PROJECT环境变量
  • 身份验证失败
  • 日志和监控操作的无效参数
  • Cloud Logging API错误
  • Cloud Monitoring API错误
  • 时间序列数据验证错误
  • 指标描述符创建/删除失败
  • Cloud Trace API错误
  • 跟踪检索和跨度更新失败
  • Cloud Profiler API错误
  • 剖析创建和更新失败

贡献

  1. 分叉仓库
  2. 创建功能分支
  3. 进行更改
  4. 为新功能添加测试
  5. 提交拉取请求

许可证

本项目根据MIT许可证发布 - 查看LICENSE文件以获取详细信息。

支持

对于问题和疑问：

  • 在GitHub仓库中创建问题
  • 查看Google Cloud Logging文档以获取日志相关问题的帮助
  • 查看Google Cloud Monitoring文档以获取监控相关问题的帮助
  • 查看Google Cloud Trace文档以获取跟踪相关问题的帮助
  • 查看Google Cloud Profiler文档以获取剖析相关问题的帮助