Observability configuration

A binding selects an external observability target and an immutable configuration version. An organization can define a default; a Workspace can inherit it, select its own custom binding, or disable export. Sessions pin that selection when they are created.

Binding configuration fields

The organization PUT body contains target, config, capture_ceiling, and conditional write-only credentials. A Workspace custom PUT also requires mode: custom. These are full replacements, not merge patches. The table distinguishes accepted fields from the current exporter recipe.

For current delivery, use {type: "basic", username: <public key>, password: <secret key>}. The API also accepts bearer/custom-header bundles, but the current exporter delivers only Basic credentials. Store target keys through this API, not in agent metadata, Helm values, or exporter environment variables. Reads expose configured/version/hint/rotation metadata, never credential bytes or SecretStore references.

Select a binding

inherit and disabled reject target, config, and credential fields. State responses separate configured settings from effective source, status, capture mode, disabled reason, and selected binding. An enabled effective state is a control-plane decision, not an endpoint connectivity test or a guarantee that the exporter supports the configuration.

Target replacement creates a new binding and drains the previous one. Same-active-target policy replacement creates a new config version without rotating credentials. Existing session pins keep their target/config selection, subject to live revocation and capture restrictions. Create a new session to use a new target, sample rate, environment/release, or expanded capture permission.

Capture modes and privacy

The effective capture capability is the minimum of the requested or pinned mode and all applicable platform, organization, and Workspace ceilings. The order is metadata_only < redacted_io < raw_io. The migration-seeded platform maximum is metadata_only; a binding request alone cannot authorize content export.

Each serialized I/O value is limited to 8192 bytes. Pending input and active-turn I/O each have a 262144-byte budget. Oversized values are omitted whole; output accumulation can be truncated. The langfuse.observation.metadata.orca.io.* attributes identify unsupported, unavailable, partial, too-large, or budget-limited content. Standalone thinking/signature blocks, partial deltas, system instructions, and non-text message blocks are not included as root text. This structural selection does not filter similarly named fields inside tool arguments.

Raw content can persist in Kafka checkpoints/chunks, delivery records, and the local scratch index. Internal delivery retention is unlimited. Restricting capture stops subsequent disallowed delivery; it is not physical deletion of stored content or a deletion request to Litefuse.

Enable raw capture explicitly

Use the Litefuse metadata-only walkthrough first. The steps below assume its dedicated Workspace now has an active custom binding. Apply Registry migration 0060 through the normal migration runner before requesting raw_io; the exporter must use Kafka state.

1. Obtain explicit authorization for unredacted content and its retention. Prefer an isolated Registry/database, organization, Workspace, and Litefuse project.
2. A platform administrator reads and replaces the platform policy, preserving its allowlists and setting max_capture_mode: raw_io. Raising this ceiling affects eligible new sessions across the deployment, not just the Workspace in this example.
3. An organization administrator sets the organization's capture_ceiling: raw_io using the ceiling-only endpoint. This does not require or create an organization default binding.
4. Replace the existing Workspace custom config with config.capture_mode: raw_io and capture_ceiling: raw_io. Preserve target/config fields and omit credentials for the same target.
5. Read the effective state, then create a new session and send synthetic input. An old session does not gain raw permission by changing current configuration.

For the platform step, export ORCA_ADMIN_URL and ORCA_PLATFORM_KEY as described in the admin API reference. This example preserves the current allowlists rather than replacing them with a guessed default:

headers=$(mktemp)
policy=$(curl -fsS -D "$headers" "$ORCA_ADMIN_URL/v1/platform/agent_observability" \
  -H "x-api-key: $ORCA_PLATFORM_KEY")
ETAG=$(awk 'tolower($1) == "etag:" { sub(/\r$/, "", $2); print $2 }' "$headers")
rm -f "$headers"
IDEMPOTENCY_KEY=$(uuidgen)

jq '{allowed_adapters, allowed_endpoint_classes, max_capture_mode: "raw_io"}' <<< "$policy" |
  curl -fsS -X PUT "$ORCA_ADMIN_URL/v1/platform/agent_observability" \
    -H "x-api-key: $ORCA_PLATFORM_KEY" \
    -H "Content-Type: application/json" \
    -H "If-Match: $ETAG" \
    -H "Idempotency-Key: $IDEMPOTENCY_KEY" --data-binary @-

Use organization credentials, a fresh organization GET ETag, and a new idempotency key for PUT /v1/organizations/agent_observability/capture_ceiling with this body:

{ "capture_ceiling": "raw_io" }

For the Workspace step, read its current state and ETag. Build the full replacement from configured.binding.target and the mutable config fields in the table above. Do not send response-only version, config_schema_version, credential metadata, or lifecycle fields back to PUT. See replacement and concurrency.

Lowering any capture ceiling advances its restriction epoch. Older affected pins remain metadata-only even if that ceiling is later raised. Pending raw projection is scrubbed on restriction; queued content that no longer has authorization is terminally suppressed, not rewritten and resent. Do not reset epochs, rewind offsets, or recreate internal topics to restore content capture.

Rotate credentials or stop export

• Use the organization or Workspace :rotate_credentials operation with only credentials in the body. It advances the active binding's credential head without changing target/config or session pins. Delivery resolves current credentials before sending.
• Use Workspace mode: disabled to stop that Workspace.
• Organization :disable stops the organization default, not Workspace custom bindings. It accepts an empty body and optional If-Match for emergency use.

Neither disabling export nor credential rotation deletes already ingested traces.

Permissions

Scoped organization roles are available through admin API keys; organization OIDC requires org:admin. These are not public Workspace API permissions.

What's next