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>
@WithSpan
Creating spans using 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() {
<...>
}
@SpanAttribute
Adding attributes to span using 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) {
<...>
}
}
Send traces to SigNoz Cloud
OpenTelemetry provides a handy Java JAR agent that can be attached to any Java 8+ application and dynamically injects bytecode to capture telemetry from a number of popular libraries and frameworks.
Step 1: Download the latest OpenTelemetry Java agent binary
curl -L -O https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar
Step 2: Run your application
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
- Set the
<region>
to match your SigNoz Cloud region - Replace
<your-ingestion-key>
with your SigNoz ingestion key <service_name>
is name of your service
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:
- 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.
- In SigNoz, open the
Services
tab. Hit theRefresh
button on the top right corner, and your application should appear in the list ofApplications
. Ensure that you're checking data for thetime range filter
applied in the top right corner. - 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.