文档
使用指引
服务端和客户端
可观测化

可观测化

Twinkle Server 通过 OpenTelemetry 提供完整的可观测性支持，覆盖 traces（链路追踪）、metrics（指标）和 logs（日志）三个维度。

快速开始

1. 启动观测栈

项目提供了一键式的 Docker Compose 配置，基于 grafana/otel-lgtm 镜像（内置 OTel Collector、Mimir、Tempo、Loki 和 Grafana）：

cd cookbook/observability
docker compose up -d

启动后可用服务：

服务地址用途
Grafanahttp://localhost:3000仪表盘和数据探索
OTLP gRPClocalhost:4317Twinkle 的 otlp_endpoint 指向此处
OTLP HTTPlocalhost:4318同上，HTTP 替代

2. 配置 Server

在 server_config.yaml 中启用遥测：

telemetry:
  enabled: true
  otlp_endpoint: http://localhost:4317

3. 安装依赖

pip install opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp

4. 启动 Server

twinkle-server launch -c server_config.yaml

5. 访问 Grafana

打开 http://localhost:3000，默认账号 admin / admin。

telemetry 配置字段

字段类型默认值说明
enabledboolfalse是否启用遥测管线
service_namestrtwinkle-server上报的服务名称
otlp_endpointstrhttp://localhost:4317OTel Collector 的 gRPC 地址
debugboolfalse为 true 时将 spans/metrics 输出到控制台（不走 OTLP）
export_interval_msint30000指标导出间隔（毫秒）
resource_attributesdict{}附加到所有遥测数据的资源属性

内置 Grafana 仪表盘

预配置的 Twinkle Server Overview 仪表盘包含以下面板：

  • HTTP 请求速率和 P95 延迟（按 Gateway / Model / Sampler / Processor 分组）
  • 活跃资源数（sessions、models、sampling sessions、futures）
  • 任务队列深度、执行 P95、等待时间 P95
  • 限流拒绝数和任务完成状态统计

指标命名参考

Twinkle 使用点号分隔的 OpenTelemetry 指标名。Prometheus OTLP 接收端会将点号转为下划线，并为单调计数器追加 _total：

OpenTelemetry 名Prometheus 名
twinkle.http.requests.totaltwinkle_http_requests_total
twinkle.http.request.duration_secondstwinkle_http_request_duration_seconds_bucket
twinkle.queue.depthtwinkle_queue_depth
twinkle.task.execution_secondstwinkle_task_execution_seconds_bucket
twinkle.task.wait_secondstwinkle_task_wait_seconds_bucket
twinkle.rate_limit.rejections.totaltwinkle_rate_limit_rejections_total
twinkle.tasks.totaltwinkle_tasks_total
twinkle.sessions.activetwinkle_sessions_active
twinkle.models.activetwinkle_models_active
twinkle.sampling_sessions.activetwinkle_sampling_sessions_active
twinkle.futures.activetwinkle_futures_active

*.active 资源 gauge 直接读取绝对值，不要对其使用 rate() 或 increase()。

链路追踪

Twinkle 的 spans 命名空间为 twinkle.server.<component>（Gateway / Model / Sampler / Processor）。每个请求携带 twinkle.session_id 和 trace_id 关联键，支持跨部署的全链路追踪。

在 Grafana 中切换数据源为 Tempo 即可按 service name 或 span name 搜索链路。

生产部署建议

cookbook/observability 中的 LGTM 一体化镜像仅适用于本地开发和演示。生产环境建议：

  • 分别部署 Mimir / Tempo / Loki / Grafana，配合持久化存储和多副本
  • 前置独立的 OTel Collector 层进行采样和路由
  • server_config.yaml 中的 telemetry 配置和指标名称在生产环境保持不变

常见问题

Grafana 显示 “No data”

  • 确认 telemetry.enabled: true
  • 确认 worker 日志中出现 Worker telemetry initialized
  • 设置 debug: true 可先在控制台确认 spans 正常产生，再切回 debug: false

Twinkle 无法连接到 Collector

  • otlp_endpoint 必须从 Twinkle 进程可达。如果 Twinkle 运行在另一个容器中，使用 Docker 网络内部地址如 http://twinkle-lgtm:4317

资源 gauge 一直为 0

  • 只有 cleanup-leader worker 推送资源计数。如果超过 export_interval_ms × 2 后仍为 0，检查日志中是否有 “became cleanup leader” 消息

清理

cd cookbook/observability
docker compose down -v   # -v 同时删除数据卷
docs