Skip to content

Correct PerfTrace export prerequisites and settings secrets guidance #1013

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
TheGreatAxios merged 1 commit into from
Sep 14, 2026
Merged

Correct PerfTrace export prerequisites and settings secrets guidance #1013

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 8 additions & 3 deletions docs/PERFTRACE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand All @@ -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
Expand All @@ -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

Expand Down Expand Up @@ -132,7 +137,7 @@ export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer%20<phc_…>"
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.

Expand Down Expand Up @@ -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 |

Expand Down
Loading