Skip to content

otel-backends.md

Latest commit

 

History

History
113 lines (80 loc) · 3.06 KB

otel-backends.md

File metadata and controls

113 lines (80 loc) · 3.06 KB

OTel Backend Configuration

sightjack supports OpenTelemetry trace export to Jaeger (local) and Weave (Weights & Biases).

Jaeger (Local Development)

# Start Jaeger
docker run -d --name jaeger \
  -p 16686:16686 \
  -p 4318:4318 \
  jaegertracing/jaeger:latest

# Initialize with Jaeger backend
sightjack init --otel-backend=jaeger --team MY --project Hades

# Verify traces at http://localhost:16686

Weave (Weights & Biases)

# Set API key
export WANDB_API_KEY=your-key-here

# Initialize with Weave backend
sightjack init --otel-backend=weave \
  --otel-entity=my-team \
  --otel-project=my-project \
  --team MY --project Hades

# Verify traces at https://wandb.ai/<entity>/<project>/weave

Manual Override

Environment variables always take precedence over .otel.env:

OTEL_EXPORTER_OTLP_ENDPOINT=http://custom:4318 sightjack scan

.otel.env File

Generated by sightjack init --otel-backend at .siren/.otel.env. Format: KEY=VALUE with ${VAR} expansion and # comments.

Weave Verification

Manual

  1. export WANDB_API_KEY=your-key-here
  2. sightjack init --otel-backend=weave --otel-entity=my-team --otel-project=my-project --team MY --project Hades
  3. sightjack scan
  4. Open https://wandb.ai/<entity>/<project>/weave and verify spans appear

Automated (Live Test)

export WANDB_API_KEY=your-key-here
just test-weave-live

TestWeave_LiveTraceDelivery sends a minimal span to the real Weave OTLP endpoint and verifies the exporter completes without error. Skipped when WANDB_API_KEY is not set.

Attribute Value
OTLP Endpoint https://trace.wandb.ai/otel
Service Name sightjack
Span Name live-weave-verification
test.tool sightjack
test.type live-verification

GenAI Semantic Conventions

sightjack emits GenAI semantic convention attributes on provider.invoke spans:

  • gen_ai.operation.name=chat
  • gen_ai.system=anthropic
  • gen_ai.request.model=<model>

Cross-Tool OTel Conformance

All 4 tools (phonewave, sightjack, paintress, amadeus) share a common OTel emission contract. Each tool's telemetry tests verify conformance to prevent drift.

Root Span

Attribute Required Description
Span name Yes Tool-specific operation name
otel.status_code Yes OK on success, ERROR on failure

provider.invoke Span (sightjack, paintress, amadeus only)

Attribute Required Description
provider.model Yes Model name (e.g. "opus")
provider.timeout_sec Yes Timeout in seconds (context deadline or config)
gen_ai.operation.name Yes Always "chat"
gen_ai.system Yes Always "anthropic"
gen_ai.request.model Yes Model name

Verification

Each tool runs conformance checks in CI via go test:

  • phonewave: internal/session/daemon_otel_test.go
  • sightjack: tests/integration/telemetry_test.go
  • paintress: internal/session/telemetry_test.go
  • amadeus: internal/session/telemetry_test.go