Skip to content
Back to the lab

When Codex collector credentials rotate: the observable states of an OTLP/HTTP exporter

Map Codex OTLP/HTTP credential rotation across successful refresh, blocked export, recovery, and excluded configurations.

Super Genius Labs Editorial · 4 min read

Codex 0.170.0 adds automatically refreshed authentication headers for OpenTelemetry HTTP exporters (release). An in-scope exporter can be operated through four observable conditions: the latest helper result is active, a scheduled refresh has failed and affected exports are blocked, a later refresh has restored export, or the configuration is excluded from the feature.

The OpenTelemetry exporter specification covers static headers and bounded retries for transient export errors. Codex defines the separate 29-minute refresh cycle, helper precedence, blocking behavior, recovery path, and exclusions described here (specification; implementation change).

Establish whether the exporter is in scope

The administrator-configured helper is shared across explicitly configured HTTP log, trace, and metric exporters. It refreshes every 29 minutes by default. Helper output overrides matching static headers, and a failed refresh blocks affected exports until recovery. The helper excludes gRPC, built-in analytics, and exporters established by admin requirements (implementation change).

Before testing, record:

  • Whether the exporter uses explicitly configured OTLP over HTTP.
  • Which signal types are configured.
  • Whether each authentication header comes from the helper, static configuration, or both.
  • Whether the route was established by admin requirements.

When both sources define the same header, the helper value wins. The matching static value does not provide a documented fallback during helper failure.

Follow the four operating conditions

ConditionTrigger or scopeEvidence to retain
Active helper resultThe latest scheduled refresh succeeded.Helper exit status and timestamp, header-source selection without the secret, export attempts, and collector receipt.
Refresh failed; export blockedA scheduled refresh failed.Failure time, affected signal types, blocked-export events, and the surrounding pipeline’s handling of telemetry during the interval.
RecoveredA later scheduled refresh succeeded and affected exports resumed.Recovery time, first subsequent export attempt, first collector receipt, and the gap from the last pre-failure receipt.
Excluded configurationThe route uses gRPC, built-in analytics, or an exporter established by admin requirements.Effective exporter configuration and confirmation that the helper does not govern the route.

These evidence fields are an operator checklist. Their availability depends on process logs, collector records, and the telemetry pipeline around Codex.

Run the failure drill

Start with an explicitly configured OTLP/HTTP exporter and a helper that returns a known test header. Record the helper invocation time and confirm collector receipt without retaining the credential value.

Make the helper return a non-success result before the next scheduled refresh. Exercise every configured HTTP signal. Record the refresh failure, the affected export events, and the treatment of telemetry generated while export is blocked. The merged change establishes blocking until recovery; buffering, loss, and replay depend on the surrounding deployment (implementation change).

Restore a successful helper result before a later scheduled refresh. Capture that refresh, the first subsequent export attempt, and the first collector receipt. The refresh timestamp marks credential recovery. Collector receipt shows when data again reached the collector.

Repeat the configuration check with one excluded route. Confirm through effective configuration that gRPC, built-in analytics, or an exporter established by admin requirements remains outside the helper path.

Verify header precedence safely

Configure the same test header name statically and through the helper. Give each source a distinct non-production value accepted by a test collector. Collector-side identification can show that the helper value arrived without placing either value in application logs.

Then test one header found only in static configuration and another found only in helper output. This distinguishes matching-key precedence from the deployment’s effective combined header set. The documented guarantee covers helper precedence for matching headers; retain the combined set as an observed test result (implementation change).

Test exporter retry independently

Credential refresh failure and transient collector failure exercise different paths. Run them as separate cases:

  • Break the helper while keeping the collector reachable. Capture the scheduled refresh failure and blocked exports.
  • Keep the helper healthy while making the collector return a transient export error. Capture the exporter’s bounded retry behavior.
  • Restore each dependency separately. Retain timestamps for refresh recovery, export attempts, and collector receipt.

Independent cases keep credential recovery, exporter retry, and collector availability distinct in the operating record.

Retain the boundary in the runbook

Record the effective transport, exporter origin, configured signal types, helper result times, blocked-export evidence, recovery time, and collector receipt. Together, those fields show which credential source governed the request and when the exporter moved from failure to recovery.

Carry the same transport, authority, and evidence boundaries into broader infrastructure reviews through Build.