Getting started with OpenTelemetry

This guide covers how to enable OpenTelemetry in Posit Connect, common configuration patterns, and how to use OpenTelemetry alongside Prometheus.

Minimal setup

Enable OpenTelemetry in your rstudio-connect.gcfg:

[OpenTelemetry]
Enabled = true

With this minimal configuration, Connect collects signals and persists them to disk. For details about its impact and retention, see Disk persistence.

Export to an observability backend

To send signals to your observability platform’s locally running agent, add an [OTLPEndpoint] section:

[OpenTelemetry]
Enabled = true

[OTLPEndpoint "mybackend"]
Endpoint = http://<host>:4318

The Endpoint setting is the base URL of an OpenTelemetry Protocol (OTLP) HTTP receiver. Port 4318 is the default OTLP HTTP port used by most collectors. Connect appends the signal-specific paths (/v1/traces, /v1/logs, /v1/metrics) automatically so do not include them in the URL.

By default, Connect sends all three signal types (logs, traces, and metrics) to each endpoint. You can configure each endpoint to receive only specific signal types:

[OTLPEndpoint "mybackend"]
Endpoint = http://<host>:4318
Logs = true
Traces = false
Metrics = false

You can configure multiple named endpoints to fan out signals to different observability platforms.

Most APM platforms require a locally running agent or collector to receive OTLP data. For example, Datadog requires the Datadog Agent running on the same host, which acts as the local collector and handles authentication to the Datadog backend. Ensure your platform’s collector agent is installed and running before configuring the endpoint.

Disk persistence

By default, Connect persists signals to disk as JSONL files. Diagnostic bundles include these files, which are useful for debugging. See the configuration reference for the full list of [OpenTelemetry] persistence settings: PersistenceEnabled, PersistenceDir, PersistenceMaxSizeMb, PersistenceNumBackups, and PersistenceMaxDays.

You can disable persistence, but we recommend keeping it on even if you export signals to an observability backend. This allows diagnostic bundles to include telemetry signals.

[OpenTelemetry]
Enabled = true
PersistenceEnabled = false

Disabling specific instrumentation

Connect enables both API and database instrumentation by default. You can selectively disable them:

[OpenTelemetry]
Enabled = true
APIInstrumentation = false       ; Disable API request tracing
DatabaseInstrumentation = false  ; Disable database metrics

Exporting logs via OpenTelemetry

You can export Connect’s server logs as structured OpenTelemetry logs. OpenTelemetry logs provide richer context through structured attributes (such as content GUIDs, user IDs, and request IDs) and automatic correlation with traces. Log scraping and OTel logs can also run side by side.

If your APM platform is already ingesting Connect’s structured logs from disk (for example, via a log-shipping agent), enabling OpenTelemetry log export sends the same data through a second path. You can disable disk-based log shipping in that case to avoid duplicate ingestion and extra costs.

To export logs via OpenTelemetry, configure an endpoint as follows. Logs defaults to true, but we set it in this example for clarity:

[OpenTelemetry]
Enabled = true

[OTLPEndpoint "mybackend"]
Endpoint = http://<host>:4318
Logs = true

Trace user enrichment

By default, trace spans carry content identifiers (such as content.guid) but not the identity of the user who owns that content. When TraceUserEnrichmentEnabled is set to true, Connect resolves user identity from span attributes before export, adding user.guid, user.username, and user.email to each span.

Connect resolves user identity using the following priority:

1. user.guid — If the span already carries a user.guid attribute, Connect looks up the corresponding username and email.
2. content.guid — If no user.guid is present but a content.guid attribute exists, Connect resolves the content owner and adds their user.guid, user.username, and user.email.

[OpenTelemetry]
Enabled = true
TraceUserEnrichmentEnabled = true

Note

Enrichment only applies to exported trace spans. Metrics and logs are not affected.

Prometheus and OpenTelemetry

Connect supports both Prometheus scraping and native OpenTelemetry export, and you can use both at the same time. We recommend native OpenTelemetry export for new setups because it provides richer context and automatic correlation across signals. If you already have a working Prometheus pipeline, Connect fully supports it.

Enabling OpenTelemetry with an existing Prometheus setup

If you already have Prometheus configured, you can enable OpenTelemetry without disrupting your existing Prometheus pipeline. When both are enabled and Metrics.PrometheusCollectorOTelEnabled = true, the Prometheus /metrics endpoint includes the new OpenTelemetry metrics along with the legacy Prometheus metrics.

[Metrics]
PrometheusListen = :3232
PrometheusCollectorOTelEnabled = true

[OpenTelemetry]
Enabled = true

Important

OpenTelemetry.Enabled must be true for OpenTelemetry metrics to appear on the Prometheus /metrics endpoint.

Migrating from legacy Prometheus HTTP metrics

When OpenTelemetry.Enabled = true and OpenTelemetry.APIInstrumentation = true, the legacy connect_http_* Prometheus HTTP metrics are automatically disabled and replaced by OpenTelemetry-standard http.server.* metrics. On the Prometheus /metrics endpoint, these appear with underscores and unit suffixes (for example, http.server.request.duration becomes http_server_request_duration_seconds).

The following table maps the legacy metrics to their OTel replacements as they appear on the Prometheus /metrics endpoint:

Legacy Prometheus metric	OTel replacement (Prometheus format)	Notes
connect_http_request_inflight_gauge	—	No OTel replacement. In-flight request tracking is not available with OTel HTTP instrumentation.
connect_http_request_count	—	Use rate(http_server_request_duration_seconds_count[5m]) for request throughput.
connect_http_request_duration_seconds	http_server_request_duration_seconds	Label changes: code → http_status_code, route → http_route, method → http_method
connect_http_request_size_bytes	http_server_request_body_size_bytes	Label changes as above
connect_http_response_size_bytes	http_server_response_body_size_bytes	Label changes as above

Note

Non-HTTP legacy Prometheus metrics (queue, applications, build, content, and platform runtime metrics) remain unaffected by this change.