{"id":"ops/otel-local","relativePath":"ops/otel-local.md","title":"Local OpenTelemetry Wiring (Tempo / Jaeger)","markdown":"# Local OpenTelemetry Wiring (Tempo / Jaeger)\n\nThis runbook standardizes local OTLP wiring for:\n\n- Next.js runtime (`instrumentation.ts`, `@vercel/otel`)\n- Python validation service\n- Python reconciliation service\n- Dagster pipeline runner\n\nAll services honor `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` (or `OTEL_EXPORTER_OTLP_ENDPOINT`).\n\n## Env templates\n\nUse one of the root templates:\n\n- `.env.otlp.tempo.example`\n- `.env.otlp.jaeger.example`\n\nCopy the selected template values into `.env.local` and export the same values\nin any shell that starts Python services/pipeline processes.\n\n## Quick wiring (PowerShell)\n\nTempo (or OTLP collector in front of Tempo):\n\n```powershell\nGet-Content .env.otlp.tempo.example | Where-Object { $_ -and -not $_.StartsWith(\"#\") }\n```\n\nJaeger all-in-one (OTLP HTTP receiver enabled):\n\n```powershell\nGet-Content .env.otlp.jaeger.example | Where-Object { $_ -and -not $_.StartsWith(\"#\") }\n```\n\nIf you want the current shell to use template variables directly:\n\n```powershell\nGet-Content .env.otlp.tempo.example `\n  | Where-Object { $_ -and -not $_.StartsWith(\"#\") } `\n  | ForEach-Object {\n      $pair = $_ -split \"=\", 2\n      [Environment]::SetEnvironmentVariable($pair[0], $pair[1], \"Process\")\n    }\n```\n\nThen start services as usual (`pnpm dev`, `pnpm validate:service`, `pnpm reconcile:service`, `python pipeline/run_materialize.py`).\n\n## Local endpoints\n\n- OTLP HTTP: `http://127.0.0.1:4318/v1/traces`\n- Jaeger UI (typical all-in-one): `http://127.0.0.1:16686`\n- Grafana UI (if running local LGTM/Tempo stack): implementation-specific (commonly `http://127.0.0.1:3000`)\n\n## Explicit GraphDB / Solr span attributes\n\nShared DB span helper:\n\n- `src/utils/otel-db-spans.ts`\n\nCurrent finalized call sites:\n\n- GraphDB SPARQL runtime calls are wrapped in:\n  - `src/services/ai-query.ts` (`graphdb.sparql.query`)\n- Solr select client calls are wrapped in:\n  - `src/services/solr-client.ts` (`solr.select.query`)\n\nEmitted attributes include:\n\n- `db.system.name` (`graphdb` or `solr`)\n- `db.operation.name`\n- `db.namespace`\n- `server.address`\n- `server.port`\n- `url.full`\n- `metamuseum.db.backend`\n\nThis keeps distributed traces queryable by backend and operation when C4/C5 search/graph traffic scales up.\n\n## Credibility engine span/metric conventions\n\nShared conventions are centralized in:\n\n- `src/utils/otel-credibility.ts`\n\nSpan names:\n\n- `metamuseum.trust.citation_coverage.evaluate`\n- `metamuseum.trust.wiki_publish.preflight`\n- `metamuseum.trust.wiki_publish.execute`\n- `metamuseum.originality.score.evaluate`\n- `metamuseum.distribution.publish_queue.enqueue`\n- `metamuseum.distribution.publish_queue.process`\n- `metamuseum.distribution.publish_queue.dispatch`\n\nMetric names:\n\n- `metamuseum.credibility.events.total`\n- `metamuseum.credibility.event.duration.ms`\n- `metamuseum.credibility.failures.total`\n\nRequired shared attributes:\n\n- `metamuseum.credibility.layer` (`trust|originality|distribution`)\n- `metamuseum.credibility.event`\n- `metamuseum.credibility.kind` (`gate|publish|queue|delivery|evaluation`)\n- `metamuseum.credibility.outcome`\n\nCurrent call sites instrumented for these conventions:\n\n- trust gate events: `src/utils/citation-coverage.ts`\n- originality gate events: `src/utils/originality-score.ts`\n- wiki preflight/publish events: `src/services/wiki-publish.ts`\n- distribution queue events: `src/services/publish-queue-worker.ts`\n","sections":[{"level":2,"heading":"Env templates","anchor":"env-templates"},{"level":2,"heading":"Quick wiring (PowerShell)","anchor":"quick-wiring-powershell"},{"level":2,"heading":"Local endpoints","anchor":"local-endpoints"},{"level":2,"heading":"Explicit GraphDB / Solr span attributes","anchor":"explicit-graphdb-solr-span-attributes"},{"level":2,"heading":"Credibility engine span/metric conventions","anchor":"credibility-engine-span-metric-conventions"}],"html":"<h1 id=\"local-opentelemetry-wiring-tempo-jaeger\">Local OpenTelemetry Wiring (Tempo / Jaeger)</h1>\n<p>This runbook standardizes local OTLP wiring for:</p>\n<ul><li>Next.js runtime (`instrumentation.ts`, `@vercel/otel`)</li><li>Python validation service</li><li>Python reconciliation service</li><li>Dagster pipeline runner</li></ul>\n<p>All services honor `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` (or `OTEL_EXPORTER_OTLP_ENDPOINT`).</p>\n<h2 id=\"env-templates\">Env templates</h2>\n<p>Use one of the root templates:</p>\n<ul><li>`.env.otlp.tempo.example`</li><li>`.env.otlp.jaeger.example`</li></ul>\n<p>Copy the selected template values into `.env.local` and export the same values</p>\n<p>in any shell that starts Python services/pipeline processes.</p>\n<h2 id=\"quick-wiring-powershell\">Quick wiring (PowerShell)</h2>\n<p>Tempo (or OTLP collector in front of Tempo):</p>\n<pre><code>\nGet-Content .env.otlp.tempo.example | Where-Object { $_ -and -not $_.StartsWith(&quot;#&quot;) }\n</code></pre>\n<p>Jaeger all-in-one (OTLP HTTP receiver enabled):</p>\n<pre><code>\nGet-Content .env.otlp.jaeger.example | Where-Object { $_ -and -not $_.StartsWith(&quot;#&quot;) }\n</code></pre>\n<p>If you want the current shell to use template variables directly:</p>\n<pre><code>\nGet-Content .env.otlp.tempo.example `\n  | Where-Object { $_ -and -not $_.StartsWith(&quot;#&quot;) } `\n  | ForEach-Object {\n      $pair = $_ -split &quot;=&quot;, 2\n      [Environment]::SetEnvironmentVariable($pair[0], $pair[1], &quot;Process&quot;)\n    }\n</code></pre>\n<p>Then start services as usual (`pnpm dev`, `pnpm validate:service`, `pnpm reconcile:service`, `python pipeline/run_materialize.py`).</p>\n<h2 id=\"local-endpoints\">Local endpoints</h2>\n<ul><li>OTLP HTTP: `http://127.0.0.1:4318/v1/traces`</li><li>Jaeger UI (typical all-in-one): `http://127.0.0.1:16686`</li><li>Grafana UI (if running local LGTM/Tempo stack): implementation-specific (commonly `http://127.0.0.1:3000`)</li></ul>\n<h2 id=\"explicit-graphdb-solr-span-attributes\">Explicit GraphDB / Solr span attributes</h2>\n<p>Shared DB span helper:</p>\n<ul><li>`src/utils/otel-db-spans.ts`</li></ul>\n<p>Current finalized call sites:</p>\n<ul><li>GraphDB SPARQL runtime calls are wrapped in:</li><li>`src/services/ai-query.ts` (`graphdb.sparql.query`)</li><li>Solr select client calls are wrapped in:</li><li>`src/services/solr-client.ts` (`solr.select.query`)</li></ul>\n<p>Emitted attributes include:</p>\n<ul><li>`db.system.name` (`graphdb` or `solr`)</li><li>`db.operation.name`</li><li>`db.namespace`</li><li>`server.address`</li><li>`server.port`</li><li>`url.full`</li><li>`metamuseum.db.backend`</li></ul>\n<p>This keeps distributed traces queryable by backend and operation when C4/C5 search/graph traffic scales up.</p>\n<h2 id=\"credibility-engine-span-metric-conventions\">Credibility engine span/metric conventions</h2>\n<p>Shared conventions are centralized in:</p>\n<ul><li>`src/utils/otel-credibility.ts`</li></ul>\n<p>Span names:</p>\n<ul><li>`metamuseum.trust.citation_coverage.evaluate`</li><li>`metamuseum.trust.wiki_publish.preflight`</li><li>`metamuseum.trust.wiki_publish.execute`</li><li>`metamuseum.originality.score.evaluate`</li><li>`metamuseum.distribution.publish_queue.enqueue`</li><li>`metamuseum.distribution.publish_queue.process`</li><li>`metamuseum.distribution.publish_queue.dispatch`</li></ul>\n<p>Metric names:</p>\n<ul><li>`metamuseum.credibility.events.total`</li><li>`metamuseum.credibility.event.duration.ms`</li><li>`metamuseum.credibility.failures.total`</li></ul>\n<p>Required shared attributes:</p>\n<ul><li>`metamuseum.credibility.layer` (`trust|originality|distribution`)</li><li>`metamuseum.credibility.event`</li><li>`metamuseum.credibility.kind` (`gate|publish|queue|delivery|evaluation`)</li><li>`metamuseum.credibility.outcome`</li></ul>\n<p>Current call sites instrumented for these conventions:</p>\n<ul><li>trust gate events: `src/utils/citation-coverage.ts`</li><li>originality gate events: `src/utils/originality-score.ts`</li><li>wiki preflight/publish events: `src/services/wiki-publish.ts`</li><li>distribution queue events: `src/services/publish-queue-worker.ts`</li></ul>","updatedAt":"2018-10-20T01:46:40.000Z","checksum":"1ebbc3b33f92b738252f307eb76f8640dc4d609335116aebb17f72127e9889a0","checksumPrefix":"1ebbc3b33f92","anchorCount":5,"lineCount":115,"rawUrl":"/api/docs/content?path=ops%2Fotel-local.md","htmlUrl":"/docs?doc=ops%2Fotel-local.md","apiUrl":"/api/docs/content?path=ops%2Fotel-local.md"}