Switch your OpenTelemetry backend to Osuite

Osuite is a standard OpenTelemetry backend: it accepts traces, logs, and metrics over OTLP on a single endpoint. If your services already emit OpenTelemetry — straight from the SDK or through a Collector — switching to Osuite is an endpoint and an auth header, not a re-instrumentation.

What changes

Two values change, and nothing else in your instrumentation does:

• Endpoint — send OTLP to ingest.<region>.osuite.io:443 over TLS, on port 443.
• Auth — attach the header x-osuite-ingest-token with your token.

Get your region endpoint and token from Getting Started. Osuite’s endpoint accepts OTLP over gRPC and HTTP; keep whichever protocol your exporter already uses.

Apps exporting OTLP directly

For a service that uses the OpenTelemetry SDK’s OTLP exporter with no Collector in between, set the standard OpenTelemetry environment variables:

OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.<region>.osuite.io:443
OTEL_EXPORTER_OTLP_HEADERS=x-osuite-ingest-token=<your-ingest-token>

These apply to all three signals. The https:// scheme keeps the exporter on TLS, which Osuite requires. If your code sets the endpoint and headers in the exporter constructor instead of through environment variables, change them there instead — the values are the same.

Existing OpenTelemetry Collector

If a Collector already sits in front of your services, add an otlp/osuite exporter and attach it to every pipeline. A typical Collector before the switch exports to another backend:

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:
    timeout: 5s
    send_batch_size: 1000

exporters:
  otlp:
    endpoint: your-current-backend:4317
    headers:
      api-key: <your-current-backend-key>

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp]

After the switch, the otlp/osuite exporter replaces it, and a resource processor stamps service.environment (see below):

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:
    timeout: 5s
    send_batch_size: 1000
  resource/environment:
    attributes:
      - key: service.environment
        value: production
        action: upsert

exporters:
  otlp/osuite:
    endpoint: ingest.<region>.osuite.io:443
    tls:
      insecure: false
    headers:
      x-osuite-ingest-token: <your-ingest-token>

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch, resource/environment]
      exporters: [otlp/osuite]
    metrics:
      receivers: [otlp]
      processors: [batch, resource/environment]
      exporters: [otlp/osuite]
    logs:
      receivers: [otlp]
      processors: [batch, resource/environment]
      exporters: [otlp/osuite]

To send data to Osuite and your current backend at the same time during a migration, keep both exporters and list them together in each pipeline: exporters: [otlp, otlp/osuite].

Set service.environment

Osuite separates data by deployment environment using the service.environment resource attribute. Set it so production, staging, and development stay distinct in APM, logs, and metrics.

• Direct SDK export — set it in the resource attributes, alongside the service name in OTEL_SERVICE_NAME:

  OTEL_SERVICE_NAME=checkout
  OTEL_RESOURCE_ATTRIBUTES=service.environment=production

• Collector — use the resource processor shown in the after config above.

See Concepts for how service.environment shapes correlation across signals.

Verify in Osuite

What you should see

Within a minute of the switch, your existing services reappear in Osuite — traces in APM, logs in the Logs explorer, metrics in the Explore metrics view — now tagged with their service.environment. Only the destination changed; the instrumentation did not.

Troubleshooting

If data still lands in your old backend and not in Osuite, confirm you replaced the exporter in every pipeline — traces, metrics, and logs each need the otlp/osuite exporter attached. If you meant to keep both destinations, both exporters must be listed in each pipeline.

No data in Osuite after a few minutes? Work through these checks.

• Endpoint — confirm the exporter targets exactly ingest.<region>.osuite.io:443 for your region, over TLS.
• Token — confirm the ingest header carries a valid <your-ingest-token> and has not been rotated.
• Pipeline — confirm the signal you expect (traces, logs, or metrics) is wired into an active pipeline with the otlp/osuite exporter attached.
• Export errors — check the application or Collector logs for OTLP export failures (auth, DNS, TLS, connection refused).
• Network — confirm the host has outbound access to the ingest endpoint on port 443.
• Timing — allow up to a minute for the first data to appear before assuming a failure.

Still stuck? Ask the Investigation Agent or contact support.

Next steps

• Concepts — signals, correlation, and service.environment.
• OTLP endpoints — regions, ports, and headers.
• Instrumentation — per-language guides if you add a service that is not yet instrumented.