可观测性

JamJet 为每次执行输出结构化的追踪、指标和日志——与 OpenTelemetry 及你已在使用的工具兼容。

哪些内容被监测

每次 JamJet 执行会自动输出：

追踪 — 每次执行和每个节点的 span，包含时序、模型、token 计数
指标 — 执行时长、队列深度、节点延迟、token 使用量、错误率
日志 — 每次状态转换的结构化 JSON 日志
事件 — 完整的执行事件日志（可通过 jamjet inspect 查询）

OpenTelemetry

JamJet 完全基于 OpenTelemetry 原生构建。在 jamjet.toml 中配置 OTLP 导出器：

[telemetry]
enabled = true
service_name = "my-agent"
service_version = "0.2.0"

[telemetry.otlp]
endpoint = "http://localhost:4317"   # OTLP gRPC

# 或

endpoint = "http://localhost:4318"   # OTLP HTTP

适用于任何兼容 OTLP 的后端：

追踪结构

每次执行产生一个追踪层级：

execution exec_01JM4X8NKWP2 (2.1s)
├── node:search (search) [tool] 823ms
│   └── mcp.call brave-search/web_search 820ms
├── node:draft (draft) [model] 1.1s
│   └── model.call claude-sonnet-4-6 1.09s
│       ├── input_tokens: 412
│       └── output_tokens: 891
└── node:evaluate (evaluate) [eval] 180ms
    └── eval.llm_judge claude-haiku 178ms
        └── score: 4.7

Span 属性

JamJet 遵循 GenAI 语义约定用于模型 span：

属性	值
`gen_ai.system`	`anthropic`、`openai` 等
`gen_ai.request.model`	模型 ID
`gen_ai.usage.input_tokens`	输入 token 数
`gen_ai.usage.output_tokens`	输出 token 数
`jamjet.workflow.id`	工作流 ID
`jamjet.workflow.version`	工作流版本
`jamjet.execution.id`	执行 ID
`jamjet.node.id`	节点 ID
`jamjet.node.kind`	节点类型

Prometheus 指标

启用 Prometheus 抓取端点：

[telemetry.prometheus]
enabled = true
port = 9090

可用指标：

指标	类型	描述
`jamjet_executions_total`	Counter	按工作流 + 状态统计的总执行次数
`jamjet_execution_duration_ms`	Histogram	端到端执行时间
`jamjet_node_duration_ms`	Histogram	按节点类型统计的单节点执行时间
`jamjet_queue_depth`	Gauge	队列中待处理的执行数量
`jamjet_model_tokens_total`	Counter	按模型和方向统计的令牌使用量
`jamjet_model_cost_usd_total`	Counter	按模型统计的预估成本

查询 p99 执行延迟的 Prometheus 示例：

histogram_quantile(0.99,
  rate(jamjet_execution_duration_ms_bucket[5m])
)

Grafana 仪表板

导入官方 JamJet Grafana 仪表板（ID：jamjet-runtime）以获取预构建的概览：

执行吞吐量和错误率
模型延迟分布
随时间变化的令牌使用量和成本
队列深度和工作器饱和度

结构化日志

JamJet 默认将结构化 JSON 日志输出到 stdout：

{
  "timestamp": "2026-03-07T09:31:00.012Z",
  "level": "info",
  "event": "node_completed",
  "execution_id": "exec_01JM4X8NKWP2",
  "workflow_id": "research-agent",
  "node_id": "think",
  "node_kind": "model",
  "model": "claude-haiku-4-5-20251001",
  "duration_ms": 512,
  "input_tokens": 64,
  "output_tokens": 312
}

在 jamjet.toml 中配置日志级别和格式：

[logging]
level = "info"       # debug | info | warn | error
format = "json"      # json | text

检查执行

jamjet inspect 命令可在本地获取完整的执行追踪，无需任何可观测性后端：

jamjet inspect exec_01JM4X8NKWP2
jamjet inspect exec_01JM4X8NKWP2 --events    # 完整事件时间线
jamjet inspect exec_01JM4X8NKWP2 --state     # 仅最终状态

告警

使用 Prometheus + Alertmanager 添加告警：


# alerts.yml

groups:
  - name: jamjet
    rules:
      - alert: HighExecutionErrorRate
        expr: |
          rate(jamjet_executions_total{status="failed"}[5m]) /
          rate(jamjet_executions_total[5m]) > 0.05
        for: 2m
        annotations:
          summary: "JamJet 错误率超过 5%"

      - alert: ExecutionQueueBacklog
        expr: jamjet_queue_depth > 100
        for: 5m
        annotations:
          summary: "JamJet 执行队列正在积压"

注意： 所有遥测数据在 jamjet dev 中都是可选的。在生产部署中，遥测功能默认启用，以确保您能够了解智能体的行为。

可观测性

On this page