Managed OpenTelemetry

Composal Managed OpenTelemetry accepts logs, metrics, and traces at https://otel.composal.ai. Confirm that https://otel.composal.ai/readyz is reachable before enabling an exporter. Use a Composal personal access token and choose the organization that owns the telemetry. The managed service retains organization-scoped signals for performance analysis, testing, and debugging; agent query access is a separate authorized capability and does not expose ClickHouse directly.

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.

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 the payload enters Composal's durable exporter queue. ClickHouse delivery then happens asynchronously with bounded retries. 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 guides an agent through instrumenting an application with maintained OpenTelemetry libraries for its language and framework. Have your agent read that guide, then ask it:

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.

For Verify and tester runs, keep composal.verify.sweep_id, vex.app.id, vex.environment.id, service.name, service.version, and deployment.environment.name as resource attributes on every signal. Add the bounded composal.verify.attempt_id, composal.verify.scenario_id, and composal.verify.persona_id to request spans or to the resource when a runtime is dedicated to one attempt. This lets Verify select only the authorized organization, exact sweep, app, environment, service, and release before returning representative traces.

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.