# Managed OpenTelemetry

Send organization-scoped OTLP logs, metrics, and traces to Composal for agent analysis.

Composal Managed OpenTelemetry accepts logs, metrics, and traces at `https://otel.composal.ai`. Use a Composal personal access token and choose the organization that owns the telemetry. Composal agents can then use the retained signals for performance analysis, testing, and debugging workflows.

## Configure an exporter

Set the standard OTLP environment variables in your application or OpenTelemetry Collector. Replace the placeholders with a personal access token and an organization slug that token can access.

```sh
export OTEL_EXPORTER_OTLP_ENDPOINT=https://otel.composal.ai
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_HEADERS='authorization=Bearer <composal-token>,x-vex-organization=<organization-slug>'
```

The signal endpoints are `/v1/logs`, `/v1/metrics`, and `/v1/traces`. A successful export returns the standard empty OTLP success response after managed storage accepts the rows. Treat `401` as an invalid token, `404` as an organization the token cannot access, and `503` as retryable.

## Instrument with an agent

The [`composal-telemetry` skill](/skills/composal-telemetry.md) guides an agent through instrumenting an application with maintained OpenTelemetry libraries for its language and framework. Install the shipped Composal skills with `com setup`, then ask your agent:

> Use `$composal-telemetry` to instrument this application and run an evidence-backed verification.

The skill covers traces, logs, metrics, managed export validation, and baseline-versus-candidate performance analysis. It also defines safety requirements for shadow traffic: explicit authorization, isolated side effects, bounded load, and cleanup.

## Organization boundary

Every export names one organization with `X-Vex-Organization`. Composal checks the token's current membership and replaces any caller-provided `vex.organization_id`, `vex.organization_public_id`, or `vex.organization_slug` resource attributes with the verified organization identity. One request cannot write telemetry for multiple organizations.

Use a dedicated personal access token for telemetry exporters and rotate it through the same Composal controls as other API tokens. Do not put the token in source control or an OpenTelemetry resource attribute.

## Protocol and limits

The public endpoint supports OTLP/HTTP with protobuf or JSON request bodies and optional gzip content encoding. The maximum decoded request body is 64 MiB. Data is retained for 30 days during the initial managed service rollout. Public OTLP/gRPC and customer-direct ClickHouse access are not currently offered.