From 1842ae6cb7b762d0234c34d208bdd686cd5d4db4 Mon Sep 17 00:00:00 2001 From: Sawyer Cutler Date: Sun, 13 Sep 2026 15:43:46 -0700 Subject: [PATCH] Correct PerfTrace export prerequisites and settings secrets guidance Drop the fixed count of PostHog product events, remove the auth header from the settings example, and state that an endpoint alone enables export. --- docs/PERFTRACE.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/docs/PERFTRACE.md b/docs/PERFTRACE.md index 5237868de..984ace052 100644 --- a/docs/PERFTRACE.md +++ b/docs/PERFTRACE.md @@ -46,7 +46,6 @@ error code `OTEL_CONFIG_INVALID` and does not half-enable export. "otel": { "enabled": true, "endpoint": "https://collector.example/v1", - "headers": { "Authorization": "Bearer …" }, "serviceName": "corbits-code", "resourceAttributes": { "deployment.environment": "dev" @@ -55,6 +54,9 @@ error code `OTEL_CONFIG_INVALID` and does not half-enable export. } ``` +Do not put auth headers in settings; pass them via `OTEL_EXPORTER_OTLP_HEADERS` +so secrets stay out of the settings file. + Precedence: - **endpoint:** env overrides settings @@ -65,6 +67,9 @@ Precedence: `resourceAttributes["service.name"]` is always set to the resolved name so the two never diverge. - **resourceAttributes:** settings merged with env; env wins on key conflict +- **enabling export:** setting an endpoint (settings or env) enables export; + `otel.enabled` need not be set. Service name or resource attributes alone do + not enable export. - **`otel.enabled: false`:** disables export when only settings provide an endpoint; an explicit env endpoint still enables export @@ -132,7 +137,7 @@ export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer%20" export OTEL_SERVICE_NAME="corbits-code" ``` -This does **not** expand the three PostHog product events in `docs/TELEMETRY.md`. +This does **not** expand the PostHog product events in `docs/TELEMETRY.md`. Product analytics opt-out (`CORBITS_TELEMETRY`, `DO_NOT_TRACK`, settings) does not control OTEL export, and vice versa. @@ -166,7 +171,7 @@ Then supply auth only via env when needed. | Pipe | Purpose | Default | Content | | ----------------------------- | ------------------------------ | --------- | --------------------------- | -| PostHog (`docs/TELEMETRY.md`) | Aggregate product usage | Opt-out | Three allowlisted events | +| PostHog (`docs/TELEMETRY.md`) | Aggregate product usage | Opt-out | Allowlisted product events | | Local PerfTrace | Operator/dev attribution | Always on | Privacy-strict phase spans | | OTEL export | Your APM / Phoenix / collector | Opt-in | Full span tree when enabled |