Support Center Home


Instrumenting a Java application

There are two ways to approach OpenTelemetry-facilitated instrumentation for a Java application:

  1. (Recommended) Automatic instrumentation is the fastest way to get started, but gives you less control over how the trace data is emitted. With auto-instrumentation, you’ll attach a JAR file to your application that injects code to capture trace data from supported libraries and frameworks. Operation names are automatically set.
  2. Manual instrumentation is your only option for applications that use libraries and frameworks that are not supported by auto-instrumentation. With manual instrumentation, you’ll write code in your application that uses the OpenTelemetry SDK to capture and emit the trace data.

In the end, you may need a combination of both manual and auto-instrumentation.

Prerequisites

Automatic Instrumentation

LogicMonitor provides a configuration wizard for automatic Instrumentation of Java applications.

1. At the top right of the Traces page, select Onboarding.

2. Select Java, and confirm automatic instrumentation.

The wizard will prompt you to download the JAR file you’ll attach to your application. This JAR file is a Java client library provided by OpenTelemetry.

3. After the JAR downloads, provide the following information:

  • (Required) The name of the service you are instrumenting. This name will also be used as the display name for the service in your LogicMonitor portal. Special characters, such as spaces, are not allowed.
  • (Recommended) Custom tags which will be associated with all the operations for this service. For example, you may want to add tags that represent the business or technical priority of the service. See Note.
  • (Optional) The service namespace, which can be used to represent a grouping of services. If specified, it will be added as a property to each auto-created service and a parent service will be created to represent the namespace. You may find this useful for organizing applications with multiple underlying services.

Note: LogicMonitor requires the following custom tags to map traces to existing monitored resources: ip, resource.type (which should be set to kubernetes-pod, cloud, or host), and host.name (which should be the pod name for Kubernetes). We recommend using these custom tags when possible to ensure that traces can be shown in the context of logs, metrics, and alerts.

4. Based on what you enter in the three fields, commands for attaching the auto-instrumentation client library to your application with the correct configuration are generated. Copy and run these commands on the server where your application is running. Make sure to reference the JAR for your application at the end.

Note: If your OpenTelemetry Collector was installed on a different server, you may need to update the value of Dotel.export.otlp.endpoint from localhost to the IP of the server where the OpenTelemetry Collector is running.

Kubernetes configuration

When instrumenting your application in Kubernetes, you will need to specify the javaagent flag with configuration options as environment values using JAVA_TOOL_OPTIONS. For example:

containers:
      - name: server
        image: gcr.io/google-samples/microservices-demo/adservice:v0.2.2
        volumeMounts:
        - mountPath: /mnt/auto-trace
          name: otel-jar
        ports:
        - containerPort: 9555
        env:
        - name: PORT
          value: "9555"
        - name: JAVA_TOOL_OPTIONS
          value: "-javaagent:/mnt/auto-trace/opentelemetry-javaagent-all.jar -Dotel.resource.attributes=service.name=adservice -Dotel.traces.exporter=otlp -Dotel.exporter.otlp.endpoint=10.74.8.33:55680"

To make the agent JAR available to your application running in a Kubernetes pod, extend your Docker image and add an init container that downloads the JAR and copies it to a volume that is shared with your application container in a single pod:

initContainers:
      - name: attach-jar
        image: lm/provide-jar:v1
        volumeMounts:
        - mountPath: /mnt/shared
          name: otel-jar
      volumes:
      - name: otel-jar
        emptyDir: {}

Where the dockerfile for the lm/provide-jar image may look like:

FROM centos:7
RUN yum install -y curl
RUN curl -L "https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/download/v0.13.0/opentelemetry-javaagent-all.jar" > opentelemetry-javaagent-all.jar
RUN mkdir -p /mnt/shared
VOLUME /mnt/shared
ENTRYPOINT ["cp", "-v", "opentelemetry-javaagent-all.jar", "/mnt/shared"]

Manual instrumentation

You may need to manually instrument some or all of your Java applications if (1) you are using libraries that are not supported for the OpenTelemetry auto-instrumentation; or (2) you want to customize how operations are generated by auto-instrumentation (such as how operations are named). 

The best source of instruction for manually instrumenting your Java application is the official OpenTelemetry documentation. This documentation will guide you through instantiating the OpenTelemetry SDK and a tracer, creating traces, and enriching them.

In This Article