feat(telemetry): configure provider OpenTelemetry by alexsoyes · Pull Request #1144 · ai-driven-dev/framework

alexsoyes · 2026-11-04T02:03:26Z

What and why

Capture and forward OpenTelemetry for Claude Code, Codex and OpenCode v2 without reading native session files or the framework usage ledger. An opt-in OpenCode server plugin transforms its public session events into OTLP logs. aidd telemetry otel run starts one provider session with a private collector and requires --yes to opt in for that execution. It does not infer a project or feature association. Cost calculation is out of scope.

The framework's existing local usage report remains a separate feature. Provider exporter initialization is also separate: user-level export can capture activity from other projects and is not required for the isolated run.

Consent, identity and data

The isolated run sends allowlisted observations to loopback Gouvernail using the selected connector token. New local Gouvernail tokens for each tool can be explicitly assigned to a team, member and installation. This identifies the declared assignee, not the physical person using the token; rotating one replaces the previous token for that tool and organization. Existing shared tokens retain declarative attribution.
--keep-capture retains a private raw OTLP file and prints its location. Raw captures can contain prompts, responses, commands, tool output and secrets. Without it the temporary capture is removed. Collector credentials and temporary settings are not retained.
Claude and Codex provide usage fields when emitted. The OpenCode plugin sends session and event IDs, selected model and variant, optional OpenCode project and parent IDs, and positive OpenCode-normalized token counts. It omits prompts, responses, tool content and cost. OpenCode normalizes missing counts to zero, so zero remains unavailable. The selected model and variant do not prove the served model or effective effort.
Production export remains disabled pending an authenticated user identity and destination. The installation UUID is not an authentication credential. Delivery completeness and exactly-once delivery are not guaranteed.
--follow-up sends a second prompt in the same session. Claude and Codex retain their CLI conversation history locally. --include-installation-id opts in to sending the existing installation UUID and is required for new assigned tokens. The UUID identifies an installation and is not a person or authentication credential. --include-repository separately opts in to Claude’s declared repository URL.

The isolated Codex runner forwards only allowlisted session_task.turn attributes, after session logs; trace events, paths and content are excluded. The span model is selected, and counters are deltas that may cover multiple requests or models. Duplicate turn IDs and partially overlapping periods are treated conservatively by Gouvernail.

Local verification

After one POC reset, Claude Code, Codex and OpenCode v2 each handled two messages in the same session and recovered the first message’s marker. OTLP observations reached Gouvernail with the same opt-in installation UUID and the configured local member attribution. Claude also supplied its declared repository URL. Codex turn traces provide the session and turn IDs with token observations; extra SSE observations remain separate and are not added to trace totals. Cache zeros remain ambiguous and are not inferred. No native session file was imported; reproduction procedure and provider field inventory.

Local CLI build, typecheck, focused checks and provider executions passed. Final CI remains to be checked.

Certification

I DO CERTIFY I READ EACH LINE OF THE PULL REQUEST BECAUSE I AM A SOFTWARE ENGINEER, NOT A AI PUPPY.

Provider coverage research

The provider observability guide records the fields documented or observed in OTLP, current forwarding gaps and source links. Claude request events contain useful technical fields that are not forwarded yet. Codex turn histograms could not be correlated safely; filtered turn traces carry the session and turn IDs together with their counters. OpenCode v2 standard OTLP did not expose session-linked model or usage in the earlier captures. The opt-in plugin now exports source events as OTLP; missing events and the provider’s ambiguous zeros remain unavailable.

alexsoyes

revue alex

alexsoyes

revue Alex

alexsoyes · 2026-11-04T23:25:26Z

@@ -0,0 +1,16 @@
+{
+  "defaults": {


check dans la doc officielle que ce ne soit pas du toml

Yes. Codex reads TOML: the CLI merges these defaults into $CODEX_HOME/config.toml (or ~/.codex/config.toml). codex.json is an internal framework template, not a Codex configuration file. The official OpenAI documentation shows the [otel] TOML configuration: https://learn.chatgpt.com/docs/config-file/config-advanced#observability-and-telemetry (checked 2026-11-05). Existing settings are preserved or the merge refuses a conflict.

alexsoyes · 2026-11-04T23:27:59Z

+import { afterEach, expect, it, vi } from "vitest";
+import { ensureInstallationId } from "../../../src/runtime/filesystem/installation-identity.js";
+
+vi.mock("node:fs/promises", async (importOriginal) => {


t'es sur de l'intéret de ces tests mockés ?

The tests mock only the filesystem link operation to deterministically exercise three hard-to-reproduce cases: another initializer wins, the filesystem returns EIO, or the winning identity disappears. They check the identity returned and temporary-file cleanup. A separate integration test starts 12 real concurrent initializations against the filesystem without mocking; both suites pass (20 tests). I would keep the injected failure cases because real concurrency alone does not reliably exercise them.

alexsoyes · 2026-11-04T23:30:24Z

+
+## Output
+
+The identity set, shown or removed, as the command reported it.


Ok mais on veut un tableau qui donne l'IA de la personne et probablement le endpoint utilisé, quand il a été généré, où il est stocké... non ?

The identity guidance now specifies a table for the local report name, installation UUID and provider identity, including tool, endpoint, creation time and storage when verified. Fields the CLI does not report are explicitly unknown, not inferred. This documents the requested output; exposing additional metadata in the CLI is not implemented yet. f49ba8e7

alexsoyes · 2026-11-04T23:31:14Z

+
+## Input
+
+The project directory.


Faut dire à l'utilisateur dans un tableau en output ce qui a été stoppé (otel ? gouvernail en prod ou local ?) ...

Depuis quand dans un tableau propre, faut qu'il soit serein sur le fait que rien n'est plus collecté.

The stop guidance now reports each scope separately. telemetry off ends consent for this clone, but does not stop native exporters or the raw OTLP collector; previously consented data may still be sent, and the CLI does not report the exact stop time. We cannot yet promise that all collection has stopped. f49ba8e7

alexsoyes · 2026-11-04T23:31:41Z

+
+## Process
+
+1. Run `aidd telemetry forget` with no flag. It removes nothing and lists what it would.


ça c'est autorisé partout sauf en prod sur le gouvernail

The documentation now distinguishes local usage deletion from OTLP captures and data already received by Gouvernail. Production deletion is a future prohibition, not a rule enforced by the current local command; production integration is not implemented. f49ba8e7

alexsoyes · 2026-11-04T23:32:24Z

+2. Obtain both choices and explain that native telemetry goes to the selected collector and can include sensitive data.
+   - The development collector and its private token must already exist; initialization does not start it.
+   - Production is refused until its destination is configured.
+3. Run `aidd telemetry otel init --config=<provider> --endpoint=<destination>` after an explicit request enabling that export.


Le endpoint par défaut est une config dans le CLI, on a local (pour les devs), et https://gouvernail.eu à terme

The current development collector is fixed in the CLI at http://127.0.0.1:14318. The documentation names https://gouvernail.eu as the intended future destination, not an active endpoint. Production initialization remains refused; mandatory production identity is not implemented yet. f49ba8e7

alexsoyes · 2026-11-04T23:32:45Z

@@ -0,0 +1,24 @@
+# 07 - Verify provider receipt


ça fait pas beaucoup de sous action ? on devrait pas split ? Je peux me tromper challenge ça

I recommend keeping verification as a separate internal, read-only action: it checks receipt independently of configuration and does not create another user-facing skill. These are actions inside one skill, not seven skills the user must choose. If this separation feels too heavy we can consolidate it, but configuration success alone must not imply receipt. f49ba8e7

Make local comparisons reproducible and preserve explicitly enabled repository metadata.

Keep the command reference aligned with the two-turn runner.

Allow session observations to carry a declared installation without treating it as a user identity.

Preserve session-linked turn observations without forwarding trace content.

Describe installation binding and legacy attribution for each tool.

Keep the field inventory aligned with the local OTLP forwarding and token attribution behavior.

Preserve the evidence needed to improve request-level attribution without guessing.

Allow request-level correlation and usage reconciliation without forwarding message contents.

Set accurate expectations for reproducing local observations.

# Conflicts: # cli/package.json # cli/scripts/check-bundle-size.mjs

feat(telemetry): configure native OTLP exports

c80215f

github-advanced-security Bot found potential problems Nov 4, 2026

View reviewed changes

Comment thread cli/src/contexts/telemetry/infrastructure/otel/init-otel.ts Fixed

Comment thread cli/tests/contexts/telemetry/otel/init-otel.integration.test.ts Fixed

Comment thread cli/tests/contexts/telemetry/otel/init-otel.integration.test.ts Fixed

alexsoyes commented Nov 4, 2026

View reviewed changes

feat(telemetry): verify native export capture and split setup actions

3be60d3

github-advanced-security Bot found potential problems Nov 4, 2026

View reviewed changes

Comment thread cli/tests/contexts/telemetry/otel/init-otel.integration.test.ts Fixed

alexsoyes added 3 commits November 4, 2026 11:27

feat(cli): create a stable installation identifier

5d87bcc

feat(cli): normalize native telemetry observations

315c93f

test(cli): isolate installation identity fixtures

7f51b7e

alexsoyes changed the title ~~feat(telemetry): configure native OTLP exports~~ feat(telemetry): configure and normalize agent telemetry Nov 4, 2026

github-advanced-security Bot found potential problems Nov 4, 2026

View reviewed changes

Comment thread cli/tests/e2e/installation-identity.e2e.test.ts Fixed

Comment thread cli/tests/e2e/installation-identity.e2e.test.ts Fixed

feat(telemetry): sync local sessions to Gouvernail

526e30d

github-advanced-security Bot found potential problems Nov 4, 2026

View reviewed changes

test(telemetry): isolate collector fixtures

82eae33

github-advanced-security Bot found potential problems Nov 4, 2026

View reviewed changes

Comment thread cli/tests/contexts/telemetry/otel/init-otel.integration.test.ts Fixed

alexsoyes added 3 commits November 4, 2026 17:26

test(telemetry): compare initialization contents directly

b8b7e50

test(telemetry): cover platform and command behavior

ed6f7e6

docs(telemetry): explain local collector startup

ffbe27e

alexsoyes commented Nov 4, 2026

View reviewed changes

alexsoyes added 4 commits November 5, 2026 07:51

docs(telemetry): explain consent, data and identity

f49ba8e

fix(telemetry): protect sync accuracy and add session titles

c343f82

fix(telemetry): reject ambiguous OTLP data

bad1f0a

feat(telemetry): sync verified native session projects

0a702ed

github-advanced-security Bot found potential problems Nov 5, 2026

View reviewed changes

Comment thread cli/tests/contexts/telemetry/otel/session-title-sync.integration.test.ts Fixed

Comment thread cli/tests/contexts/telemetry/otel/session-title-sync.integration.test.ts Fixed

alexsoyes added 3 commits November 5, 2026 12:32

test(telemetry): verify session metadata end to end

f7b3e10

test(telemetry): register native Codex smoke test

28b9b62

test(telemetry): align sync coverage with platform support

5bd7950

github-advanced-security Bot found potential problems Nov 5, 2026

View reviewed changes

Comment thread cli/tests/e2e/telemetry-otel-collector.e2e.test.ts Fixed

alexsoyes added 3 commits November 5, 2026 12:42

fix(ci): isolate mutation shard reports

70a4d2f

test(telemetry): verify session consent intervals

0a15aeb

fix(telemetry): clarify identity and consent status

1d96237

alexsoyes added 2 commits November 6, 2026 09:58

refactor(telemetry): remove non-OTel session metadata

af42e1c

refactor(telemetry): remove unused session comparator

c9866cd

alexsoyes changed the title ~~feat(telemetry): configure and normalize agent telemetry~~ feat(telemetry): configure provider OpenTelemetry Nov 6, 2026

alexsoyes added 27 commits November 6, 2026 10:21

feat(telemetry): run isolated provider OTLP sessions

1517d40

docs(telemetry): explain OpenCode OTLP coverage

2057191

docs(telemetry): clarify OpenCode trace correlation

4907069

docs(telemetry): map provider OTLP coverage

643bef3

feat(telemetry): export OpenCode session events as OTLP

ec0b2f5

fix(telemetry): reject special plugin files without blocking

775594d

fix(telemetry): reject conflicting OpenCode plugin entries

5645331

fix(telemetry): guard all OpenCode plugin entry variants

83b7ccf

docs(telemetry): clarify OpenCode token attribution

ea5c727

feat(telemetry): observe two turns in one session

fbeddb9

Make local comparisons reproducible and preserve explicitly enabled repository metadata.

test(telemetry): refresh command help snapshot

99da51f

Keep the command reference aligned with the two-turn runner.

feat(telemetry): opt in to installation attribution

0c38c27

Allow session observations to carry a declared installation without treating it as a user identity.

docs(telemetry): include installation in local examples

f189cba

feat(telemetry): forward Codex turn traces

f6f749d

Preserve session-linked turn observations without forwarding trace content.

docs(telemetry): explain assigned local tokens

691e013

Describe installation binding and legacy attribution for each tool.

docs(telemetry): clarify forwarded usage and identity

b354b17

Keep the field inventory aligned with the local OTLP forwarding and token attribution behavior.

docs(telemetry): record Claude metric interval gap

e75b9cc

Preserve the evidence needed to improve request-level attribution without guessing.

feat(telemetry): forward Claude request evidence

ea429ac

Allow request-level correlation and usage reconciliation without forwarding message contents.

docs(telemetry): document administrator token setup

3455147

docs(telemetry): clarify temporary capture retention

022c3b0

Set accurate expectations for reproducing local observations.

docs(telemetry): clarify OpenCode Claude hook limits

cc02e5e

docs(telemetry): remove unconfirmed provider assumption

415c7f3

docs(telemetry): explain proxy cache ambiguity

96c6ffa

docs(telemetry): qualify proxy input counts

a9c7bde

docs(telemetry): record repository attribute coverage

9bbda0a

docs(telemetry): qualify Codex cache counters

8b2eb05

Merge remote-tracking branch 'origin/next' into HEAD

253d204

# Conflicts: # cli/package.json # cli/scripts/check-bundle-size.mjs


		## Output

		The identity set, shown or removed, as the command reported it.


		## Process

		1. Run `aidd telemetry forget` with no flag. It removes nothing and lists what it would.

Conversation

alexsoyes commented Nov 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What and why

Consent, identity and data

Local verification

Certification

Provider coverage research

Uh oh!

Uh oh!

Uh oh!

Uh oh!

alexsoyes left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

alexsoyes left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

alexsoyes commented Nov 4, 2026 •

edited

Loading