@opensearch-project/agent-health 0.3.0 → 0.5.2

package/docs/BACKEND_JOB_QUEUE.md

@@ -0,0 +1,405 @@
+# Backend Job Queue for Experiment Runs
+
+## Overview
+
+Move experiment evaluation from browser to backend with a persistent job queue.
+
+**Goal**: Close browser, experiments keep running. Monitor progress anytime.
+
+**Features**:
+- Queue experiments to run in background
+- Start, stop, pause (between use cases), resume
+- Real-time SSE streaming of trajectory steps
+- File-based persistence (survives server restarts)
+
+---
+
+## Milestone Breakdown
+
+### Milestone 1: Backend Can Run a Single Evaluation
+
+**Scope**: Prove backend can call agent, convert events, call judge - same as browser does today.
+
+#### Tasks
+
+- [ ] **A1**: Copy `aguiConverter.ts` to `server/services/` (replace debug import with console)
+- [ ] **A2**: Copy `payloadBuilder.ts` to `server/services/` (just copy, no changes)
+- [ ] **A3**: Create `server/services/nodeSSEClient.ts` (adapt browser SSE client for Node)
+- [ ] **A4**: Create `server/services/evaluationService.ts` (port runEvaluation logic)
+- [ ] **A6-partial**: Create test endpoint `POST /api/eval/test` in `server/routes/eval.ts`
+
+#### How to Verify
+
+```bash
+# 1. Start the server
+npm run dev:server
+
+# 2. Call the test endpoint with a test case ID
+curl -X POST http://localhost:4001/api/eval/test \
+  -H "Content-Type: application/json" \
+  -d '{"testCaseId": "YOUR_TEST_CASE_ID", "agentKey": "YOUR_AGENT", "modelId": "YOUR_MODEL"}'
+
+# 3. Check the response has:
+#    - trajectory array with steps
+#    - metrics with accuracy score
+#    - status: "completed" or "failed"
+#    - runId captured from agent
+```
+
+#### Success Criteria
+
+- [ ] Response contains trajectory steps (action, tool_result, assistant, response)
+- [ ] Response contains metrics from judge
+- [ ] runId is captured (check server logs: `[EvalService] Agent completed, runId: xxx`)
+- [ ] Report is saved to OpenSearch
+
+---
+
+### Milestone 2: File-Based Job Queue (No SSE Yet)
+
+**Scope**: Jobs can be submitted, started, and persist to file. Poll for status.
+
+#### Tasks
+
+- [ ] **C1**: Create `types/jobs.ts` with job types
+- [ ] **C2**: Create `server/services/jobStorage.ts` for file persistence
+- [ ] **A5**: Create `server/services/jobQueue.ts` (without SSE broadcasting)
+- [ ] **A6**: Create `/api/jobs/*` routes in `server/routes/jobs.ts`
+- [ ] Mount routes in `server/routes/index.ts`
+- [ ] Initialize job queue in `server/index.ts`
+
+#### How to Verify
+
+```bash
+# 1. Submit a job
+curl -X POST http://localhost:4001/api/jobs \
+  -H "Content-Type: application/json" \
+  -d '{"experimentId": "YOUR_EXP_ID", "runConfig": {"name": "Test Run", "agentKey": "xxx", "modelId": "yyy"}}'
+# → Returns job with status: "queued"
+
+# 2. Check file was created
+cat server/data/jobs/queue.json
+# → Should show job in jobs array
+
+# 3. List jobs via API
+curl http://localhost:4001/api/jobs
+# → Returns { jobs: [...] }
+
+# 4. Start the job
+curl -X POST http://localhost:4001/api/jobs/JOB_ID/start
+# → Returns { success: true }
+
+# 5. Poll for status (repeat until completed)
+curl http://localhost:4001/api/jobs/JOB_ID
+# → Watch status change: queued → running → completed
+
+# 6. Restart server mid-job, check recovery
+# Kill server (Ctrl+C), restart, check queue.json - job should be "paused"
+
+# 7. Cancel a running job
+curl -X POST http://localhost:4001/api/jobs/JOB_ID/cancel
+```
+
+#### Success Criteria
+
+- [ ] Jobs persist in `server/data/jobs/queue.json`
+- [ ] Job transitions: queued → running → completed
+- [ ] Use cases execute sequentially (check server logs)
+- [ ] Reports are saved for each completed use case
+- [ ] Server restart marks running job as paused
+- [ ] Cancel stops job after current use case
+
+---
+
+### Milestone 3: SSE Streaming for Real-Time Progress
+
+**Scope**: Clients can subscribe to job events, see trajectory steps live.
+
+#### Tasks
+
+- [ ] **C3**: Create `server/services/sseManager.ts`
+- [ ] **A5-update**: Add SSE broadcasting to job queue service
+- [ ] **A6-update**: Add `/api/jobs/:id/stream` endpoint
+
+#### How to Verify
+
+```bash
+# 1. In terminal 1: Subscribe to job stream
+curl -N http://localhost:4001/api/jobs/JOB_ID/stream
+# → Should see: data: {"type":"connected"}
+
+# 2. In terminal 2: Start the job
+curl -X POST http://localhost:4001/api/jobs/JOB_ID/start
+
+# 3. Watch terminal 1 - should see streaming events:
+#    data: {"type":"job:status","data":{"status":"running"}}
+#    data: {"type":"job:progress","data":{"useCaseId":"xxx","status":"running"}}
+#    data: {"type":"job:trajectory","data":{"step":{"type":"action",...}}}
+#    data: {"type":"job:trajectory","data":{"step":{"type":"tool_result",...}}}
+#    ... more trajectory steps ...
+#    data: {"type":"job:progress","data":{"useCaseId":"xxx","status":"completed"}}
+#    data: {"type":"job:complete","data":{...}}
+
+# 4. Open multiple terminals with curl -N, verify all receive same events
+```
+
+#### Success Criteria
+
+- [ ] SSE connection stays open
+- [ ] Trajectory steps stream in real-time (as agent executes)
+- [ ] Multiple clients receive same events
+- [ ] Keep-alive pings prevent timeout
+- [ ] Client disconnect doesn't crash server
+
+---
+
+### Milestone 4: Pause/Resume Works
+
+**Scope**: Pause a running job between use cases, resume later.
+
+#### Tasks
+
+- [ ] **A5-update**: Add pause/resume logic to job queue service
+
+#### How to Verify
+
+```bash
+# 1. Start a job with multiple use cases
+curl -X POST http://localhost:4001/api/jobs/JOB_ID/start
+
+# 2. Wait for first use case to complete (watch logs or SSE)
+# Server log: "[JobQueue] Use case 0 completed"
+
+# 3. Pause the job
+curl -X POST http://localhost:4001/api/jobs/JOB_ID/pause
+
+# 4. Check status - should be "paused"
+curl http://localhost:4001/api/jobs/JOB_ID
+# → status: "paused", currentUseCaseIndex: 1
+
+# 5. Check queue.json - should persist paused state
+cat server/data/jobs/queue.json
+
+# 6. Resume the job
+curl -X POST http://localhost:4001/api/jobs/JOB_ID/resume
+
+# 7. Watch it continue from where it left off
+# Server log: "[JobQueue] Resuming job at index 1"
+```
+
+#### Success Criteria
+
+- [ ] Pause takes effect after current use case completes
+- [ ] Paused state persists in file
+- [ ] Resume continues from next use case (not from beginning)
+- [ ] All results preserved (use cases 0-N completed before pause)
+
+---
+
+### Milestone 5: Frontend Integration
+
+**Scope**: UI uses job queue instead of browser-based execution.
+
+#### Tasks
+
+- [ ] **B1**: Create `services/api/jobsApi.ts` client
+- [ ] **B2**: Create `hooks/useJobStream.ts` hook
+- [ ] **B3**: Create `components/JobProgressPanel.tsx` component
+- [ ] **B4**: Update `components/ExperimentRunsPage.tsx` with feature flag
+
+#### How to Verify
+
+1. Open the app in browser, go to an experiment
+2. Click "Add Run", configure, click "Start"
+3. Verify: Job is submitted (check Network tab: POST /api/jobs)
+4. Verify: Progress panel shows live updates
+5. Verify: Trajectory steps appear as they stream
+6. Close browser tab
+7. Reopen browser, go back to experiment
+8. Verify: Job is still running (or completed)
+9. Verify: Results appear correctly
+
+#### Success Criteria
+
+- [ ] UI submits job instead of running in browser
+- [ ] Live progress updates via SSE
+- [ ] Can close browser, job continues
+- [ ] Pause/Resume buttons work
+- [ ] Final results match what old system produced
+
+---
+
+### Milestone 6: Cleanup & Polish
+
+**Scope**: Remove feature flag, clean up old code, handle edge cases.
+
+#### Tasks
+
+- [ ] Remove feature flag, make job queue the default
+- [ ] Handle edge cases (network errors, agent timeouts)
+- [ ] Add job history cleanup (delete old completed jobs)
+- [ ] Update documentation
+
+---
+
+## Implementation Timeline
+
+```
+Week 1: Milestone 1 (Backend Eval)
+├── Copy aguiConverter to server
+├── Copy payloadBuilder to server
+├── Create nodeSSEClient
+├── Create evaluationService
+└── Add test endpoint
+    └── VERIFY: curl test works ✓
+
+Week 2: Milestone 2 (Job Queue)
+├── Create job types
+├── Create jobStorage
+├── Create jobQueue
+└── Create job routes
+    └── VERIFY: Job lifecycle via curl ✓
+
+Week 3: Milestone 3 + 4 (SSE + Pause/Resume)
+├── Create sseManager
+├── Add broadcasting to queue
+├── Add stream endpoint
+└── Add pause/resume logic
+    └── VERIFY: SSE stream + pause works ✓
+
+Week 4: Milestone 5 (Frontend)
+├── Create jobsApi
+├── Create useJobStream hook
+├── Create JobProgressPanel
+└── Update ExperimentRunsPage
+    └── VERIFY: Full flow in browser ✓
+```
+
+---
+
+## Files to Create
+
+| File | Milestone | Description |
+|------|-----------|-------------|
+| `types/jobs.ts` | M2 | Job types |
+| `server/services/aguiConverter.ts` | M1 | Copy from frontend |
+| `server/services/payloadBuilder.ts` | M1 | Copy from frontend |
+| `server/services/nodeSSEClient.ts` | M1 | Node SSE consumer |
+| `server/services/evaluationService.ts` | M1 | Backend eval logic |
+| `server/services/jobStorage.ts` | M2 | File persistence |
+| `server/services/jobQueue.ts` | M2 | Queue orchestrator |
+| `server/services/sseManager.ts` | M3 | Client broadcasting |
+| `server/routes/jobs.ts` | M2 | API endpoints |
+| `services/api/jobsApi.ts` | M5 | Frontend API client |
+| `hooks/useJobStream.ts` | M5 | SSE subscription |
+| `components/JobProgressPanel.tsx` | M5 | Progress UI |
+
+## Files to Modify
+
+| File | Milestone | Change |
+|------|-----------|--------|
+| `server/routes/index.ts` | M2 | Mount job routes |
+| `server/index.ts` | M2 | Initialize job queue on startup |
+| `components/ExperimentRunsPage.tsx` | M5 | Add feature flag + job integration |
+
+---
+
+## Backward Compatibility
+
+During Milestone 5, use a feature flag:
+
+```typescript
+// In ExperimentRunsPage.tsx
+const USE_BACKEND_JOBS = true; // Toggle to test
+
+const handleStartRun = async () => {
+  if (USE_BACKEND_JOBS) {
+    // New: Submit to backend job queue
+    const job = await jobsApi.submit(experimentId, runConfigValues);
+    await jobsApi.start(job.id);
+    setActiveJobId(job.id);
+  } else {
+    // Old: Run in browser (existing code, unchanged)
+    await runExperiment(experiment, runConfigValues, onProgress);
+  }
+};
+```
+
+This enables:
+- **A/B testing**: Run same test case both ways, compare results
+- **Quick rollback**: Set flag to false if issues found
+- **Gradual rollout**: Enable for some users first
+
+---
+
+## Technical Details
+
+### Job Types (`types/jobs.ts`)
+
+```typescript
+export type JobStatus = 'queued' | 'running' | 'paused' | 'completed' | 'failed' | 'cancelled';
+
+export interface ExperimentJob {
+  id: string;
+  experimentId: string;
+  experimentName: string;
+  runConfig: RunConfigInput;
+  status: JobStatus;
+  useCaseIds: string[];
+  currentUseCaseIndex: number;
+  currentUseCaseId: string | null;
+  results: Record<string, { reportId: string; status: RunResultStatus }>;
+  createdAt: string;
+  startedAt: string | null;
+  pausedAt: string | null;
+  completedAt: string | null;
+  error: string | null;
+  experimentRunId: string | null;
+}
+
+export type JobEventType = 'job:status' | 'job:progress' | 'job:trajectory' | 'job:complete' | 'job:error';
+
+export interface JobEvent {
+  type: JobEventType;
+  jobId: string;
+  timestamp: number;
+  data: unknown;
+}
+```
+
+### API Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/api/jobs` | Submit new job |
+| `GET` | `/api/jobs` | List all jobs |
+| `GET` | `/api/jobs/:id` | Get job details |
+| `POST` | `/api/jobs/:id/start` | Start queued job |
+| `POST` | `/api/jobs/:id/pause` | Pause running job |
+| `POST` | `/api/jobs/:id/resume` | Resume paused job |
+| `POST` | `/api/jobs/:id/cancel` | Cancel job |
+| `DELETE` | `/api/jobs/:id` | Delete from history |
+| `GET` | `/api/jobs/:id/stream` | SSE stream for progress |
+
+### File Storage Structure
+
+```
+server/
+  data/
+    jobs/
+      queue.json       # Active jobs
+      history/
+        {jobId}.json   # Archived completed/failed jobs
+```
+
+### Key Implementation Notes
+
+1. **AG UI Converter** (`services/agent/aguiConverter.ts`) is already Node.js compatible - just needs debug import changed
+
+2. **Payload Builder** (`services/agent/payloadBuilder.ts`) is 100% portable - pure functions, no browser APIs
+
+3. **SSE in Node.js** - Use native `fetch` (Node 18+) with `ReadableStream.getReader()` - same as browser
+
+4. **Pause Logic** - Set a flag, checked between use cases. Current use case always completes.
+
+5. **Server Restart Recovery** - On startup, scan queue for `status: 'running'`, mark as `'paused'`

package/docs/CLAUDE_CODE_TELEMETRY.md

@@ -0,0 +1,283 @@
+<!--
+  * Copyright OpenSearch Contributors
+  * SPDX-License-Identifier: Apache-2.0
+-->
+
+# Claude Code Telemetry → Agent Health
+
+Route Claude Code's native OpenTelemetry telemetry (traces, logs, metrics) into the same OpenSearch cluster used by Agent Health, so you can view Claude Code sessions alongside your other agent traces.
+
+## Quick Setup (Recommended)
+
+If you deployed the Agent Health Observability CloudFormation stack, it includes an API Gateway with a Lambda SigV4 proxy. Claude Code can send telemetry directly to it — no Docker or local collector needed.
+
+### 1. Get Your API Gateway URL
+
+From CloudFormation stack outputs:
+
+```bash
+aws cloudformation describe-stacks \
+  --stack-name AgentHealthObservability \
+  --query "Stacks[0].Outputs[?OutputKey=='OTLPIngestEndpoint'].OutputValue" \
+  --output text
+```
+
+### 2. Configure Claude Code
+
+Add to your `~/.zshrc` (or `~/.bashrc`):
+
+```bash
+# --- Claude Code OpenTelemetry ---
+export CLAUDE_CODE_ENABLE_TELEMETRY=1
+
+# Exporters (all three signals)
+export OTEL_METRICS_EXPORTER=otlp
+export OTEL_LOGS_EXPORTER=otlp
+export OTEL_TRACES_EXPORTER=otlp
+
+# Point at API Gateway (Lambda proxies to OSIS with SigV4)
+export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
+export OTEL_EXPORTER_OTLP_ENDPOINT=https://<YOUR-API-GATEWAY-URL>
+```
+
+Then reload and start a new Claude Code session:
+
+```bash
+source ~/.zshrc
+claude
+```
+
+Telemetry begins flowing automatically. No restart of the API Gateway or OSIS needed.
+
+### 3. View in Agent Health
+
+Open Agent Health → **Agent Traces** tab. Claude Code appears as service `claude-code`. Expand the time range filter if recent sessions don't appear immediately (OSIS ingestion has a short delay).
+
+Each Claude Code conversation becomes a trace with spans for:
+- `interaction` — top-level user turn
+- `llm_request` — model API calls (with token counts and cost)
+- `tool` / `tool.execution` — tool invocations and results
+
+## Privacy Note
+
+Even with default settings (no opt-in flags), Claude Code telemetry includes `session.id`, `user.account_uuid`, and `organization.id` in every span. These are account-level identifiers, not conversation content.
+
+To include prompt and tool content in spans (useful for debugging, but sends conversation data to OpenSearch):
+
+```bash
+# Optional — has privacy implications
+export OTEL_LOG_USER_PROMPTS=1
+export OTEL_LOG_TOOL_DETAILS=1
+export OTEL_LOG_TOOL_CONTENT=1
+```
+
+## What Data Lands in OpenSearch
+
+| Signal | Data | Index Pattern |
+|--------|------|---------------|
+| **Traces** | Span hierarchy: `interaction` → `llm_request` / `tool` → `tool.execution` | `otel-v1-apm-span-*` |
+| **Logs/Events** | `user_prompt`, `api_request`, `tool_result`, `tool_decision`, `compaction` events | `otel-logs-*` |
+| **Metrics** | `claude_code.cost.usage`, `claude_code.token.usage`, `claude_code.session.count`, etc. | Not supported by OSIS (no OTLP metrics receiver) |
+
+### Key Span Attributes
+
+Every span includes `service.name: claude-code`, `session.id`, `user.account_uuid`, and `organization.id`. LLM request spans add `model`, `input_tokens`, `output_tokens`, `cost_usd`, `duration_ms`. Tool spans add `tool_name`, `result_tokens`.
+
+> **Run correlation (Strategy D).** Because Claude Code stamps a stable
+> `session.id` on *every* span of a run — and emits neither our
+> `agent_health.run.id` nor a W3C `traceparent` we control — Agent Health
+> correlates its spans by that `session.id`. `ClaudeCodeConnector` captures the
+> `session_id` from the stream-json output, persists it as `report.sessionId`,
+> and the run-report Traces tab / trace judge query `attributes.session.id`
+> (unioned with the service-name + time-window fallback). See
+> [AGENTS.md → Trace correlation conventions](../AGENTS.md).
+
+See the [Claude Code monitoring docs](https://code.claude.com/docs/en/monitoring-usage) for the full attribute reference.
+
+## Verification
+
+### Check OpenSearch for Claude Code spans
+
+```bash
+curl -s "https://<opensearch-endpoint>/otel-v1-apm-span-*/_search" \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "size": 5,
+    "query": { "match": { "serviceName": "claude-code" } },
+    "sort": [{ "startTime": "desc" }]
+  }' | jq '.hits.hits[]._source.spanId'
+```
+
+Or open Agent Health → Agent Traces and filter by service name `claude-code`.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| No spans in Agent Traces | Time range too narrow | Expand to "Last 7d"; OSIS ingestion can have a short delay |
+| `HTTP 403` from API Gateway | IAM credentials expired or wrong account | Refresh credentials; Lambda assumes a role in the stack's account |
+| Traces arrive but no logs | OSIS has no logs pipeline | Deploy the full CFN stack which includes `otel_logs_source` pipeline |
+| Spans arrive but no service map | Service map processor not in OSIS | The Agent Health CFN template includes `otel-service-map-pipeline` by default |
+
+## Advanced: Local ADOT Collector
+
+If you can't use the API Gateway (e.g., air-gapped environment, custom processing), you can run a local ADOT collector that signs requests with SigV4 and forwards to OSIS directly.
+
+<details>
+<summary>ADOT Collector setup</summary>
+
+### Architecture
+
+```
+Claude Code ──OTLP (gRPC, localhost)──▶ ADOT Collector (Docker)
+                                            │
+                              SigV4-signed HTTPS
+                                            │
+                          ┌─────────────────┼─────────────────┐
+                          ▼                 ▼                 ▼
+                   OSIS Traces        OSIS Logs         (metrics via
+                   Pipeline           Pipeline           logs pipeline)
+                          │                 │
+                          ▼                 ▼
+                      OpenSearch (otel-v1-apm-span-* / otel-logs-*)
+```
+
+### Prerequisites
+
+- Docker installed and running
+- AWS credentials with `osis:Ingest` permission on your pipelines
+
+### Get Your OSIS Endpoints
+
+```bash
+# Traces endpoint
+aws cloudformation describe-stacks \
+  --stack-name AgentHealthObservability \
+  --query "Stacks[0].Outputs[?OutputKey=='OSISTraceIngestEndpoint'].OutputValue" \
+  --output text
+
+# Logs endpoint
+aws cloudformation describe-stacks \
+  --stack-name AgentHealthObservability \
+  --query "Stacks[0].Outputs[?OutputKey=='OSISLogsIngestEndpoint'].OutputValue" \
+  --output text
+```
+
+### Collector Config
+
+Create `~/.claude/otel-collector-config.yaml`:
+
+```yaml
+receivers:
+  otlp:
+    protocols:
+      grpc:
+        endpoint: 0.0.0.0:4317
+      http:
+        endpoint: 0.0.0.0:4318
+
+processors:
+  batch:
+    timeout: 10s
+    send_batch_size: 512
+
+exporters:
+  otlphttp/traces:
+    endpoint: "https://<YOUR-OSIS-TRACES-ENDPOINT>"
+    encoding: json          # REQUIRED: OSIS rejects protobuf with HTTP 500
+    compression: none       # Avoid gzip issues with SigV4 body signing
+    auth:
+      authenticator: sigv4auth
+
+  otlphttp/logs:
+    endpoint: "https://<YOUR-OSIS-LOGS-ENDPOINT>"
+    encoding: json
+    compression: none
+    auth:
+      authenticator: sigv4auth
+
+extensions:
+  sigv4auth:
+    region: "us-west-2"      # ← your OSIS pipeline region
+    service: "osis"
+
+service:
+  extensions: [sigv4auth]
+  pipelines:
+    traces:
+      receivers: [otlp]
+      processors: [batch]
+      exporters: [otlphttp/traces]
+    logs:
+      receivers: [otlp]
+      processors: [batch]
+      exporters: [otlphttp/logs]
+```
+
+> **Important:** `encoding: json` and `compression: none` are **required**. OSIS rejects OTLP protobuf payloads with HTTP 500.
+
+### Docker Compose
+
+Create `~/.claude/docker-compose-otel.yaml`:
+
+```yaml
+services:
+  adot-collector:
+    image: public.ecr.aws/aws-observability/aws-otel-collector:latest
+    command: ["--config", "/opt/config.yaml"]
+    ports:
+      - "4317:4317"
+      - "4318:4318"
+    volumes:
+      - ./otel-collector-config.yaml:/opt/config.yaml:ro
+    env_file:
+      - .adot.env    # AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN
+    environment:
+      - AWS_REGION=${AWS_REGION:-us-west-2}
+    restart: unless-stopped
+```
+
+Create `~/.claude/.adot.env` with your AWS credentials:
+
+```bash
+AWS_ACCESS_KEY_ID=AKIA...
+AWS_SECRET_ACCESS_KEY=...
+AWS_SESSION_TOKEN=...    # if using temporary credentials
+```
+
+### Start / Stop
+
+```bash
+cd ~/.claude
+docker compose -f docker-compose-otel.yaml up -d
+docker compose -f docker-compose-otel.yaml logs --tail 20
+# Look for: "Everything is ready. Begin running and processing data."
+```
+
+When using the ADOT path, configure Claude Code with gRPC instead of HTTP:
+
+```bash
+export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
+export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
+```
+
+To stop:
+
+```bash
+docker compose -f ~/.claude/docker-compose-otel.yaml down
+```
+
+### ADOT-Specific Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `HTTP 500` from OSIS | Protobuf encoding (default) | Add `encoding: json` and `compression: none` to all `otlphttp` exporters |
+| `HTTP 401` / "Missing Authentication Token" | SigV4 credentials expired | Refresh `.adot.env` with fresh credentials |
+| `EOF` or connection drops | OSIS pipeline cold-start | Stop and start the OSIS pipeline |
+| `connection refused` | ADOT not listening on 4317 | Check `docker ps`; ensure ports aren't taken |
+
+</details>
+
+## Disabling Telemetry
+
+Unset `CLAUDE_CODE_ENABLE_TELEMETRY` or set it to `0`. No other changes needed.