Getting Started
Automatic Instrumentation
Automatic instrumentation is applicable to trace data only today.
Download the latest version. This package includes the instrumentation agent, instrumentations for all supported libraries and all available data exporters.
The instrumentation agent is enabled by passing the -javaagent flag to the JVM.
java -javaagent:path/to/opentelemetry-javaagent-all.jar \
-jar myapp.jar
By default OpenTelemetry Java agent uses the OTLP
exporter
configured to send data to a local OpenTelemetry
Collector
at localhost:55680.
Configuration parameters are passed as Java system properties (-D flags) or as
environment variables. For example:
java -javaagent:path/to/opentelemetry-javaagent-all.jar \
-Dotel.exporter=zipkin \
-jar myapp.jar
An exporter jar can be specified via the otel.exporter.jar system property:
java -javaagent:path/to/opentelemetry-javaagent-all.jar \
-Dotel.exporter.jar=path/to/external-exporter.jar \
-jar myapp.jar
For additional information, see the Automatic Instrumentation documentation.
Manual Instrumentation
Traces
import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.context.Scope;
import io.opentelemetry.exporter.otlp.OtlpGrpcSpanExporter;
import io.opentelemetry.sdk.OpenTelemetrySdk;
import io.opentelemetry.sdk.trace.export.BatchSpanProcessor;
public class DoWork {
// Instantiate a tracer
Tracer tracer =
OpenTelemetry.getGlobalTracer("io.opentelemetry.example.dowork");
// Configure the SDK with batch processor and OTLP gRPC exporter
OtlpGrpcSpanExporter spanExporter = OtlpGrpcSpanExporter.getDefault();
BatchSpanProcessor spanProcessor =
BatchSpanProcessor.builder(spanExporter).setScheduleDelayMillis(100).build();
OpenTelemetrySdk.getGlobalTracerManagement().addSpanProcessor(spanProcessor);
for (int i = 0; i < 10; i++) {
// Start a span with scope
Span exampleSpan = tracer.spanBuilder("exampleSpan").startSpan();
try (Scope scope = exampleSpan.makeCurrent()) {
// Add attributes
exampleSpan.setAttribute("good", "true");
exampleSpan.setAttribute("exampleNumber", i);
Thread.sleep(100);
} finally {
// End span
exampleSpan.end();
}
}
}
For more detailed information, see the Manual Instrumentation documentation.
Example
Several examples are provided to get started. The HTTP example demonstrates how to manually instrument a simple HTTP based Client/Server application. The example creates a root span on the client and sends the context over the HTTP request. On the server side, the example shows how to extract the context and create a child span with an attached span event. All generated data is logged locally.
To get started, perform the following steps::
- Clone the repository
- Change into the example directory
- Compile the code
- Start the server
- Start the client
git clone git@github.com:open-telemetry/opentelemetry-java.git
cd opentelemetry-java/examples/http
../gradlew fatJar
java -cp ./build/libs/opentelemetry-examples-http-all-0.1.0-SNAPSHOT.jar io.opentelemetry.example.http.HttpServer
java -cp ./build/libs/opentelemetry-examples-http-all-0.1.0-SNAPSHOT.jar io.opentelemetry.example.http.HttpClient
Metrics
import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.api.metrics.LongCounter;
import io.opentelemetry.api.metrics.Meter;
import io.opentelemetry.context.Scope;
import io.opentelemetry.exporter.otlp.OtlpGrpcMetricExporter;
import io.opentelemetry.sdk.OpenTelemetrySdk;
import io.opentelemetry.sdk.metrics.export.IntervalMetricReader;
public class DoWork {
// Instantiate a meter
Meter meter =
OpenTelemetry.getGlobalMeter("io.opentelemetry.example.dowork");
// Configure the SDK with OTLP gRPC exporter
OtlpGrpcMetricExporter metricExporter = OtlpGrpcMetricExporter.getDefault();
IntervalMetricReader intervalMetricReader =
IntervalMetricReader.builder()
.setMetricExporter(metricExporter)
.setMetricProducers(
Collections.singleton(
OpenTelemetrySdk.getGlobalMeterProvider().getMetricProducer()))
.setExportIntervalMillis(500)
.build();
for (int i = 0; i < 10; i++) {
// Create a metric
counter.add(1);
}
}
For more detailed information, see the Manual Instrumentation documentation.
Example
Several examples are provided to get started. The metrics examples demonstrates how to generate other types of metrics.