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). The dashboard also displays traces when the content observability interface is available on your Connect server.

Prerequisites

Content observability requires your Connect administrator to enable OpenTelemetry.Enabled. Content instrumentation is permitted by default. Administrators can set OpenTelemetry.AllowContentInstrumentation to false to block content instrumentation. The dashboard controls require additional server configuration. If you do not see the controls, use the API or 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. You can also inspect traces in the dashboard when the trace interface is available.

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.

Third-party OpenTelemetry instrumentation packages produce the traces, not Connect, so the library determines exactly what appears in a span. For example, spans can include HTTP routes and status codes, SQL statements, outbound request URLs, and operation durations. In practice this commonly includes 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

Your content sends traces to the embedded OpenTelemetry Collector in Connect. Connect stores retained traces on the server and makes them available through the dashboard (when enabled) and 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

Database clients such as SQLAlchemy and psycopg2 emit traces for query execution, and libraries like requests and httpx trace outbound HTTP calls. Web frameworks like 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:

  • shiny (1.12.0+) traces web requests and reactive execution
  • plumber2 (0.2.0+) traces API endpoint execution
  • httr2 (1.2.2+) traces outbound HTTP requests
  • DBI (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

Connect sets the general OpenTelemetry Protocol (OTLP) endpoint and other settings that route traces to the embedded collector. Content environment variables cannot override Connect values that use the same variable name.

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 or display 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.