Elastic Distribution for OpenTelemetry Java

This project is the Elastic distribution of the OpenTelemetry Java agent.

This is currently an early alpha release and should be used mostly for testing.

Download

Latest release:

Latest snapshot:

Run

Use the -javaagent: JVM argument with the path to agent jar.

java -javaagent:/path/to/agent.jar \
-jar myapp.jar

Build and Test

Execute ./gradlew assemble, the agent binary will be in ./agent/build/libs/elastic-otel-javaagent-${VERSION}.jar where ${VERSION} is the current project version set in version.properties.

You can run the tests locally using ./gradlew test. You can optionally specify the

Java Version to test on, e.g. -PtestJavaVersion=8
Java implementation to run on (hotspot or openJ9): -PtestJavaVM=openj9

You don't need to have a corresponding JVM installed, gradle automatically will download a matching one.

Features

Resource attributes

The agent enables the following resource attributes providers from opentelemetry-java-contrib

AWS: aws-resources
GCP: gcp-resources
application server service name detection: resource-providers

The attributes for cloud providers are captured asynchronously to prevent application startup overhead due to calling an internal metadata API.

Inferred spans

Set ELASTIC_OTEL_INFERRED_SPANS_ENABLED=true to enable.

See inferred spans for more details

Span stacktrace

The agent captures the stacktraces of spans to help identify code paths that triggered them.

The stacktrace is stored in the code.stacktrace attribute.

The minimum span duration can be configured with elastic.otel.span.stack.trace.min.duration (in milliseconds, defaults to 5ms).

Breakdown metrics

Breakdown metrics currently require a custom Elasticsearch ingest pipeline.

PUT _ingest/pipeline/metrics-apm.app@custom
{
  "processors": [
    {
      "script": {
        "lang": "painless",
        "source": """

if(ctx.span == null){
  ctx.span = [:];
}
if(ctx.transaction == null){
  ctx.transaction = [:];
}
if(ctx.labels != null){
  if(ctx.labels.elastic_span_type != null){
    ctx.span.type = ctx.labels.elastic_span_type;
  }
  if(ctx.labels.elastic_span_subtype != null){
    ctx.span.subtype = ctx.labels.elastic_span_subtype;
  }
  if(ctx.labels.elastic_local_root_type != null){
    ctx.transaction.type = ctx.labels.elastic_local_root_type;
  }
  if(ctx.labels.elastic_local_root_name != null){
    ctx.transaction.name = ctx.labels.elastic_local_root_name;
  }
}

if(ctx.numeric_labels != null && ctx.numeric_labels.elastic_span_self_time != null){
  def value = ctx.numeric_labels.elastic_span_self_time/1000;
  def sum = [ 'us': value];
  ctx.span.self_time =  [ 'count': 0, 'sum': sum];
}

        """
      }
    }
  ]
}

License

The Elastic Distribution for OpenTelemetry Java is licensed under Apache License, Version 2.0.

elastic / elastic-otel-java

readme