Java Application Instrumentation

Last Updated: 10 August, 2022

You can use the following methods for OpenTelemetry-facilitated instrumentation of a Java application:

  • (Recommended) Automatic instrumentation—This option is the fastest way to get started, but gives you less control over how the trace data is emitted. LogicMonitor provides a wizard for automatic instrumentation of Java applications. 
    Alternatively, you can automatically instrument a Java application outside your LogicMonitor portal. This requires you to attach a JAR file to your application that injects code to capture trace data from the supported libraries and frameworks. Operation names are automatically set.
    If your environment uses Kubernetes to run your Java applications, you can automatically instrument the application within your Kubernetes infrastructure.
  • Manual instrumentation—This is the only option for applications that use libraries and frameworks that are not supported by automatic instrumentation. With manual instrumentation, you write code in your application that uses the OpenTelemetry SDK to capture and emit the trace data. For more information, see Supported libraries, frameworks, application servers, and JVMs from OpenTelemetry.

Depending on your environment, you may need a combination of both automatic and manual instrumentation.

Requirements for Instrumenting a Java Application with LogicMonitor

To instrument a Java application, you must install and configure an OpenTelemetry Collector to forward trace data to your LogicMonitor portal. For more information, see OpenTelemetry Collector Installation.

Automatically Instrumenting a Java Application using the Instrumentation Wizard in LogicMonitor

Note: To automatically instrument a Java application outside your LogicMonitor portal, see OpenTelemetry’s Automatic Instrumentation documentation.

  1. Navigate to Traces > Onboarding and select Instrument Your Application.
  2. Click Select for Java, and then select Automatic (Recommended).
  3. Copy the JAR file and attach it to your application. This JAR file is a Java client library provided by OpenTelemetry.
  4. When prompted, enter the following information:
    • (Recommended) Service Namespace
      This is used to represent a grouping of services. If specified, it is added as a property to each auto-created service and a parent service is created to represent the namespace. You may find this useful for organizing applications with multiple underlying services.
    • (Required) Service Name
      This is also used as the display name for the service in your LogicMonitor portal. Special characters, including spaces, are not allowed.
    • (Recommended) Custom Tags
      These are associated with all the operations for this service. For example, you can add tags that represent the business or technical priority of the service.

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). Use these custom tags when possible to ensure that traces are shown in the context of logs, metrics, and alerts.

  1. Copy the commands that are generated based on the information you provided and run them on the server where your application is running. Ensure 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.

For more information about automatically instrumenting a Java application outside your LogicMonitor portal, see OpenTelemetry’s Automatic Instrumentation documentation.

Automatically Instrumenting a Java Application in Kubernetes

  1. Specify the javaagentflag with configuration options as environment values using JAVA_TOOL_OPTIONS similar to the following:
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"
  1. Extend your Docker image by adding 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: {}

This makes the agent JAR available to your application running in a Kubernetes pod. The dockerfile for the lm/provide-jar image may look similar to the following:

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"]

In addition, when instrumenting your Java application in your Kubernetes infrastructure, you can leverage OpenTelemetry’s operator for Kubernetes to automatically instrument your application. For more information, see Automatic Instrumentation using the OpenTelemetry Operator for Applications in Kubernetes.

Manually Instrumenting a Java Application

You can manually instrument your Java application if your application is not supported for OpenTelemetry automatic instrumentation, or if you want to customize how traces are generated by automatic instrumentation. For example, you may want to customize how operations are named. For more information about manually instrumenting your Java application, the OpenTelemetry SDK, creating and enriching traces, see OpenTelemetry’s Manual Instrumentation documentation. 

In This Article