Observability

JamJet gibt strukturierte Traces, Metriken und Logs für jede Ausführung aus – kompatibel mit OpenTelemetry und den Tools, die Sie bereits verwenden.

Was instrumentiert wird

Jede JamJet-Ausführung gibt automatisch aus:

Traces — Spans pro Ausführung und pro Node mit Timing, Modell und Token-Anzahl
Metriken — Ausführungsdauer, Queue-Tiefe, Node-Latenz, Token-Nutzung, Fehlerraten
Logs — strukturierte JSON-Logs für jeden Zustandsübergang
Events — das vollständige Execution-Event-Log (abfragbar via jamjet inspect)

OpenTelemetry

JamJet ist vollständig OpenTelemetry-nativ. Konfigurieren Sie einen OTLP-Exporter in jamjet.toml:

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

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

# oder

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

Dies funktioniert mit jedem OTLP-kompatiblen Backend:

Trace-Struktur

Jede Ausführung erzeugt eine Trace-Hierarchie:

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-Attribute

JamJet folgt den GenAI Semantic Conventions für Model-Spans:

Attribut	Wert
`gen_ai.system`	`anthropic`, `openai`, etc.
`gen_ai.request.model`	Modell-ID
`gen_ai.usage.input_tokens`	Anzahl der Input-Token
`gen_ai.usage.output_tokens`	Anzahl der Output-Token
`jamjet.workflow.id`	Workflow-ID
`jamjet.workflow.version`	Workflow-Version
`jamjet.execution.id`	Execution-ID
`jamjet.node.id`	Node-ID
`jamjet.node.kind`	Node-Typ

Prometheus-Metriken

Aktivieren Sie den Prometheus-Scrape-Endpunkt:

[telemetry.prometheus]
enabled = true
port = 9090

Verfügbare Metriken:

Metrik	Typ	Beschreibung
`jamjet_executions_total`	Counter	Gesamtzahl der Ausführungen nach Workflow + Status
`jamjet_execution_duration_ms`	Histogram	End-to-End-Ausführungszeit
`jamjet_node_duration_ms`	Histogram	Ausführungszeit pro Node nach Node-Typ
`jamjet_queue_depth`	Gauge	Ausstehende Ausführungen in der Warteschlange
`jamjet_model_tokens_total`	Counter	Token-Nutzung nach Modell und Richtung
`jamjet_model_cost_usd_total`	Counter	Geschätzte Kosten nach Modell

Beispiel einer Prometheus-Abfrage für p99-Ausführungslatenz:

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

Grafana-Dashboard

Importieren Sie das offizielle JamJet Grafana-Dashboard (ID: jamjet-runtime) für eine vorkonfigurierte Übersicht:

Ausführungsdurchsatz und Fehlerrate
Modell-Latenzverteilung
Token-Nutzung und Kosten im Zeitverlauf
Warteschlangentiefe und Worker-Auslastung

Strukturierte Logs

JamJet gibt standardmäßig strukturierte JSON-Logs nach stdout aus:

{
  "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
}

Konfigurieren Sie Log-Level und Format in jamjet.toml:

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

Ausführungen inspizieren

Der Befehl jamjet inspect liefert Ihnen den vollständigen Ausführungs-Trace lokal ohne Observability-Backend:

jamjet inspect exec_01JM4X8NKWP2
jamjet inspect exec_01JM4X8NKWP2 --events    # vollständige Event-Timeline
jamjet inspect exec_01JM4X8NKWP2 --state     # nur finaler Zustand

Alerting

Mit Prometheus + Alertmanager fügen Sie Alerts hinzu für:


# 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-Fehlerrate über 5%"

      - alert: ExecutionQueueBacklog
        expr: jamjet_queue_depth > 100
        for: 5m
        annotations:
          summary: "JamJet-Ausführungswarteschlange staut sich"

Hinweis: Alle Telemetrie ist in jamjet dev opt-in. In Produktionsumgebungen ist Telemetrie standardmäßig aktiviert, um sicherzustellen, dass Sie Einblick in das Agentenverhalten haben.

Observability

On this page