Lightstep Distro for OpenTelemetry Java

This is the Lightstep package for configuring OpenTelemetry

Agent

The Lightstep OpenTelemetry Agent is a configuration layer over OpenTelemetry Instrumentation Agent. Download the latest version of lightstep-opentelemetry-javaagent.jar.

Run

The instrumentation agent is enabled using the -javaagent flag to the JVM. Configuration parameters are passed as Java system properties (-D flags) or as environment variables. Full list of supported parameters.

Configuration via Java system properties

export LS_ACCESS_TOKEN=your-token

java -javaagent:path/to/lightstep-opentelemetry-javaagent.jar \
     -Dotel.service.name=your-service-name
     -Dotel.exporter.otlp.traces.endpoint=https://ingest.lightstep.com:443 \
     -jar myapp.jar

Configuration via environment variables

export LS_ACCESS_TOKEN=your-token
export OTEL_SERVICE_NAME=your-service-name
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://ingest.lightstep.com:443

java -javaagent:path/to/lightstep-opentelemetry-javaagent.jar \
     -jar myapp.jar

Observe that system properties have higher priority than environment variables.

Launcher

The Lightstep OpenTelemetry Launcher is a configuration layer over OpenTelemetry OTLP trace exporter.

Installation

pom.xml

<dependency>
    <groupId>com.lightstep.opentelemetry</groupId>
    <artifactId>opentelemetry-launcher</artifactId>
    <version>VERSION</version>
</dependency>

Usage

Easy initialization

// Installs exporter into tracer SDK default provider with batching span processor.
OpenTelemetryConfiguration.newBuilder()
                      .setServiceName("{service_name}")
                      .setAccessToken("{your_access_token}")
                      .setTracesEndpoint("{lightstep_host}")
                      .install();

// Get tracer
Tracer tracer = GlobalOpenTelemetry.getTracer("instrumentation-library-name", "1.0.0");

Manual configuration

// Create builder
Builder builder = OpenTelemetryConfiguration.newBuilder()
                      .setServiceName("{service_name}")
                      .setAccessToken("{your_access_token}")
                      .setTracesEndpoint("{lightstep_host}");

// Instantiate openTelemetry
OpenTelemetry openTelemetry = builder.buildOpenTelemetry().getOpenTelemetrySdk();

// Get tracer
Tracer tracer = openTelemetry.get("instrumentation-library-name", "1.0.0");

Logging

It uses java.util.logging therefore logging properties file can be specified via system property java.util.logging.config.file. E.g. -Djava.util.logging.config.file=path/to/logging.properties

System properties and environmental variables

Supported system properties and environmental variables:

Deprecated properties and environmental variables

OpenTelemetry Metrics support

Metrics support is currently experimental and it is disabled by default. It can be enabled via LS_METRICS_ENABLED=true. Breaking changes may still occur. Use at your own risk.

License

Apache 2.0 License.