프로덕션 환경에서 JamJet 워크플로우를 위한 트레이스, 메트릭, 로그.

관찰성

JamJet은 모든 실행에 대해 구조화된 추적, 메트릭, 로그를 생성합니다 — OpenTelemetry 및 이미 사용 중인 도구와 호환됩니다.

계측 항목

모든 JamJet 실행은 자동으로 다음을 생성합니다:

추적 — 실행별 및 노드별 스팬과 타이밍, 모델, 토큰 수
메트릭 — 실행 시간, 큐 깊이, 노드 지연, 토큰 사용량, 에러율
로그 — 모든 상태 전환에 대한 구조화된 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

스팬 속성

JamJet은 모델 스팬에 대해 GenAI 시맨틱 컨벤션을 따릅니다:

속성	값
`gen_ai.system`	`anthropic`, `openai` 등
`gen_ai.request.model`	모델 ID
`gen_ai.usage.input_tokens`	입력 토큰 수
`gen_ai.usage.output_tokens`	출력 토큰 수
`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은 기본적으로 stdout에 구조화된 JSON 로그를 출력합니다:

{
  "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에서 옵트인 방식입니다. 프로덕션 배포에서는 에이전트 동작에 대한 가시성을 보장하기 위해 텔레메트리가 기본적으로 활성화됩니다.

관찰 가능성

관찰성