Spring Boot OpenTelemetry Instrumentation

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

Requirements

Java 8 or higher

wget https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar

OTEL_RESOURCE_ATTRIBUTES=service.name=<service_name> \
OTEL_EXPORTER_OTLP_HEADERS="signoz-ingestion-key=<your-ingestion-key>" \
OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.<region>.signoz.cloud:443 \
java -javaagent:$PWD/opentelemetry-javaagent.jar -jar <my-app>.jar

wget https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar

java -javaagent:$PWD/opentelemetry-javaagent.jar -jar <myapp>.jar

Note: By default, Java auto-instrumentation does not create spans for user-defined functions. In such scenarios, we can use annotations to quickly create spans for user-defined functions with minimal code change. You can instrument your Spring Boot application following this guide on annotations.

Validating instrumentation by checking for traces

With your application running, you can verify that you’ve instrumented your application with OpenTelemetry correctly by confirming that tracing data is being reported to SigNoz.

To do this, you need to ensure that your application generates some data. Applications will not produce traces unless they are being interacted with, and OpenTelemetry will often buffer data before sending. So you need to interact with your application and wait for some time to see your tracing data in SigNoz.

Validate your traces in SigNoz:

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.
2. In SigNoz, open the Services tab. Hit the Refresh button on the top right corner, and your application should appear in the list of Applications.
3. Go to the Traces tab, and apply relevant filters to see your application’s traces.

Configuring the agent

The agent is highly configurable. You can check out all the configuration options available here.

Disabled instrumentations

Some instrumentations can produce too many spans and make traces very noisy. For this reason, the following instrumentations are disabled by default:

• jdbc-datasource which creates spans whenever the java.sql.DataSource#getConnection method is called.
• dropwizard-metrics, which might create very low-quality metrics data because of the lack of label/attribute support in the Dropwizard metrics API.

To enable them, add the otel.instrumentation.<name>.enabled system property: -Dotel.instrumentation.jdbc-datasource.enabled=true

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] }
},

Sample Application

• We have included a sample application at:
  • Sample Java App Github Repo.
  • Sample Springboot App Github Repo.