Read this in other languages: English, 简体中文.

可观测性指南

概述

HotPlex 通过 OpenTelemetry 链路追踪、Prometheus 指标和健康检查提供全面的可观测性。

OpenTelemetry 链路追踪

配置

export OTEL_ENDPOINT="localhost:4317"
export OTEL_SERVICE_NAME="hotplex"
export OTEL_SAMPLING_RATE="1.0"

Spans (追踪跨度)

Span 名称	描述
session.execute	完整会话执行
tool.use	工具调用
security.danger_block	WAF 拦截事件

属性

属性	描述
session.id	会话标识符
namespace	命名空间
tool.name	工具名称
tool.id	工具调用 ID
danger.operation	被拦截的操作

Prometheus 指标

接口地址

GET /metrics

指标项

指标	类型	描述
hotplex_sessions_active	gauge	活动中的会话数
hotplex_sessions_total	counter	已创建的会话总数
hotplex_sessions_errors	counter	会话错误总数
hotplex_tools_invoked	counter	工具调用次数
hotplex_dangers_blocked	counter	WAF 拦截次数
hotplex_request_duration_seconds	histogram	请求延迟分布

Grafana 仪表盘

从 docs/grafana-dashboard.json 导入仪表盘。

健康检查

接口地址

GET /health       # 基础健康检查
GET /health/ready # 就绪探针
GET /health/live  # 存活探针

响应示例

{
  "status": "healthy",
  "checks": {
    "engine": true,
    "pool": true
  }
}

日志记录

结构化日志

{"level":"info","msg":"session started","session_id":"abc123","namespace":"default"}

日志级别

级别	使用场景
debug	详细调试信息
info	正常运行信息
warn	可恢复的错误
error	执行失败错误