Type to search.

Instrumenting Java applications using the EDOT Java runtime attach

Serverless Observability

Elastic Cloud Serverless projects are autoscaled environments, fully managed by Elastic and available on Elastic Cloud.

Availability

  • Generally available

    This functionality is generally available and ready for production usage.

Stack

The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats.

Availability

  • Generally available

    This functionality is generally available and ready for production usage.

Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments.

This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes.

EDOT Java Preview 1.0+

The Elastic Distribution of OpenTelemetry (EDOT) Java SDK collects performance metrics, traces, and logs in OpenTelemetry format, and sends them to Elastic Observability.

Availability

  • Preview since 1.0

    This functionality is in technical preview and is ready for evaluation. Use with caution in production; it is not recommended for mission-critical workloads. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. Specific Support terms apply.

This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes.

Runtime attach includes the EDOT instrumentation agent in the application binary. This allows deploying the agent when access to JVM arguments or configuration is not possible, for example, with some managed services. The application development team can control the agent deployment and update cycle without having to modify the execution environment. Runtime attach only requires a minor modification of the application main entry point and one additional dependency.

The following limitations apply:

  • Runtime attach can't be used with multiple applications that share a JVM, for example, with web-applications and application servers. In this case, only the -javaagent setup option is supported.
  • Agent update is tied to the application development and deployment lifecycle. You can't update application and agent independently.
  • Agent can only be attached at application start; it can't be used to attach later during application runtime.
  • Recent JVMs issue warnings in standard error and the feature might require explicit opt-in with JVM settings in the future.

Follow these steps to instrument your Java application using runtime attach.

  1. Add runtime attach to application dependencies

    Xml 
    <dependency>
  <groupId>co.elastic.otel</groupId>
  <artifactId>elastic-otel-runtime-attach</artifactId>
  <version>1.14.0</version>
</dependency>
    Kotlin 
    implementation("co.elastic.otel:elastic-otel-runtime-attach:1.14.0")

  2. Modify the main method

    Add a single call to RuntimeAttach.attachJavaagentToCurrentJvm() at the start of the main method body. Here is an example of a simple spring-boot application:

    Java 
    @SpringBootApplication
public class MyApplication {

    public static void main(String[] args) {
        RuntimeAttach.attachJavaagentToCurrentJvm();
        SpringApplication.run(MyApplication.class, args);
    }
}

  3. Package and redeploy the application

    After you've added the new dependency and modified the main method, package and redeploy your application.

The following warning might appear in the process standard error output:

Text 
WARNING: A Java agent has been loaded dynamically (/tmp/otel-agent6227828786286549290/agent.jar)
WARNING: If a serviceability tool is in use, please run with -XX:+EnableDynamicAgentLoading to hide this warning
WARNING: If a serviceability tool is not in use, please run with -Djdk.instrument.traceUsage for more information
WARNING: Dynamic loading of agents will be disallowed by default in a future release

This message indicates that the dynamic agent attachment will be disabled by in the future. Add -XX:+EnableDynamicAgentLoading to the JVM arguments, or to the JAVA_TOOL_OPTIONS environment variable, to silence it.

The runtime attach feature will be turned off by default in future JVM versions. Until then, you can ignore the warning.