Content observability

Content observability lets you monitor applications and reports that you deploy to Posit Connect by using distributed traces. Connect retains content traces and exposes them through the application programming interface (API).

Prerequisites

Content observability requires your Connect administrator to enable OpenTelemetry.Enabled. OpenTelemetry.AllowContentInstrumentation is true by default. Administrators can set OpenTelemetry.AllowContentInstrumentation to false to block content instrumentation. For content that supports runtime settings, the dashboard displays the Traces setting when both settings are true and you have access to the content settings. If you do not see the Traces setting, ask your administrator to review the content telemetry configuration.

Enabling observability for your content

If the dashboard displays the Traces setting, you can enable observability in the content settings:

  1. Open the content in the Connect dashboard.
  2. Select Settings > Monitoring.
  3. Under Traces, select Enabled.

You can also use the Update Content API to set otel_enabled to true:

Terminal
curl -X PATCH "https://connect.example.com/__api__/v1/content/{guid}" \
  -H "Authorization: Key ${CONNECT_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"otel_enabled": true}'

Connect applies this setting when it starts a content process. Use the Get content traces API to retrieve retained traces.

Note

For R content, enabling observability triggers a rebuild of your content bundle to include the instrumentation package. This happens automatically.

Collected signals

The public content observability feature supports traces. Traces capture the execution flow of requests through your application and show how long each operation takes, which is valuable for identifying bottlenecks.

How your information is shared

Content observability captures data from inside your running application and sends it out of that process. Before enabling it, understand what leaves and who can read it.

OpenTelemetry instrumentation packages produce traces. The instrumentation package and its configuration determine which operations and attributes appear in each span. For example, spans can include HTTP routes and status codes, SQL statements, outbound request URLs, and operation durations. These spans can include query text, request URLs and query strings, and HTTP headers. Any of these can embed identifiers, parameters, or values derived from your data or your viewers.

Warning

Trace instrumentation can include request details, query text, outbound request URLs, and operation durations. These values can embed identifiers, parameters, or values derived from your data or your viewers. Review the data emitted by your instrumentation before enabling observability on content that handles sensitive data.

Where it goes

By default, your content sends traces to the embedded OpenTelemetry Collector in Connect. Connect stores retained traces on the server and makes them available through the content traces API.

Access follows the permissions for the content. Administrators and users with Reviewer or higher access can read traces. Users with Viewer access cannot read traces.

Turning it off

Content observability is per content item and off unless you enable it. Setting it back to disabled prevents Connect from configuring new content processes to emit traces.

Auto-instrumentation

When observability is enabled, Connect configures compatible libraries in your application to emit traces automatically. You do not need to add instrumentation code.

The OpenTelemetry ecosystem provides instrumentation for a wide range of libraries. The following sections describe libraries that work with the instrumentation that Connect provides.

Python examples

The SQLAlchemy and psycopg2 packages emit traces for query execution. Packages such as requests and httpx emit traces for outbound HTTP calls. Web frameworks such as Flask, FastAPI, and Django also emit traces for each incoming request, including route information and response status.

The OpenTelemetry Python Contrib documentation describes the instrumentation packages for these libraries.

R examples

R packages that integrate with the otelsdk package emit traces when it is available. For example:

  • The shiny package (1.12.0+) traces web requests and reactive execution.
  • The plumber2 package (0.2.0+) traces API endpoint execution.
  • The httr2 package (1.2.2+) traces outbound HTTP requests.
  • The DBI package (1.3.0+) traces database queries.

See the compatible libraries page for a more complete list of R packages with tracing support.

Using a bundled Python SDK

Connect provides a shared OpenTelemetry SDK for Python auto-instrumentation. If your bundle declares opentelemetry-sdk in requirements.txt, Connect uses the version in the bundle and does not inject the shared SDK.

Customizing trace export

By default, Connect sets the general OpenTelemetry Protocol (OTLP) endpoint and other settings that route traces to the embedded collector. Connect applies content environment variables after its own values. They override a value with the same name unless Applications.ProhibitedEnvironment blocks the variable.

To send traces to another collector, set OTEL_EXPORTER_OTLP_TRACES_ENDPOINT in your content environment. Set it to the complete trace endpoint URL, including the /v1/traces path when your collector requires that path. The trace-specific endpoint takes precedence over the general endpoint that Connect sets. Connect does not retain traces that you send only to another collector.

You can also use SDK-specific settings that Connect does not set. For example, Python content can set OTEL_PYTHON_DISABLED_INSTRUMENTATIONS to a comma-separated list of instrumentations to disable.