Quarkus OpenTelemetry Instrumentation

This document contains instructions on how to set up OpenTelemetry instrumentation in your Quarkus applications and view your application traces in SigNoz.

OpenTelemetry's Java implementation integrates seamlessly with Quarkus through its extension system, providing automatic instrumentation with minimal configuration.

There are two steps to using OpenTelemetry with Quarkus:

• Instrumenting your Quarkus application with OpenTelemetry
• Validating the configuration to ensure data is being sent as expected

Prerequisite

• A Quarkus REST application with basic endpoints
• Java 17 or higher environment
• Docker (if using Docker and Kubernetes)

Configuration Steps

• Add OpenTelemetry extension to your project:

# Using Quarkus CLI
quarkus extension add opentelemetry

• Update the application.properties file to enable and configure OpenTelemetry

# Application name and version
quarkus.application.name=quarkus-app
quarkus.application.version=1.0.0

# Ingestion key for authentication (only if using Signoz Cloud)
quarkus.otel.exporter.otlp.headers=${OTEL_EXPORTER_OTLP_HEADERS:}

# Enable OpenTelemetry SDK
quarkus.otel.sdk.disabled=false

# Enable tracing
quarkus.otel.traces.enabled=true

# Set sampler to always collect traces based on parent context
quarkus.otel.traces.sampler=parentbased_always_on

# Sampling rate argument (1.0 means 100% sampling)
quarkus.otel.traces.sampler.arg=1.0

# Use OTLP exporter for sending trace data
quarkus.otel.traces.exporter=otlp

# OTLP exporter endpoint (base URL for telemetry data)
quarkus.otel.exporter.otlp.endpoint=${OTEL_EXPORTER_OTLP_ENDPOINT}

# Specific endpoint for exporting trace data
quarkus.otel.exporter.otlp.traces.endpoint=${OTEL_EXPORTER_OTLP_ENDPOINT}/v1/traces

# Protocol used by OTLP exporter (HTTP with Protobuf encoding)
quarkus.otel.exporter.otlp.protocol=http/protobuf

# Additional resource attributes for telemetry data
quarkus.otel.resource.attributes=${OTEL_RESOURCE_ATTRIBUTES}

export OTEL_RESOURCE_ATTRIBUTES=service.name=<app-name>
export OTEL_EXPORTER_OTLP_HEADERS="signoz-ingestion-key=SIGNOZ_INGESTION_KEY"
export OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.{region}.signoz.cloud:443

# Using Quarkus CLI
quarkus build
java -jar target/quarkus-app/quarkus-run.jar

In case you encounter an issue where all applications do not get listed in the services section then please refer to the troubleshooting section.

Validating Instrumentation

To verify your instrumentation is working:

1. Trigger an action in your app that generates a web request. Hit the endpoint a number of times to generate some data. Then, wait for some time. Ex:

curl http://localhost:8080/hello

2. Check the Services tab in SigNoz UI for your application

3. Navigate to the Traces tab to see detailed traces

Sample Application

• We have included a sample application at:
  • Sample Quarkus App Github Repo

Troubleshooting

If traces are not appearing:

• Verify your configuration in application.properties
• Check application logs for OpenTelemetry-related errors
• Try enabling debug logging by setting quarkus.log.category."io.opentelemetry".level=DEBUG
• Check logs if your application is able to reach the SigNoz endpoint, If not you will see errors in the logs similar to

  2024-12-15 12:06:43,469 WARNING [io.ope.exp.int.htt.HttpExporter] (OkHttp https://ingest.in.signoz.cloud/...) Failed to export spans. Server responded with HTTP status code 401. Error message: Unable to parse response body, HTTP status message: Unauthorized
  

  or

  2024-12-15 12:17:50,343 SEVERE [io.ope.exp.int.htt.HttpExporter] (OkHttp http://localhost:4318/...) Failed to export spans. The request could not be executed. Full error message: Failed to connect to localhost/[0:0:0:0:0:0:0:1]:4318: java.net.ConnectException: Failed to connect to localhost/[0:0:0:0:0:0:0:1]:4318
  

  • If using SigNoz Cloud, check if the ingestion key and endpoint are correct.
  • If using self-hosted SigNoz, check if the endpoint is correct and if you have allowed incoming requests to the port 4318 of the machine where SigNoz backend is hosted.

Frequently Asked Questions

1. How to find what to use in IP of SigNoz if I have installed SigNoz in Kubernetes cluster?

   Based on where you have installed your application and where you have installed SigNoz, you need to find the right value for this. Please use this grid to find the value you should use for IP of SigNoz

2. I am sending data from my application to SigNoz, but I don't see any events or graphs in the SigNoz dashboard. What should I do?

   This could be because of one of the following reasons:

   1. Your application is generating telemetry data, but not able to connect with SigNoz installation

      Please use this troubleshooting guide to find if your application is able to access SigNoz installation and send data to it.

   2. Your application is not actually generating telemetry data

      Please check if the application is generating telemetry data first. You can use Console Exporter to just print your telemetry data in console first. Join our Slack Community if you need help on how to export your telemetry data in console

   3. Your SigNoz installation is not running or behind a firewall

      Please double check if the pods in SigNoz installation are running fine. docker ps or kubectl get pods -n platform are your friends for this.

What Cloud Endpoint Should I Use?

The primary method for sending data to SigNoz Cloud is through OTLP exporters. You can either send the data directly from your application using the exporters available in SDKs/language agents or send the data to a collector agent, which batches/enriches telemetry and sends it to the Cloud.

My Collector Sends Data to SigNoz Cloud

Using gRPC Exporter

The endpoint should be ingest.{region}.signoz.cloud:443, where {region} should be replaced with in, us, or eu. Note that the exporter endpoint doesn't require a scheme for the gRPC exporter in the collector.

# Sample config with `us` region
exporters:
    otlp:
        endpoint: "ingest.us.signoz.cloud:443"
        tls:
            insecure: false
        headers:
            "signoz-ingestion-key": "<SIGNOZ_INGESTION_KEY>"

Using HTTP Exporter

The endpoint should be https://ingest.{region}.signoz.cloud:443, where {region} should be replaced with in, us, or eu. Note that the endpoint includes the scheme https for the HTTP exporter in the collector.

# Sample config with `us` region
exporters:
    otlphttp:
        endpoint: "https://ingest.us.signoz.cloud:443"
        tls:
            insecure: false
        headers:
            "signoz-ingestion-key": "<SIGNOZ_INGESTION_KEY>"

My Application Sends Data to SigNoz Cloud

The endpoint should be configured either with environment variables or in the SDK setup code.

Using Environment Variables

Using gRPC Exporter

Examples with us region

• OTEL_EXPORTER_OTLP_PROTOCOL=grpc OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.us.signoz.cloud:443 OTEL_EXPORTER_OTLP_HEADERS=signoz-ingestion-key=<SIGNOZ_INGESTION_KEY>

Using HTTP Exporter

• OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.us.signoz.cloud:443 OTEL_EXPORTER_OTLP_HEADERS=signoz-ingestion-key=<SIGNOZ_INGESTION_KEY>

Configuring Endpoint in Code

Please refer to the agent documentation.

Sending Data from a Third-Party Service

The endpoint configuration here depends on the export protocol supported by the third-party service. They may support either gRPC, HTTP, or both. Generally, you will need to adjust the host and port. The host address should be ingest.{region}.signoz.cloud:443, where {region} should be replaced with in, us, or eu, and port 443 should be used.