Java OpenTelemetry Instrumentation

Get up and running with OpenTelemetry in just a few quick steps! The setup process consists of two phases--getting OpenTelemetry installed and configured, and then validating that configuration to ensure that data is being sent as expected. This guide explains how to download, install, and run OpenTelemetry in Java.

We follow OpenTelemetry java instrumentation library. We shall be exporting data in OTLP format.

Getting Started

Download the latest version.

This package includes the instrumentation agent as well as instrumentations for all supported libraries and all available data exporters. The package provides a completely automatic, out-of-the-box experience.

Enable the instrumentation agent using the -javaagent flag to the JVM.

 

For Java applications packaged as JAR files

If you run your Java application as a JAR file, please follow the below instruction

OTEL_METRICS_EXPORTER=none OTEL_EXPORTER_OTLP_ENDPOINT="http://<IP of SigNoz Backend>:4317" OTEL_RESOURCE_ATTRIBUTES=service.name=<app_name> java -javaagent:/path/opentelemetry-javaagent.jar -jar  <myapp>.jar

where <app_name> is the name you want to set for your application. path should be updated to the path of downloaded Java JAR agent.

You can also specify environment variables in the following way

java -javaagent:/path/opentelemetry-javaagent.jar \
    -Dotel.metrics.exporter=none \
    -Dotel.exporter.otlp.endpoint=http://<IP of SigNoz Backend>:4317 \
    -Dotel.resource.attributes="service.name=<app_name>" \
    -jar <myapp>.jar

note

Remember to allow incoming requests to port 4317 of machine where SigNoz backend is hosted

If you want to try out SigNoz with a sample Java application, visit this GitHub repo.

 

Tomcat Instrumentation

For Tomcat application, you need to make sure the following environment variables are set up.

If you run your .war package by putting in webapps folder, just add setenv.sh in your Tomcat bin folder.

This should set these environment variables and start sending telemetry data to SigNoz backend specified in the IP

export CATALINA_OPTS="$CATALINA_OPTS -javaagent:/path/to/opentelemetry-javaagent.jar"
export OTEL_METRICS_EXPORTER=none
export OTEL_EXPORTER_OTLP_ENDPOINT=http://<IP of SigNoz Backend>:4317
export OTEL_RESOURCE_ATTRIBUTES=service.name=<app_name>

where app_name is the name you want to set for your application and IP of SigNoz Backend is the IP where SigNoz backend is accessible

 

Here's a video on how to instrument Tomcat applications with SigNoz and a blog with step by step instructions.

 

Troubleshooting your installation

If spans are not being reported to SigNoz, try running in debug mode by setting OTEL_LOG_LEVEL=debug:

The debug log level will print out the configuration information. It will also emit every span to the console, which should look something like:

Span {
  attributes: {},
  links: [],
  events: [],
  status: { code: 0 },
  endTime: [ 1597810686, 885498645 ],
  _ended: true,
  _duration: [ 0, 43333 ],
  name: 'bar',
  spanContext: {
    traceId: 'eca3cc297720bd705e734f4941bca45a',
    spanId: '891016e5f8c134ad',
    traceFlags: 1,
    traceState: undefined
  },
  parentSpanId: 'cff3a2c6bfd4bbef',
  kind: 0,
  startTime: [ 1597810686, 885455312 ],
  resource: Resource { labels: [Object] },
  instrumentationLibrary: { name: 'example', version: '*' },
  _logger: ConsoleLogger {
    debug: [Function],
    info: [Function],
    warn: [Function],
    error: [Function]
  },
  _traceParams: {
    numberOfAttributesPerSpan: 32,
    numberOfLinksPerSpan: 32,
    numberOfEventsPerSpan: 128
  },
  _spanProcessor: MultiSpanProcessor { _spanProcessors: [Array] }
},

 

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.