Spring Boot OpenTelemetry Instrumentation

For Java Springboot application deployed on Kubernetes, you can auto-instrument the traces using Kubernetes OpenTelemetry Operator.

An OpenTelemetry Operator is a Kubernetes Operator that manages OpenTelemetry Collectors and auto-instrumentation of workloads. It basically simplifies the deployment and management of OpenTelemetry in a Kubernetes environment.

The OpenTelemetry Operator provides two Custom Resource Definitions (CRDs):

• OpenTelemetryCollector
• Instrumentation

The OpenTelemetryCollector CRD allows you to deploy and manage OpenTelemetry Collectors in your Kubernetes cluster.

The Instrumentation CRD allows you to configure and inject OpenTelemetry auto-instrumentation libraries into your workloads.

Here are the steps you need to follow to auto-instrument Springboot application using OTel Operator:

Step 1: Install cert-manager

Run the following commands to apply cert manager.

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.16.1/cert-manager.yaml

kubectl wait --for=condition=Available deployments/cert-manager -n cert-manager

Step 2: Install OpenTelemetry Operator

To install the operator in the existing K8s cluster, run the following command:

kubectl apply -f https://github.com/open-telemetry/opentelemetry-operator/releases/download/v0.116.0/opentelemetry-operator.yaml

Installing the OpenTelemetry Operator sets up the necessary components and configurations to enable the observability and monitoring of applications running in the cluster.

Step 3: Setup the OpenTelemetry Collector instance

Once the opentelemetry-operator has been deployed, you can proceed with the creation of the OpenTelemetry Collector (otelcol) instance. The OpenTelemetry Collector collects, processes, and exports telemetry data.

There are different deployment modes for the OpenTelemetryCollector, and you can specify them in the spec.mode section of the custom resource. The available deployment modes are:

• Daemonset
• Sidecar
• StatefulSet
• Deployment (default mode)

The default method - the Deployment mode, will be used here.

To create a simple instance of the OpenTelemetry Collector, create a file otel-collector.yaml with the following contents:

apiVersion: opentelemetry.io/v1alpha1
kind: OpenTelemetryCollector
metadata:
  name: otel-collector
spec:
  mode: deployment
  config: |
    receivers:
      otlp:
        protocols:
          grpc:
            endpoint: 0.0.0.0:4317
          http:
            endpoint: 0.0.0.0:4318
    processors:
      batch: {}
      resource/env:
        attributes:
        - key: deployment.environment
          value: prod # can be dev, prod, staging etc. based on your environment
          action: upsert
    exporters:
      debug: {}
      otlp:
        endpoint: "ingest.<region>.signoz.cloud:443" # replace <region> with your region of SigNoz Cloud
        tls:
          insecure: false
        headers:
          "signoz-ingestion-key": "<your-ingestion-key>" # Obtain from https://{your-signoz-tenant-url}/settings/ingestion-settings
    service:
      pipelines:
        traces:
          receivers: [otlp]
          processors: [batch, resource/env]
          exporters: [otlp]

• Set the <region> to match your SigNoz Cloud region
• Replace <your-ingestion-key> with your SigNoz ingestion key

Apply the above yaml file using the following command:

kubectl apply -f otel-collector.yaml

Step 4: Setup the Instrumentation instance

Once the OpenTelemetry Collector instance has been deployed, the next step will be to create an instrumentation instance, which will be responsible for sending OTLP data to the OTel Collector.

Create a file instrumentation.yaml with the following contents:

apiVersion: opentelemetry.io/v1alpha1
kind: Instrumentation
metadata:
  name: traces-instrumentation
spec:
  exporter:
    endpoint: https://ingest.{region}.signoz.cloud:443  # replace {region} with your region
  env:
    - name: OTEL_EXPORTER_OTLP_HEADERS
      value: signoz-ingestion-key="{signoz-token}"  # Obtain from https://{your-signoz-url}/settings/ingestion-settings
    - name: OTEL_EXPORTER_OTLP_INSECURE
      value: "false"
  propagators:
    - tracecontext
    - baggage
    - b3
  sampler:
    type: parentbased_traceidratio
    argument: "1"
  java:
    image: ghcr.io/open-telemetry/opentelemetry-operator/autoinstrumentation-java:latest

Apply the above instrumentation using the following command:

kubectl apply -f instrumentation.yaml

Step 5: Auto-instrument your Springboot app with OpenTelemetry

Create deployment.yaml file for your Springboot application as follows:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: spring-petclinic
spec:
  selector:
    matchLabels:
      app: spring-petclinic
  replicas: 1
  template:
    metadata:
      labels:
        app: spring-petclinic
      annotations:
        instrumentation.opentelemetry.io/inject-java: "true"
        resource.opentelemetry.io/service.name: "spring-petclinic"
    spec:
      containers:
      - name: app
        image: ghcr.io/pavolloffay/spring-petclinic:latest
        ports:
        - containerPort: 8080

Note that we have created the above deployment file for spring-petclinic Java Springboot application.

It is important to add the following annotation under spec > template > metadata > annotations:

instrumentation.opentelemetry.io/inject-java: "true"`

This helps in auto-instrumenting the traces from the Java application.

Apply the deployment using the following command:

kubectl apply -f deployment.yaml

With this, the auto-instrumentation of traces for Java Springboot application is ready.

Step 6: Running the Springboot application

In order to run the application on port 8080, run the following commands:

$ export POD_NAME=$(kubectl get pod -l app=<service-name> -o jsonpath="{.items[0].metadata.name}")  # service name is `spring-petclinic` in this case.   
$ kubectl port-forward ${POD_NAME} 8080:8080

You can now access the application on port 8080.

You can validate if your application is sending traces to SigNoz cloud by following the instructions here.

For Java Springboot application deployed on Kubernetes, you need to install OTel Collector agent in your k8s infra to collect and send traces to SigNoz Cloud. You can find the instructions to install OTel Collector agent here.

Once you have set up OTel Collector agent, you can proceed with OpenTelemetry java instrumentation by following the below steps:

1. Download otel java binary
   

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

2. Run your application
   

   java -javaagent:$PWD/opentelemetry-javaagent.jar -jar <myapp>.jar
   

   • <myapp> is the name of your application jar file
   • In case you download opentelemetry-javaagent.jar file in different directory than that of the project, replace $PWD with the path of the otel jar file.

3. Make sure to dockerise your application along with OpenTelemetry instrumentation.

You can validate if your application is sending traces to SigNoz cloud by following the instructions here.

In case you encounter an issue where all applications do not get listed in the services section then please refer to the troubleshooting section.