Back
To Top
Loki MCP Server -支持Claude Desktop/Claude Code/Cursor 等客户端通过自然语言查询日志
2026/04/09
Loki MCP Server -支持Claude Desktop/Claude Code/Cursor 等客户端通过自然语言查询日志
- MCP定位，技术栈，架构，项目结构，基础框架搭建，开发部署及常见问题
# Loki MCP Server - CLAUDE.md
> Go 实现的 MCP Server，集成 Grafana Loki 日志查询。支持 Claude Desktop / Claude Code / Cursor 等客户端通过自然语言查询日志。
---一、项目概述
定位
将 Grafana Loki 的日志查询能力通过 MCP (Model Context Protocol) 暴露给 AI 助手，运维人员可以用自然语言代替 LogQL 查询日志。技术栈
层 技术 版本 语言 Go 1.24+ MCP SDK github.com/mark3labs/mcp-go v0.32.0 日志存储 Grafana Loki 2.9.0 日志采集 Promtail 2.9.0 可视化 Grafana latest 容器化 Docker + Compose - 核心能力（3 个 MCP Tool）
Tool 用途 Loki API `loki_query` 执行 LogQL 查询 `/loki/api/v1/query_range` `loki_label_names` 获取所有标签名 `/loki/api/v1/labels` `loki_label_values` 获取标签值列表 `/loki/api/v1/label/{name}/values` 二、架构设计
整体架构
``` ┌─────────────────┐ ┌──────────────────┐ ┌──────────────┐ │ AI Client │ │ Loki MCP Server │ │ Grafana │ │ (Claude Code/ │─────→│ :8080 │─────→│ Loki │ │ Desktop/ │ MCP │ │ HTTP │ :3100 │ │ Cursor) │ │ 3 种传输协议: │ │ │ └─────────────────┘ │ - stdio │ └──────────────┘ │ - SSE (/sse) │ │ - HTTP (/stream)│ │ │ │ /healthz (K8s) │ └──────────────────┘ ```三种传输协议（同端口共存）
协议 端点 场景 stdio 标准输入输出 本地 binary / Docker 集成，Claude Desktop 直接启动进程 SSE `/sse` + `/mcp` Server-Sent Events，远程连接（旧协议） Streamable HTTP `/stream` 新一代 MCP 远程协议（推荐）
**设计要点**：通过 `http.ServeMux` 将 SSE 和 Streamable HTTP 注册到同一端口，stdio 作为后台 goroutine 并行运行。项目结构
``` loki-mcp/ ├── cmd/ │ ├── server/main.go # 入口：注册 Tool + 启动 3 种传输 │ └── client/main.go # JSON-RPC 测试客户端 ├── internal/ │ └── handlers/ │ ├── loki.go # 核心：3 个 Tool 的完整实现 (993 行) │ └── loki_test.go # 单元测试 (261 行) ├── pkg/ │ └── utils/logger.go # 简易日志工具 ├── grafana/ │ └── provisioning/datasources/loki.yaml # Grafana 数据源预配置 ├── promtail/ │ └── config.yml # 日志采集配置 ├── examples/ │ ├── claude-desktop/ # 4 种 Claude Desktop 配置示例 │ ├── claude-code-commands/ # Slash Command 模板 │ ├── simple-sse-client.html # SSE 测试页面 │ └── sse-client.html # 完整 SSE 客户端 ├── docker-compose.yml # 本地 5 服务开发环境 ├── Dockerfile # 多阶段构建 ├── Makefile # 构建/测试/运行 ├── go.mod / go.sum ├── run-mcp-server.sh # 启动脚本 ├── test-loki-query.sh # 查询测试脚本 ├── insert-loki-logs.sh # 插入测试日志 └── README.md ```
---三、从零实现指南
Phase 1：基础框架搭建
1.1 初始化 Go 项目
```bash mkdir loki-mcp && cd loki-mcp go mod init github.com/yourname/loki-mcp go get github.com/mark3labs/mcp-go@v0.32.0 ```1.2 理解 MCP Server 入口 (`cmd/server/main.go`)
核心模式：**创建 Server → 注册 Tool → 启动传输层**
```go // 1. 创建 MCP Server 实例 s := server.NewMCPServer( "Loki MCP Server", "0.1.0", server.WithResourceCapabilities(true, true), server.WithLogging(), )
// 2. 注册工具（Tool 定义 + Handler 函数） lokiQueryTool := handlers.NewLokiQueryTool() s.AddTool(lokiQueryTool, handlers.HandleLokiQuery)
// 3. 创建传输层 sseServer := server.NewSSEServer(s, server.WithSSEEndpoint("/sse"), server.WithMessageEndpoint("/mcp"), ) streamableServer := server.NewStreamableHTTPServer(s)
// 4. 统一路由 mux := http.NewServeMux() mux.Handle("/sse", sseServer) mux.Handle("/mcp", sseServer) mux.Handle("/stream", streamableServer) mux.HandleFunc("/healthz", healthHandler)
// 5. 并行启动 HTTP + stdio go http.ListenAndServe(":8080", mux) go server.ServeStdio(s)
// 6. 优雅关闭 stop := make(chan os.Signal, 1) signal.Notify(stop, os.Interrupt, syscall.SIGTERM) <-stop ```
**关键设计决策**： - 三种传输协议同端口：简化部署，一个端口搞定所有客户端 - stdio 后台运行：兼容 Claude Desktop 的进程模式 - `/healthz` 端点：适配 K8s readiness/liveness probe1.3 理解 Tool 定义模式
每个 Tool 由两部分组成：- **Tool 定义函数** (`NewXxxTool()`) — 声明参数 schema
- **Handler 函数** (`HandleXxx()`) — 处理请求逻辑
```go // Tool 定义：声明参数、类型、默认值、描述 func NewLokiQueryTool() mcp.Tool { return mcp.NewTool("loki_query", mcp.WithDescription("Run a query against Grafana Loki"), mcp.WithString("query", mcp.Required(), mcp.Description("LogQL query string")), mcp.WithString("url", mcp.Description("Loki server URL"), mcp.DefaultString(lokiURL)), mcp.WithString("start", mcp.Description("Start time (default: 1h ago)")), mcp.WithNumber("limit", mcp.Description("Max entries (default: 100)")), mcp.WithString("format", mcp.DefaultString("raw")), // ... 认证参数 ) }
// Handler：提取参数 → 构建请求 → 调用 Loki API → 格式化输出 func HandleLokiQuery(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { args := request.GetArguments() // ... 处理逻辑 return mcp.NewToolResultText(formattedResult), nil } ```Phase 2：核心逻辑实现
2.1 请求处理流程 (`internal/handlers/loki.go`)
``` 参数提取 → 环境变量回退 → 时间解析 → URL构建 → HTTP请求 → 响应解析 → 格式化输出 ```2.2 参数提取模式（带环境变量回退）
每个参数都遵循：**请求参数 > 环境变量 > 默认值** 的优先级链
```go // 统一模式：先看请求参数，再看环境变量 var lokiURL string if urlArg, ok := args["url"].(string); ok && urlArg != "" { lokiURL = urlArg } else { lokiURL = os.Getenv("LOKI_URL") if lokiURL == "" { lokiURL = "http://localhost:3100" } } ```
环境变量清单：变量 用途 默认值 `LOKI_URL` Loki 地址 `http://localhost:3100\` `LOKI_ORG_ID` 租户 ID 空 `LOKI_USERNAME` Basic Auth 用户名 空 `LOKI_PASSWORD` Basic Auth 密码 空 `LOKI_TOKEN` Bearer Token 空 `PORT` 服务端口 `8080` 2.3 时间解析 (`parseTime`)
支持多种输入格式，按顺序尝试：
```go func parseTime(timeStr string) (time.Time, error) { // 1. "now" 关键字 if timeStr == "now" { return time.Now(), nil }// 2. 相对时间: "-1h", "-30m" if timeStr\[0\] == '\-' { duration, err :\= time.ParseDuration(timeStr) if err == nil { return time.Now().Add(duration), nil } } // 3. RFC3339: "2024-01-15T10:30:45Z" // 4. ISO 变体: "2006-01-02T15:04:05", "2006-01-02 15:04:05" // 5. 纯日期: "2006-01-02"
} ```2.4 URL 构建
智能路径拼接，处理各种 base URL 格式：
```go func buildLokiQueryURL(baseURL, query string, start, end int64, limit int) (string, error) { u, _ := url.Parse(baseURL)// 路径规范化：避免重复拼接 if !strings.Contains(u.Path, "loki/api/v1") { u.Path \= "/loki/api/v1/query\_range" } // 查询参数 q := u.Query() q.Set("query", query) // LogQL q.Set("start", fmt.Sprintf("%d", start)) // Unix 秒 q.Set("end", fmt.Sprintf("%d", end)) q.Set("limit", fmt.Sprintf("%d", limit)) u.RawQuery \= q.Encode() return u.String(), nil
} ```2.5 认证机制
三级认证，优先级：Bearer Token > Basic Auth > 无认证
```go if token != "" { req.Header.Add("Authorization", "Bearer "+token) } else if username != "" || password != "" { req.SetBasicAuth(username, password) }
// 多租户隔离（始终添加如果有值） if orgID != "" { req.Header.Add("X-Scope-OrgID", orgID) } ```2.6 响应数据结构
```go type LokiResult struct { Status string `json:"status"` // "success" | "error" Data LokiData `json:"data"` Error string `json:"error,omitempty"` }
type LokiData struct { ResultType string `json:"resultType"` // "streams" Result []LokiEntry `json:"result"` }
type LokiEntry struct { Stream map[string]string `json:"stream"` // 标签: {job: "xx", pod: "xx"} Values [][]string `json:"values"` // [[纳秒时间戳, 日志行], ...] } ```2.7 三种输出格式
格式 用途 示例 `raw`（默认） AI 解析友好，最紧凑 `2024-01-15T10:30:45Z {job=api} Request received` `json` 程序化处理 完整 JSON 结构 `text` 人类可读 编号 Stream + 时间戳日志行 2.8 已知 Bug 及修复
**时间戳 2262 年 Bug**：Loki 返回纳秒时间戳，早期实现使用 `time.Unix(ts, 0)` 将纳秒当秒处理，导致显示 2262 年。
修复：`time.Unix(0, int64(ts))` — 第一个参数为 0 秒，第二个参数为纳秒。Phase 3：Docker 化与本地环境
3.1 Dockerfile（多阶段构建）
```dockerfileStage 1: 编译
FROM golang:1.24-alpine AS builder WORKDIR /app COPY go.mod go.sum ./ RUN go mod download # 利用缓存层 COPY . . RUN CGO_ENABLED=0 GOOS=linux go build -o loki-mcp-server ./cmd/serverStage 2: 运行（最小镜像）
FROM alpine:latest WORKDIR /app COPY --from=builder /app/loki-mcp-server . EXPOSE 8080 ENTRYPOINT ["./loki-mcp-server"] ```
**关键点**： - `CGO_ENABLED=0`：静态链接，不依赖 glibc - 先 COPY go.mod/go.sum → `go mod download`：利用 Docker 层缓存加速构建 - 最终镜像基于 `alpine:latest`：最小化攻击面3.2 Docker Compose（5 服务完整环境）
```yaml services: loki-mcp-server: # MCP Server :8080 depends_on: loki: condition: service_healthy # 等 Loki 就绪
loki: # 日志存储 :3100 healthcheck: # /ready 端点检查 test: ["CMD-SHELL", "wget -q --spider http://localhost:3100/ready || exit 1"]
grafana: # 可视化 :3000 volumes: - ./grafana/provisioning:/etc/grafana/provisioning # 预配置数据源
promtail: # 日志采集 volumes: - /var/log:/var/log # 采集宿主机日志 - /var/run/docker.sock:/var/run/docker.sock # 采集容器日志
log-generator: # 测试日志生成器 command: | # 每 5 秒生成 INFO/ERROR 日志 while true; do echo "INFO: ..."; sleep 5; done ```
**服务依赖链**：`log-generator → promtail → loki → loki-mcp-server`，Grafana 独立。Phase 4：测试策略
4.1 单元测试
重点覆盖时间戳解析（bug 高发区）：
```go func TestFormatLokiResults_NoYear2262Bug(t *testing.T) { testCases := []struct { name string timestampNs string expectedYear string }{ {"Current", "1705312245000000000", "2024"}, // 2024-01-15 {"Recent", "1700000000000000000", "2023"}, // 2023-11-14 {"Future", "1800000000000000000", "2027"}, // 2027-01-11 }for \_, tc := range testCases { t.Run(tc.name, func(t \*testing.T) { // 构建 LokiResult → formatLokiResults → 断言年份 }) }
} ```
**测试用例覆盖**： - 正常时间戳解析 - 多条日志时间戳 - 非法时间戳回退 - 空结果处理 - 当前时间回归 - 2262 年 Bug 回归（表驱动，3 个时间点）4.2 运行测试
```bash make test # 全部测试 go test -coverprofile=coverage.out ./... # 带覆盖率 go tool cover -func=coverage.out # 查看覆盖率 go test -race ./... # 竞态检测 ```4.3 集成测试脚本
```bash插入测试日志
./insert-loki-logs.sh --num 20 --job "custom-job" --app "my-app"查询验证
./test-loki-query.sh '{job="varlogs"}' ./test-loki-query.sh '{job="varlogs"} |= "ERROR"' '-1h' 'now' 50 ```Phase 5：部署与客户端集成
5.1 部署方式选择
方式 场景 命令 本地二进制 开发调试 `make run` Docker 单容器 已有 Loki 实例 `docker run -p 8080:8080 -e LOKI_URL=... loki-mcp-server` Docker Compose 完整本地环境 `docker-compose up --build` K8s Deployment 生产环境 见下方 manifest 远程 URL 团队共享 `https://loki-mcp.loki.com/stream\` 5.2 K8s 部署建议
```yaml apiVersion: apps/v1 kind: Deployment metadata: name: loki-mcp-server spec: replicas: 2 # 无状态，可水平扩展 template: spec: containers: - name: loki-mcp-server image: loki-mcp-server:v0.1.0 # 固定版本 ports: - containerPort: 8080 env: - name: LOKI_URL value: "http://loki-gateway.monitoring:3100" - name: LOKI_TOKEN valueFrom: secretKeyRef: name: loki-auth key: token readinessProbe: httpGet: path: /healthz port: 8080 periodSeconds: 10 livenessProbe: httpGet: path: /healthz port: 8080 periodSeconds: 30 resources: requests: cpu: 50m memory: 64Mi limits: cpu: 200m memory: 128Mi ```5.3 客户端接入
**Claude Code（推荐 Streamable HTTP）**： ```bash claude mcp add --transport http --scope user loki https://loki-mcp.loki.com/stream ```
**Claude Desktop（本地 Docker）**： ```json { "mcpServers": { "loki": { "command": "docker", "args": ["run", "--rm", "-i", "-e", "LOKI_URL=http://host.docker.internal:3100", "loki-mcp-server:latest"] } } } ```
**Cursor**： ```json { "mcpServers": { "loki": { "command": "docker", "args": ["run", "--rm", "-i", "-e", "LOKI_URL=http://host.docker.internal:3100", "loki-mcp-server:latest"] } } } ```
---四、开发命令速查
```bash构建
make build # 编译本地二进制 make build-linux # 交叉编译 Linux (amd64) docker build -t loki-mcp-server . # 构建镜像运行
make run # 本地运行 docker-compose up --build # 完整本地环境测试
make test # 单元测试 go test -race ./... # 竞态检测 ./test-loki-query.sh # 集成测试 ./insert-loki-logs.sh # 插入测试数据依赖
make deps # 下载依赖 make tidy # 整理 go.mod清理
make clean # 删除二进制 docker-compose down -v # 清理容器和数据卷 ```
---五、代码规范
Go 规范
- `gofmt` / `goimports` 格式化 - 错误处理：`fmt.Errorf("context: %w", err)` 包装 - 环境变量用 `const` 定义名称，避免硬编码字符串 - HTTP 客户端必须设置 `Timeout`（当前 30s） - 使用 `context.Context` 传递请求上下文MCP Tool 开发规范
- Tool 名称用 `snake_case`（如 `loki_query`） - 必填参数用 `mcp.Required()` 标记 - 每个参数都要有 `mcp.Description()`，包含默认值说明 - 环境变量回退必须在 Handler 中实现（而非仅 Tool 定义中） - 返回 `mcp.NewToolResultText()` 作为标准响应新增 Tool 模板
如果需要添加新工具（如 `loki_series`），遵循以下步骤：- 在 `internal/handlers/loki.go` 中添加： - `NewLokiSeriesTool()` — 定义参数 - `HandleLokiSeries()` — 实现逻辑 - `buildLokiSeriesURL()` — URL 构建 - `executeLokiSeriesQuery()` — HTTP 请求 - `formatLokiSeriesResults()` — 格式化输出
- 在 `cmd/server/main.go` 中注册： ```go seriesTool := handlers.NewLokiSeriesTool() s.AddTool(seriesTool, handlers.HandleLokiSeries) ```
- 在 `internal/handlers/loki_test.go` 中添加测试
---六、运维关注点
可观测性
- `/healthz` 端点返回 `ok`，适配 K8s probe - 服务本身无状态，无需持久化存储 - 启动日志输出所有端点地址 - 建议：生产环境添加 Prometheus metrics 端点（`/metrics`）安全
- 认证信息通过环境变量注入，不写入镜像层 - Bearer Token 优先于 Basic Auth - 多租户通过 `X-Scope-OrgID` 头隔离 - HTTP 超时 30s 防止慢查询阻塞扩展方向
方向 说明 添加 `/metrics` Prometheus 指标暴露 添加 `loki_series` Tool 查询 series 元数据 添加 `loki_stats` Tool 查询 ingester 统计 提取认证参数公共函数 消除 3 个 Handler 中的重复代码 添加请求日志中间件 记录每次 Tool 调用的查询和耗时 支持 TLS HTTPS 终止或证书配置 添加 rate limiting 防止 AI 频繁查询 七、学习路径建议
``` 第 1 天：跑起来 ├── docker-compose up --build ├── 访问 Grafana :3000 理解 Loki 数据结构 ├── ./insert-loki-logs.sh 插入测试数据 └── ./test-loki-query.sh 验证查询
第 2 天：读懂入口 ├── cmd/server/main.go (100 行) — MCP 注册 + 传输层 ├── 理解 mcp-go SDK 的 AddTool 模式 └── 理解三协议同端口架构
第 3 天：精读核心 ├── internal/handlers/loki.go (993 行) ├── 参数提取 → 环境变量回退模式 ├── parseTime 多格式时间解析 ├── buildLokiQueryURL 路径规范化 ├── executeLokiQuery HTTP + 认证 └── formatLokiResults 三种输出格式
第 4 天：测试与 Bug ├── internal/handlers/loki_test.go ├── 纳秒时间戳 2262 年 Bug 的前因后果 └── Go 表驱动测试风格
第 5 天：Docker + 部署 ├── Dockerfile 多阶段构建 ├── docker-compose.yml 服务编排 ├── K8s 部署清单设计 └── 客户端集成配置
第 6 天：动手扩展 ├── 尝试添加 loki_series Tool ├── 提取认证参数公共函数（消除重复） └── 添加 /metrics 端点 ```
---八、常见问题
连接失败
- `claude mcp get loki` 检查配置
- 确认网络连通性
- 检查 HTTPS 证书
查询无结果
- 确认 Loki 有对应时间范围的数据
- 多租户场景检查 `org_id`
- 用 `loki_label_names` 先查可用标签
Docker 环境问题
- Loki 启动需要时间，等 healthcheck 通过
- Mac 上 Docker 访问宿主机用 `host.docker.internal`
- `docker-compose down -v` 可清理数据重来
时间戳显示异常
- 确认使用 `time.Unix(0, int64(ns))` 而非 `time.Unix(ns, 0)` - Loki 返回纳秒时间戳，不是秒 - 使用测试
▗ ▗ ▖ ▖ Claude Code v2.1.96 Opus 4.6 (1M context) with medium effort · API Usage Billing ▘▘ ▝▝ ~/loki-mcp ⎿ SessionStart:startup hook error
❯ /mcp ⎿ MCP dialog dismissed
❯ loki查看所有可用的标签名
⏺ loki - loki_label_names (MCP)
⏺ Loki 当前可用的标签名：
┌────────────────┬─────────────────────────┐ │ 标签 │ 常见用途 │ ├────────────────┼─────────────────────────┤ │ app │ 应用名称 │ ├────────────────┼─────────────────────────┤ │ broker │ 消息代理 │ ├────────────────┼─────────────────────────┤ │ component │ 组件标识 │ ├────────────────┼─────────────────────────┤ │ container │ 容器名 │ ├────────────────┼─────────────────────────┤ │ env │ 环境 (prod/staging/dev) │ ├────────────────┼─────────────────────────┤ │ filename │ 日志文件路径 │ ├────────────────┼─────────────────────────┤ │ host │ 主机名 │ ├────────────────┼─────────────────────────┤ │ instance │ 实例地址 │ ├────────────────┼─────────────────────────┤ │ job │ Prometheus job 名称 │ ├────────────────┼─────────────────────────┤ │ namespace │ K8s 命名空间 │ ├────────────────┼─────────────────────────┤ │ node_name │ K8s 节点名 │ ├────────────────┼─────────────────────────┤ │ pod │ Pod 名称 │ ├────────────────┼─────────────────────────┤ │ request_method │ HTTP 请求方法 │ ├────────────────┼─────────────────────────┤ │ service_name │ 服务名称 │ ├────────────────┼─────────────────────────┤ │ site │ 站点标识 │ ├────────────────┼─────────────────────────┤ │ status │ 状态码 │ ├────────────────┼─────────────────────────┤ │ stream │ stdout/stderr │ ├────────────────┼─────────────────────────┤ │ uri │ 请求路径 │ └────────────────┴─────────────────────────┘
需要查看某个标签的具体值，可以告诉我，比如 namespace 有哪些值。
❯ 查询app=pb-trading-engine env=prodjp 的近5分钟的错误日志，帮我分析下
⏺ loki - loki_query (MCP)(query: "{app=\"pb-trading-engine\", env=\"prodjp\"} |~ `(?i)error|exception|fatal|panic`", start: "5m", limit: 200) ⎿ Error: MCP error -32603: invalid start time: unsupported time format: 5m
⏺ loki - loki_query (MCP)(query: "{app=\"pb-trading-engine\", env=\"prodjp\"} |~ `(?i)error|exception|fatal|panic`", start: "2026-04-08T15:00:00Z", end: "2026-04-08T15:05:00Z", limit: 200)
⏺ 时间格式需要调整，让我用 UTC 时间重试（当前北京时间约 15:05，即 UTC 07:05）。
⏺ loki - loki_query (MCP)(query: "{app=\"pb-trading-engine\", env=\"prodjp\"} |~ `(?i)error|exception|fatal|panic`", start: "2026-04-08T07:00:00Z", end: "2026-04-08T07:05:00Z", limit: 200)
⏺ 近 5 分钟没有匹配到错误日志。让我先确认标签值是否正确，以及扩大时间范围看看。
⏺ loki - loki_label_values (MCP)(label: "app")
⏺ loki - loki_label_values (MCP)(label: "env")
⏺ 标签值确认正确：app=pb-trading-engine 和 env=prodjp 都存在。让我扩大时间范围查询。
⏺ loki - loki_query (MCP)(query: "{app=\"pb-trading-engine\", env=\"prodjp\"} |~ `(?i)error|exception|fatal|panic`", start: "2026-04-08T06:00:00Z", end: "2026-04-08T07:10:00Z", limit: 200) ⎿ Error: result (73,209 characters) exceeds maximum allowed tokens. Output has been saved to /Users/example/.claude/projects/-Users-example-ltp-codes-ops-agent/0d50fb2b-2b85-4322-9f3a-72d75fc427 b3/tool-results/mcp-loki-loki_query-1111111.txt. Format: JSON array with schema: [{type: string, text: string}] … +7 lines (ctrl+o to expand)
⏺ 查到大量错误日志，让我逐段读取分析。
Searched for 1 pattern, read 1 file, searched memories (ctrl+o to expand)
⏺ 文件是 JSON 格式，用 jq 解析。
⏺ Bash(cat /Users/example/.claude/projects/-Users-example-ltp-codes-ops-agent/0d50fb2b-2b85-4322-9f3a-72d75fc427b3/tool-results/mcp-loki-loki_query-111111.txt |…) ⎿ 2026-04-08T06:39:55Z {service_name=pb-trading-engine,app=pb-trading-engine,detected_level=info,env=prodjp,filename=/data/logs/pb-trading-engine/info.log,host=10.19.5.136} 2026-04-08 06:39:54.9 62 [disruptor-worker9] [INFO ] [TraceId=11111111] com.ltp.pb.engine.service.biz.PlacePerpOrderService - placePerpOrder TRADE_MAX_ORDERS_ERROR. oid:6666666,count:60,maxNum:6 0 … +24 lines (ctrl+o to expand)
⏺ Bash(cat /Users/example/.claude/projects/-Users-example-ltp-codes-ops-agent/0d50fb2b-2b85-4322-9f3a-72d75fc427b3/tool-results/mcp-loki-loki_query-222222`````.txt |…) ⎿ 总日志条数: 172=== 错误类型分布 === … +24 lines (ctrl+o to expand)
⏺ Bash(cat /Users/example/.claude/projects/-Users-example-ltp-codes-ops-agent/0d50fb2b-2b85-4322-9f3a-72d75fc427b3/tool-results/mcp-loki-loki_query-333333.txt |…)
⎿ === 非 TRADE_MAX_ORDERS_ERROR 的日志 ===2026\-04\-08T06:25:17Z {app=pb-trading-engine,detected\_level=error,env\=prodjp,filename=/data/logs/pb-trading-engine/warn.log,host=10.19.5.136,service\_name=pb-trading-engine} 2026\-04\-08 06:25:12. … +34 lines (ctrl+o to expand)
⏺ pb-trading-engine (prodjp) 错误日志分析
时间范围: 2026-04-08 06:03 ~ 06:43 UTC（约 14:03 ~ 14:43 JST）
总日志条数: 172 条
---- 错误类型分布
┌───────────────────────────────────────────────────────┬──────┬───────┬──────────┐
│ 错误类型 │ 数量 │ 占比 │ 严重程度 │
├───────────────────────────────────────────────────────┼──────┼───────┼──────────┤
│ TRADE_MAX_ORDERS_ERROR │ 158 │ 91.9% │ MEDIUM │
├───────────────────────────────────────────────────────┼──────┼───────┼──────────┤
│ LiqService - tryTriggerLiqHandle account status error │ 9 │ 5.2% │ HIGH │
├───────────────────────────────────────────────────────┼──────┼───────┼──────────┤
│ LiqService - cancel all/open exceed limit │ 2 │ 1.2% │ HIGH │
├───────────────────────────────────────────────────────┼──────┼───────┼──────────┤
│ PostWorkerHandler - lark alert (飞书告警) │ 2 │ 1.2% │ INFO │
├───────────────────────────────────────────────────────┼──────┼───────┼──────────┤
│ OrderMonitor - ems not exist │ 1 │ 0.6% │ MEDIUM │
└───────────────────────────────────────────────────────┴──────┴───────┴──────────┘
---
2. 逐类分析
(1) TRADE_MAX_ORDERS_ERROR — 158 条 (占 91.9%)
PlacePerpOrderService - placePerpOrder TRADE_MAX_ORDERS_ERROR. oid:xxx, count:60, maxNum:60- 原因: 某账户的永续合约挂单数 (count=60) 达到最大限制 (maxNum=60)，新单被拒绝
- 主机: 集中在 10.19.5.136（161 条）
- 时间: 呈周期性爆发，每隔约 5-6 分钟出现一波（06:03, 06:09, 06:15, 06:22, 06:26, 06:39）
- 推测: 某个做市/策略账户在高频下单，每次触发限制后短暂停顿再重试，形成周期性模式
- 影响: INFO 级别，不影响系统稳定性，但说明客户端策略未处理好限频
(2) LiqService 清算状态异常 — 9 条 (HIGH)
tryTriggerLiqHandle account status error oldAccountStatus=NORMAL/MARGIN_CALL/CANCEL_ALL/CANCEL_OPEN
- 涉及用户: userId=123456，3 个 portfolioId：
- 11111 (BINANCE) — equity ≈ 19.6 USDT
- 22222 (BINANCE) — equity ≈ 35.2 USDT
- 33333 (BINANCE) — equity ≈ 1.0~1.5 USDT
- 原因: 清算引擎尝试触发清算处理时，账户状态不符合预期（如：想从 NORMAL 转到清算状态时发现状态不一致）
- 关注点: portfolioId 33333 的 equity 极低（仅 ~1 USDT），经历了完整的清算流程 MARGIN_CALL → CANCEL_OPEN → CANCEL_ALL
(3) cancel all/open exceed limit — 2 条 (HIGH)
cancel all exceed limit, portfolioId 33333
cancel open exceed limit, portfolioId 33333- 原因: 同一 portfolioId 33333 的清算撤单操作频率超过限制
- 关联: 与上面的 LiqService 状态异常是同一账户，清算过程中多次尝试撤单被限频
(4) OrderMonitor - ems not exist — 1 条
orderStateMonitor ems not exist. pid:11111, oid:666666, engine:OPEN
- 原因: 订单状态监控发现某订单的 EMS（执行管理系统）记录不存在
- 可能: 订单创建与 EMS 注册之间的时序问题，或 EMS 记录已被清理
---
3. 主机分布
┌──────────────┬──────┬─────────────────────────────┐ │ Host │ 条数 │ 主要错误 │
├──────────────┼──────┼─────────────────────────────┤
│ 10.19.5.136 │ 161 │ TRADE_MAX_ORDERS_ERROR 为主 │
├──────────────┼──────┼─────────────────────────────┤
│ 10.19.11.174 │ 11 │ LiqService 清算相关 │
└──────────────┴──────┴─────────────────────────────┘
---
4. 建议
┌────────┬───────────────────────────────┬───────────────────────────────────────────────────────────────────────────────────────────────────┐ │ 优先级 │ 行动 │ 说明 │
├────────┼───────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────┤
│ P1 │ 检查 userId=123456 账户健康度 │ 多个 portfolio 同时触发清算，equity 极低，需确认是否需人工干预 │
├────────┼───────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────┤
│ P2 │ 排查高频下单源 │ 10.19.5.136 上每 5 分钟爆发 158 次 MAX_ORDERS_ERROR，定位是哪个 API client / 策略在重复触碰限制 │
├────────┼───────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────┤
│ P3 │ 优化清算限频逻辑 │ cancel all/open exceed limit 说明清算过程中的撤单频率控制可能需要调整，避免清算流程被自身限频阻断 │
├────────┼───────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────┤
│ P4 │ 确认 EMS 数据一致性 │ ems not exist 虽然只有 1 条，但可能代表订单生命周期管理的隐患 │ └────────┴───────────────────────────────┴───────────────────────────────────────────────────────────────────────────────────────────────────┘
需要我针对某个具体问题深入排查吗？比如查看 userId=123456 的更多日志，或者分析下单源的 TraceId 链路。