OpenTelemetry (OTel) agent

OpenTelemetry’s mission is to enable effective observability by making high-quality, portable telemetry ubiquitous. Refer here for OpenTelemetry’s mission, vision, and values.

OpenTelemetry supports observability by following two key principles:

1. You own the data that you generate. There’s no vendor lock-in.
2. You only have to learn a single set of APIs and conventions.

OTel is an observability framework and toolkit designed to generate, collect, manage, and export telemetry data in a standardised manner. OTel uses OpenTelemetry protocol (OTLP), which is a set of rules, conventions, and standards that stipulate how telemetry data is exchanged, ensuring telemetry data is encrypted for transmission reliably with high throughput. Additionally, OTLP is natively supported by the Elastic Stack. This means that if you are using an OTel agent or collector, your application’s trace data or metrics can be sent directly to the Elastic Stack.

With OTel, you can instrument applications using a standard telemetry format, integrate various OTel libraries into your applications and infrastructure, as well as leverage its user experience monitoring tools to adapt your observability solution.

Refer to the OTel documentation for more information.

OTel components

OpenTelemetry consists of three components: agents, collectors, and exporters. Click on each tab to find out more.

Instrumenting OTel for Java

OTel supports instrumentation for multiple languages and you can select the language API and SDK suitable for your application.

In this guide, we focus on instrumentating for Java.

1. From the opentelemetry-java-instrumentation repository, download the opentelemetry-javaagent.jar, which contains the OTel agent and relevant instrumentation libraries. You can place the JAR file in your preferred directory.

2. Open a Terminal window and run either one of these commands:

   • Include the OTel attributes directly in the startup command:

       java -javaagent:/path/to/opentelemetry-javaagent.jar \
           -Dotel.service.name=my-java-app \
           -Dotel.traces.exporter=otlp \
           -Dotel.exporter.otlp.endpoint=<ELASTIC_APM_SERVER_URL> \
           -Dotel.exporter.otlp.headers="Authorization=Bearer <your-api-token>" \
           -jar my-java-app.jarCopy to clipboardErrorCopied

   • Export OTel settings as environment variables:

       export OTEL_EXPORTER_OTLP_ENDPOINT=<ELASTIC_APM_SERVER_URL>
       export OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer <your-api-token>
       export JAVA_TOOL_OPTIONS="-javaagent:path/to/opentelemetry-javaagent.jar"
       export OTEL_SERVICE_NAME="your-service-name"
       java -jar myapp.jarCopy to clipboardErrorCopied

     Note: Change your-service-name and myapp.jar accordingly.

The Elastic APM server URL and secret token can be obtained here:

Note: You will need to update the your-api-token and ELASTIC_APM_SERVER_URL variables accordingly. The ELASTIC_APM_SERVER_URL should be your VPCE endpoint, e.g. https://xxxxxxxxxxxxxxxxxx.apm.vpce.ap-southeast-1.aws.elastic-cloud.com:443.

(Optional) Set up OTel collector

1. Install the OTel collector by referring to How to install collector.

2. For manual Linux installation, run these commands to download the file containing the binary and install it on your machine:

    curl --proto '=https' --tlsv1.2 -fOL https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.100.0/otelcol_0.100.0_linux_amd64.tar.gz
    tar -xvf otelcol_0.100.0_linux_amd64.tar.gzCopy to clipboardErrorCopied

3. Update your project’s collector.yaml file with the following configurations to connect your OpenTelemetry collector instances to Elastic:

    receivers:
        otlp:
            protocols:
            http:
                endpoint: "localhost:4317"
        
    exporters:
        logging:
            loglevel: warn
        otlp/elastic:
            endpoint: "<ELASTIC_APM_SERVER_URL>"
            headers:
                Authorization: "Bearer <ELASTIC_APM_SECRET_TOKEN>"
        
    processors:
        memory_limiter:
            check_interval: 1s
            limit_mib: 2000
        batch:
        
    service:
        pipelines:
            traces:
                receivers: [otlp]
                exporters: [logging, otlp/elastic]
            metrics:
                receivers: [otlp]
                exporters: [logging, otlp/elastic]
            logs:
                receivers: [otlp]
                exporters: [logging, otlp/elastic]Copy to clipboardErrorCopied

4. In this option, by default the OTel Java agent uses OTLP exporter configured to send data to OTel collector at http://localhost:4317.
   
   You can start the application with one of these commands:

   • Include the OTel attributes directly in the startup command:

       java -javaagent:path/to/opentelemetry-javaagent.jar \
       -Dotel.resource.attributes=service.name=your-service-name \
       -Dotel.traces.exporter=otlp \
       -jar myapp.jarCopy to clipboardErrorCopied

   • Export OTel settings as environment variables:

       export JAVA_TOOL_OPTIONS="-javaagent:path/to/opentelemetry-javaagent.jar"
       export OTEL_EXPORTER_OTLP_ENDPOINT=http://<otel-collector-url>:4317
       export OTEL_SERVICE_NAME="your-service-name"
       export OTEL_TRACES_EXPORTER=otlp
       java -jar myapp.jarCopy to clipboardErrorCopied