Create Custom Spans with Annotations in Java

Overview

This document helps you get started with annotations in Java to create custom spans for user-defined functions and view your application traces in SigNoz.

Annotations

For the most part automatic instrumentation is sufficient. But sometimes, we want to create spans for our custom code without having to change code much. That's where the WithSpan and SpanAttribute annotations come into picture, these allow us to create spans with minimal code.

Requirements

Java 8 or higher

Installing Dependencies

You will need to add opentelemetry-instrumentation-annotations to use WithSpan annotations.

<dependencies>
  <dependency>
    <groupId>io.opentelemetry.instrumentation</groupId>
    <artifactId>opentelemetry-instrumentation-annotations</artifactId>
    <version>2.20.1</version>
  </dependency>
</dependencies>

dependencies {
    implementation('io.opentelemetry.instrumentation:opentelemetry-instrumentation-annotations:2.20.0')
}

Creating spans using @WithSpan

We can create a span around a particular method by annotating with @WithSpan.

import io.opentelemetry.instrumentation.annotations.WithSpan;

public class SomeClass {
    @WithSpan
    public void someMethod() {
        <...>
    }
}

Each time the application calls the annotated method, it creates a span that denotes the entire lifecycle and duration of that method and provides exceptions if any. By default, the span name is <class_name>.<method_name>, you can provide span name in annotation parameter such as:

@WithSpan("span name")
public void otherMethod() {
    <...>
}

Adding attributes to span using @SpanAttribute

When a span is created for an annotated method, the values of the arguments can be automatically added to the attributes of the span. Annotate the method parameters with @SpanAttribute annotation:

import io.opentelemetry.instrumentation.annotations.WithSpan;
import io.opentelemetry.instrumentation.annotations.SpanAttribute;

public class SomeClass {
    @WithSpan
    public void someMethod(@SpanAttribute("argument1") String argument1, @SpanAttribute("argument2") String argument2) {
        <...>
    }
}

curl -L -O 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

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

OTEL_EXPORTER_OTLP_ENDPOINT="http://<IP of SigNoz Backend>:4317" \
OTEL_RESOURCE_ATTRIBUTES=service.name=<service_name> \
java -javaagent:$PWD/opentelemetry-javaagent.jar -jar <my-app>.jar

java -javaagent:$PWD/opentelemetry-javaagent.jar \
    -Dotel.exporter.otlp.endpoint=http://<IP of SigNoz Backend>:4317 \
    -Dotel.resource.attributes=service.name=<service_name> \
    -jar <my-app>.jar

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. Ensure that you're checking data for the time range filter applied in the top right corner.
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.

Manual Instrumentation

For manual instrumentation of Java applications, refer to the docs here.

Get Help

If you need help with the steps in this topic, please reach out to us on SigNoz Community Slack.

If you are a SigNoz Cloud user, please use in product chat support located at the bottom right corner of your SigNoz instance or contact us at cloud-support@signoz.io.