SuperAPI AI 工具集

jaeger

部署与运维

查看项目

更新于 10-16 09:30

技能介绍

用途:在开发阶段使用本地 Jaeger 实例检查 Gram 服务端(gram-server)与 worker(gram-worker)发出的 OpenTelemetry 追踪数据,用于调试后端行为。

架构与启动:Gram 运行一个本地 OTel Collector,接收来自应用的 OTLP 信号,将追踪路由到 Jaeger,将指标路由到 Prometheus;spanmetrics connector 还会从追踪派生 RED 指标。全部基础设施随 mise run infra:start 自动启动。

端口发现:Jaeger 端口由 mise.toml 中的环境变量配置,应始终从环境变量读取,不要硬编码,因为不同工作树或本地覆盖可能不同。查看方式:echo $JAEGER_WEB_PORT 与 echo $OTLP_GRPC_PORT。Web UI 位于 http://localhost:$JAEGER_WEB_PORT,OTLP gRPC 接收端为 localhost:$OTLP_GRPC_PORT,REST API 前缀为 http://localhost:$JAEGER_WEB_PORT/api/。

REST API:列出服务 GET /api/services;搜索追踪 GET /api/traces?service=gram-server&limit=20,支持 operation、tags(JSON)、start/end(微秒 Unix 时间戳)、limit(默认 20)、minDuration/maxDuration(如 1ms、500ms、2s)、lookback(如 1h、2h、1d);获取单条追踪 GET /api/traces/{traceID},包含跨服务跨度;列出某服务的操作 GET /api/services/{service}/operations。

开发流程:mise run infra:start 启动基础设施;mise start:server --dev-single-process 启动服务端;运行种子数据或调用端点以触发目标代码路径;再用 API 或 UI 查询追踪,关注慢跨度、错误跨度(error=true)、缺失埋点与 N+1 查询模式。

追踪结构:HTTP 跨度由 otelhttp 中间件创建,operation 形如 HTTP <method> <route>;数据库跨度由 pgx tracing 创建,operation 为 SQL 查询;还有 Temporal 活动与工作流跨度,以及通过 tracer.Start(ctx, "operation-name") 创建的自定义跨度。常见属性包括 http.method、http.route、http.status_code、db.statement、service.name、error。

Prometheus:位于 http://localhost:$PROMETHEUS_PORT,存储应用指标和由追踪派生的 RED 指标;示例查询包括 calls_total{service_name="gram-server"}、calls_total{status_code="STATUS_CODE_ERROR"}、histogram_quantile(0.99, sum(rate(duration_milliseconds_bucket[5m])) by (le, service_name))。

环境变量:OTLP_GRPC_HOST(localhost)、OTLP_GRPC_PORT(4317)、OTEL_EXPORTER_OTLP_ENDPOINT(http://localhost:4317)、JAEGER_WEB_PORT(16686)、PROMETHEUS_PORT(9099)、GRAM_ENABLE_OTEL_TRACES(1)、GRAM_ENABLE_OTEL_METRICS(1),均在 mise.toml 中配置。

限制:资料未提供 Jaeger 自身的版本、安装方式与鉴权细节,也未说明生产环境使用方式。