Quarkus OpenTelemetry Instrumentation Guide

This guide walks you through instrumenting your Quarkus application with OpenTelemetry and sending traces to SigNoz. Quarkus uses built-in OpenTelemetry extensions rather than the Java agent, making it well-suited for both JVM and native builds.

Most steps are identical. To adapt this guide, update the endpoint and remove the ingestion key header as shown in Cloud to Self-Hosted.

Prerequisites

JDK 17+
A Quarkus REST application
A SigNoz Cloud account or self-hosted SigNoz instance

Send traces to SigNoz

Step 1. Set environment variables

export OTEL_RESOURCE_ATTRIBUTES="service.name=my-quarkus-app,service.version=<service-version>"
export OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.<region>.signoz.cloud:443"
export OTEL_EXPORTER_OTLP_HEADERS="signoz-ingestion-key=<your-ingestion-key>"

Add these environment variables to your deployment manifest:

env:
- name: OTEL_RESOURCE_ATTRIBUTES
  value: 'service.name=my-quarkus-app,service.version=<service-version>'
- name: OTEL_EXPORTER_OTLP_ENDPOINT
  value: 'https://ingest.<region>.signoz.cloud:443'
- name: OTEL_EXPORTER_OTLP_HEADERS
  value: 'signoz-ingestion-key=<your-ingestion-key>'

$env:OTEL_RESOURCE_ATTRIBUTES = "service.name=my-quarkus-app,service.version=<service-version>"
$env:OTEL_EXPORTER_OTLP_ENDPOINT = "https://ingest.<region>.signoz.cloud:443"
$env:OTEL_EXPORTER_OTLP_HEADERS = "signoz-ingestion-key=<your-ingestion-key>"

Add to your Dockerfile:

ENV OTEL_RESOURCE_ATTRIBUTES="service.name=my-quarkus-app,service.version=<service-version>"
ENV OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.<region>.signoz.cloud:443"
ENV OTEL_EXPORTER_OTLP_HEADERS="signoz-ingestion-key=<your-ingestion-key>"

Or pass at runtime:

docker run -p 8080:8080 \
  -e OTEL_RESOURCE_ATTRIBUTES="service.name=my-quarkus-app,service.version=<service-version>" \
  -e OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.<region>.signoz.cloud:443" \
  -e OTEL_EXPORTER_OTLP_HEADERS="signoz-ingestion-key=<your-ingestion-key>" \
  my-quarkus-app

Verify these values:

<region>: Your SigNoz Cloud region
<your-ingestion-key>: Your SigNoz ingestion key.
<service-version> (optional): Your release version, image tag, or git SHA (e.g., 1.4.2, a01dbef8).

Set service.version to a per-build value, not a static string. SigNoz detects a deployment each time this value changes. Common sources:

Bash / shell: service.version=$(git rev-parse --short HEAD)
GitHub Actions: service.version=${{ github.sha }}
GitLab CI: service.version=$CI_COMMIT_SHORT_SHA
Kubernetes: inject from your Helm chart image tag or CI variable

Step 2. Add the OpenTelemetry extension

quarkus extension add opentelemetry

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

Or add directly to your pom.xml:

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

Step 3. Configure application.properties

Add the following configuration to src/main/resources/application.properties:

quarkus.application.name=my-quarkus-app
 
quarkus.otel.exporter.otlp.endpoint=${OTEL_EXPORTER_OTLP_ENDPOINT}
quarkus.otel.exporter.otlp.headers=${OTEL_EXPORTER_OTLP_HEADERS:}
quarkus.otel.resource.attributes=${OTEL_RESOURCE_ATTRIBUTES:}

This configuration reads values from environment variables, making it easy to configure different environments without code changes.

Step 4. Build and run your application

./mvnw package
java -jar target/quarkus-app/quarkus-run.jar

Quarkus OpenTelemetry works with native builds too. The extension is designed to compile to native code:

# Build native executable
./mvnw package -Pnative
 
# Run the native executable
./target/my-app-runner

Make sure to set the same environment variables before running the native executable.

Validate

With your application running, verify traces are being sent to SigNoz:

Make a few requests to your application endpoints.
In SigNoz, open the Services tab and click Refresh. Your application should appear.
Go to the Traces tab to see your application's traces.

Troubleshooting

Still not seeing data in SigNoz? Work through Debug missing traces, logs, and metrics, which covers SDK diagnostics, Collector connectivity, and the common ingestion errors for all three signals.

Traces not showing up in SigNoz?

Check environment variables:

echo $OTEL_EXPORTER_OTLP_ENDPOINT
echo $OTEL_RESOURCE_ATTRIBUTES

Enable debug logging in application.properties:

quarkus.log.category."io.opentelemetry".level=DEBUG

Test connectivity:

curl -v https://ingest.<region>.signoz.cloud:443/v1/traces

Extension not found?

Make sure the quarkus-opentelemetry extension is in your dependencies:

# Check installed extensions
./mvnw quarkus:list-extensions -Dinstalled

If missing, add it:

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

Quarkus dev mode not sending traces?

In dev mode, make sure environment variables are set in your terminal before running:

export OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.<region>.signoz.cloud:443"
export OTEL_EXPORTER_OTLP_HEADERS="signoz-ingestion-key=<your-ingestion-key>"
./mvnw quarkus:dev

Native build failing with OpenTelemetry?

Ensure you're using a GraalVM-compatible version of the OpenTelemetry extension. Check the Quarkus platform BOM version in your pom.xml and update if needed:

<quarkus.platform.version>3.8.0</quarkus.platform.version>

Why not use the Java agent with Quarkus?

The Java agent relies on bytecode manipulation at runtime, which conflicts with:

Native builds: GraalVM native-image compiles bytecode ahead of time, so runtime agents cannot work
Quarkus build-time optimization: Quarkus performs dependency injection and configuration at build time

The quarkus-opentelemetry extension is designed to work with Quarkus's build-time approach and supports both JVM and native modes.

Next steps

Add manual instrumentation for custom spans and business context
Collect Java application logs with OpenTelemetry
Set up alerts for your Quarkus application

Sample application:

Quarkus demo app with OpenTelemetry