Lightstep Distro for OpenTelemetry Java

NOTE: This is in beta and is expected to GA in Fall 2020.

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-<version>.jar \
     -Dls.service.name=your-service-name
     -Dotel.exporter.otlp.span.endpoint=ingest.lightstep.com \
     -jar myapp.jar

Configuration via environment variables

export LS_ACCESS_TOKEN=your-token
export LS_SERVICE_NAME=your-service-name
export OTEL_EXPORTER_OTLP_SPAN_ENDPOINT=ingest.lightstep.com

java -javaagent:path/to/lightstep-opentelemetry-javaagent-<version>.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}")
                      .setSpanEndpoint("{lightstep_host}")
                      .install();

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

Manual configuration

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

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


// 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:

System property	Environment variable	Purpose	Default
ls.service.name	LS_SERVICE_NAME	Service name
ls.service.version	LS_SERVICE_VERSION	Service version
ls.access.token	LS_ACCESS_TOKEN	Token for Lightstep access
otel.exporter.otlp.span.endpoint	OTEL_EXPORTER_OTLP_SPAN_ENDPOINT	Satellite URL	https://ingest.lightstep.com
otel.propagators	OTEL_PROPAGATORS	Propagator	b3multi
otel.log.level	OTEL_LOG_LEVEL	Log level for agent, to see more messages set to debug, to disable set to off	info
otel.resource.attributes	OTEL_RESOURCE_ATTRIBUTES	Comma separated key-value pairs

License

Apache 2.0 License.