Quarkus OpenTelemetry instrumentation

Quarkus has first-class OpenTelemetry support through the quarkus-opentelemetry extension. It builds the SDK and exporter into your application and configures them through Quarkus config, so there is no agent to attach. This is also the recommended path for Quarkus native images, where the Java agent cannot run.

Fastest path. Run this in your AI IDE and the Instrumentation Agent wires this service up for you.

/osuite-instrument quarkus

Adds the OpenTelemetry extension and wires the exporter to Osuite.

Prefer to do it by hand? Follow the manual steps below — they are the complete path.

Prerequisites

A Quarkus application (Quarkus 3.x).
Your Osuite ingest endpoint (ingest.<region>.osuite.io:443) and token (<your-ingest-token>).
Outbound network access from the application host to the ingest endpoint on port 443.

Add the OpenTelemetry extension

quarkus extension add opentelemetry

./mvnw quarkus:add-extension -Dextensions="opentelemetry"

Or add the dependency directly:

<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-opentelemetry</artifactId>
</dependency>

implementation("io.quarkus:quarkus-opentelemetry")

Configure the exporter

Set the endpoint, protocol, and token in application.properties. Quarkus derives service.name from quarkus.application.name. Keep the token in an environment variable rather than in source control:

quarkus.application.name=catalog-service
quarkus.otel.exporter.otlp.endpoint=https://ingest.<region>.osuite.io:443
quarkus.otel.exporter.otlp.protocol=grpc
quarkus.otel.exporter.otlp.headers=x-osuite-ingest-token=${OSUITE_INGEST_TOKEN}
quarkus.otel.resource.attributes=service.environment=production

Traces are enabled by default. To also export logs and metrics, enable them:

quarkus.otel.logs.enabled=true
quarkus.otel.metrics.enabled=true

Run the service

Supply the ingest token through OSUITE_INGEST_TOKEN. Every tab is a complete, self-contained path.

export OSUITE_INGEST_TOKEN="<your-ingest-token>"
java -jar target/quarkus-app/quarkus-run.jar

Pass the token at runtime instead of baking it into the image:

docker run \
  -e OSUITE_INGEST_TOKEN="<your-ingest-token>" \
  catalog-service:latest

Store the token in a Secret and expose it as OSUITE_INGEST_TOKEN:

kubectl create secret generic osuite-ingest \
  --from-literal=ingest-token="<your-ingest-token>"

apiVersion: apps/v1
kind: Deployment
metadata:
  name: catalog-service
spec:
  replicas: 1
  selector:
    matchLabels:
      app: catalog-service
  template:
    metadata:
      labels:
        app: catalog-service
    spec:
      containers:
        - name: catalog-service
          image: catalog-service:latest
          env:
            - name: OSUITE_INGEST_TOKEN
              valueFrom:
                secretKeyRef:
                  name: osuite-ingest
                  key: ingest-token

Verify in Osuite

What you should see

Start the service and send it some traffic. It appears in APM within a minute, emitting request-rate, error-rate, and latency metrics, and its requests show up as traces in the trace explorer.

Troubleshooting

For native-image and exporter-connectivity problems, see Java troubleshooting.

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.