Text of github.github.com › gh-aw › reference › open-telemetry as Styx crawled it on Nov 18, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

OpenTelemetry | GitHub Agentic Workflows

Skip to main content OpenTelemetry OpenTelemetry is the observability layer for GitHub Agentic Workflows. It lets workflows export traces and spans to an external backend, and it gives workflows a way to read that telemetry back when they need to inspect behavior across runs. This guide covers the two ways gh-aw uses OpenTelemetry: Write-side OTLP sends new workflow spans to a backend such as Sentry. Read-side MCP lets a workflow query traces and spans that already exist in that backend.

Keep reusable telemetry setup in shared workflow files when multiple workflows use the same configuration. Write telemetry through OTLP Section titled “Write telemetry through OTLP” Configure observability.otlp in workflow frontmatter when the workflow should emit new spans. A typical Sentry setup looks like this: .github/workflows/daily-report.md --- network : allowed : - " *.sentry.io " observability : otlp : endpoint : - url : ${{ secrets.GH_AW_OTEL_SENTRY_ENDPOINT }} headers : Authorization : ${{ secrets.GH_AW_OTEL_SENTRY_AUTHORIZATION }} --- Once configured, gh-aw exports built-in workflow spans such as setup and conclusion events to the configured OTLP backend.

Use the bare secret expression for authorization headers, as shown above, rather than adding an authentication scheme prefix. For Sentry endpoints, gh-aw automatically rewrites Authorization to x-sentry-auth , so no prefix is needed. OTLP header credentials of at least four characters are masked before setup exports spans, including encoded Basic-auth credentials, decoded passwords, and JSON-escaped values. Artifact and step-summary redaction also derives these values from the configured headers rather than relying on setup logs or recognizable token prefixes.

OTLP endpoint and header environment variables, including multi-endpoint aggregated headers, are excluded from the eval agent sandbox. If a credential was exposed in an earlier run, revoke or rotate it and remove the affected logs and artifacts. Updated redaction does not sanitize retained output from previous runs. HTTP 401 and 403 export failures are not retried with unchanged credentials. Check the affected collector’s configured authorization header and telemetry-write permissions.

Transient delivery failures retain bounded retries; a rejected endpoint does not block other configured endpoints or the local telemetry mirror, and export failure does not fail the functional workflow. Protobuf encoding and Azure Monitor Section titled “Protobuf encoding and Azure Monitor” The gh-aw JavaScript exporter defaults to OTLP/HTTP JSON ( http/json ) for traces, opt-in compact session logs , and metrics , which are enabled by default when OTLP is configured.

Set the standard protocol environment variable to use binary OTLP/HTTP protobuf instead: env : OTEL_EXPORTER_OTLP_PROTOCOL : http/protobuf observability : otlp : endpoint : ${{ secrets.AZURE_MONITOR_OTLP_ENDPOINT }} headers : Authorization : ${{ secrets.AZURE_MONITOR_OTLP_AUTHORIZATION }} OTEL_EXPORTER_OTLP_TRACES_PROTOCOL , OTEL_EXPORTER_OTLP_LOGS_PROTOCOL , and OTEL_EXPORTER_OTLP_METRICS_PROTOCOL , when non-empty, take precedence over OTEL_EXPORTER_OTLP_PROTOCOL for their respective signals.

A signal-specific override affects only that signal. Set these overrides in workflow env when the signals need different encodings. All accept http/json or http/protobuf ; gRPC is not supported by this helper. The selected encoding applies to all configured endpoints for that signal. Unsupported protocols and encoding errors produce an exporter diagnostic without retrying or silently falling back to JSON. To manage the protocol as a repository, organization, or enterprise Actions variable, use gh aw env get and gh aw env update .

The defaults file field default_otlp_protocol maps to the standard OTEL_EXPORTER_OTLP_PROTOCOL variable: Terminal window gh aw env get defaults.yml Set this field in the downloaded file, retaining any other defaults: default_otlp_protocol : http/protobuf Terminal window gh aw env update defaults.yml --scope repo As with other managed fields, setting it to null or omitting it deletes the variable at the selected scope.

The compiler injects ${{ vars.OTEL_EXPORTER_OTLP_PROTOCOL }} into workflow env unless that key is explicitly defined by the workflow. Recompile existing workflows once to add that lookup; subsequent variable updates take effect without recompilation. For Azure Monitor native OTLP ingestion , use the traces endpoint from Application Insights OTLP Connection Info , or construct the Data Collection Endpoint / Data Collection Rule path: https://<logs-dce-domain>/datacollectionRules/<dcr-immutable-id>/streams/Microsoft-OTLP-Traces/otlp/v1/traces The exporter retains a complete /v1/traces path, including query parameters.

For base endpoints, it appends /v1/traces . Set AZURE_MONITOR_OTLP_AUTHORIZATION to the complete Bearer <access-token> header value for a Microsoft Entra identity authorized to write to the DCR (typically Monitoring Metrics Publisher ). Provision and refresh that token outside this helper; protobuf encoding does not provide Azure authentication or make an Application Insights connection string an OTLP endpoint. When compact session logs are enabled, the exporter selects the independent Microsoft-OTLP-Logs stream for the same DCE and DCR, preserving query parameters: https://<logs-dce-domain>/datacollectionRules/<dcr-immutable-id>/streams/Microsoft-OTLP-Logs/otlp/v1/logs The DCR must accept the logs stream as well as the traces stream.

A complete logs endpoint is retained; generic collector endpoints use /v1/logs without Azure stream rewriting. Protobuf requests use Content-Type: application/x-protobuf with binary-safe direct and proxy transports. Traces encode ExportTraceServiceRequest ; logs encode ExportLogsServiceRequest , including structured bodies and trace/span correlation; metrics encode ExportMetricsServiceRequest (gauge, monotonic sum, and explicit-bucket histogram data points, with exemplars).

The encoder uses only Node.js built-ins, and the sanitized local otel.jsonl trace mirror and otel-metrics.jsonl metrics mirror remain raw OTLP JSON regardless of wire encoding. These settings configure gh-aw JavaScript telemetry; external engines and the MCP gateway retain their own exporter capabilities. Successful HTTP responses are inspected for OTLP partialSuccess in JSON or protobuf, for traces, logs, and metrics.

JSON responses ignore unknown fields and treat null members as unset, following OTLP/ProtoJSON compatibility rules. Rejected spans, log records, or metric data points produce a warning with the signal-specific rejection count and increment gh-aw.otlp.export_errors ; sanitized details appear in gh-aw.otlp.export_error_details . Warning-only partial success (zero rejected records with a collector message) warns without incrementing the error count.

Collector messages are withheld because they may contain private data or credentials. Response diagnostics are limited to 64 KiB. Malformed, unsupported, oversized, or unreadable successful responses record an exporter error with acceptance marked unknown. The proxy-aware curl transport has a 10-second request timeout within a 15-second subprocess deadline; a body timeout after known HTTP success reports unknown acceptance without retrying.

Empty responses and valid full-success responses remain successful. None of these successful HTTP responses are retried: resending records the collector already accepted could create duplicates. Export diagnostics remain nonfatal and do not prevent delivery to other configured endpoints. Organization-wide defaults Section titled “Organization-wide defaults” When a workflow does not configure observability.otlp (in its own frontmatter or through an import), the compiler falls back to a default OTLP configuration read from the GitHub Actions environment: Name Kind Purpose GH_AW_DEFAULT_OTLP_ENDPOINT Secret or variable OTLP endpoint URL used when no endpoin

The rest of this page is on the live site.