This page describes how to install the Observe Agent, then instrument your Java applications to send data to Observe.

Compatibility

See Supported Java libraries and frameworks for the Java compatibility matrix.

To manually instrument custom logic, refer to Manage Telemetry with SDK in the Java SDK documentation.

Get the Observe Agent

Use the Add Data portal in the product to get the Observe Agent installed in your environment.

1. From the left navigation rail, select Data & integrations > Add data.
2. In the Observe Agent section, pick your environment, then follow the instructions to create a data ingest token and install the Observe Agent.

Depending on the environment you select, you are asked to select some options for installing and configuring the Observe Agent.

3. Follow the remainder of the instructions to install the Observe Agent and verify that your data is being received.

Add the OpenTelemetry zero-code instrumentation for Java

The instrumentation is packaged as a JAR file which dynamically injects bytecode to capture telemetry from your Java applications.

Run the following command to get the JAR file:

curl -L -O https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar

Set the following environment variables. Replace the placeholders such as ${YOUR_SERVICE_NAME} with the actual information from your environment.

OTEL_SERVICE_NAME=${YOUR_SERVICE_NAME}
JAVA_TOOL_OPTIONS=-javaagent:${PATH_TO}/opentelemetry-javaagent.jar
OTEL_RESOURCE_ATTRIBUTES=deployment.environment=${YOUR_APP_ENVIRONMENT}
OTEL_EXPORTER_OTLP_ENDPOINT=http://${YOUR_OBSERVE_AGENT_ENDPOINT}:4318 

Run the following command to run your instrumented application:

java -jar /path/to/myapp.jar

Frameworks incompatible with OpenTelemetry zero-code instrumentation

This section provides instrumentation instructions for the frameworks that are not compatible with the default OTel java-agent.

Micronaut

📘

Note

Micronaut exports JVM metrics through Micrometer, which uses area/id attributes for memory pools instead of the OTel-standard jvm.memory.type/jvm.memory.pool.name. APM runtime metric views that filter on the OTel attributes will not render these metrics.

Add the tracing modules to build.gradle.kts:

implementation("io.micronaut.tracing:micronaut-tracing-opentelemetry:<version>")
implementation("io.micronaut.tracing:micronaut-tracing-opentelemetry-http:<version>")
implementation("io.micronaut.tracing:micronaut-tracing-opentelemetry-jdbc:<version>")
implementation("io.opentelemetry:opentelemetry-exporter-otlp:<version>")
implementation("io.micronaut.micrometer:micronaut-micrometer-registry-otlp:<version>")

Configure application.yml. Traces are exported via the OTel SDK exporter (gRPC on port 4317). Metrics are exported via the Micrometer OTLP registry (HTTP on port 4318):

micronaut:
  metrics:
    enabled: true
    binders:
      jvm:
        enabled: true
    export:
      otlp:
        enabled: true
        url: ${OTLP_ENDPOINT_HTTP}/v1/metrics
        step: PT30S

otel:
  traces:
    exporter: otlp
  metrics:
    exporter: otlp
  exporter:
    otlp:
      endpoint: ${OTLP_ENDPOINT}

Note that micronaut.metrics.export.otlp.url requires the HTTP endpoint with the /v1/metrics path, while otel.exporter.otlp.endpoint uses the gRPC endpoint.

For log correlation, add opentelemetry-logback-appender as a dependency and register it in logback.xml:

<appender name="OpenTelemetry"
    class="io.opentelemetry.instrumentation.logback.appender.v1_0.OpenTelemetryAppender">
    <captureExperimentalAttributes>true</captureExperimentalAttributes>
</appender>

Quarkus

Add the extension to pom.xml (version managed by the Quarkus BOM):

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-opentelemetry</artifactId>
</dependency>

Configure `application.properties

quarkus.otel.enabled=true
quarkus.otel.metrics.enabled=true
quarkus.otel.logs.enabled=true
quarkus.otel.exporter.otlp.endpoint=${OTLP_ENDPOINT}
quarkus.otel.exporter.otlp.logs.endpoint=${OTLP_ENDPOINT}
quarkus.application.name=<service-name>
quarkus.otel.resource.attributes=service.name=<service-name>
quarkus.datasource.jdbc.telemetry=true

%test.quarkus.otel.sdk.disabled=true
quarkus.test.continuous-testing=disabled

quarkus.datasource.jdbc.telemetry is false by default -- without it, no database spans are emitted. Quarkus also defaults service.version to the POM <version>. To set a custom version, declare it explicitly in quarkus.otel.resource.attributes:

quarkus.otel.resource.attributes=service.name=<service-name>,service.version=<version>

Run with the following command, no Java agent required:

./mvnw quarkus:dev

Next steps

Navigate to Traces in your Observe tenant to view traces from your application.

• Use Trace Explorer to find traces in your environment.
• Use service management to view your services and their dependencies.
• Monitor and track new deployments on your service.
• View logs associated with a trace.
• Use the APM reference to see what data is collected by APM.