This recipe describes how attach an OpenTelemetry agent to Tomcat running on Linux, and configure it to send OpenTelementry data to a Distributed Application in the vFunction server.

The Distributed Application in vFunction can collect data from multiple OTEL agents, one per service of the distributed system.

Steps

1. Download the Open Telementry Java Agent and copy it to the bin directory of Tomcat (e.g., /home/user/apache-tomcat/bin or $CATALINA_HOME/bin)

2. Get the vFunction application id:

   • In the vFunction server, go to the Distributed Application (or create one if needed).

   • Go to the Learning page, open the installation instructions and go to the Java page.

   • The value of X-VF-APP is the application id (copy it).

     For example, if you see in the installation instructions:

     -Dotel.exporter.otlp.traces.headers=X-VF-APP=0664e801-7fbb-4e36-9ce8-6f18c96eb099,X-VF-TAG=<env>

     The application id is: 0664e801-7fbb-4e36-9ce8-6f18c96eb099

3. Copy the below example lines to the file setenv.sh in the bin directoy of Tomcat (if the file doesn’t exist, then create it) and modify the values of the following environment variables:

   • PROTOCOL - The protocol of the vFunction server: https or http
   • VF_SERVER_ADDRESS - The hostname of the vFunction server, e.g., vfunction.myorg.com
   • VF_APP_ID - The vFunction application id (the value obtained in the previous step)

   PATH_TO_OPENTELEMETRY_JAVAAGENT_JAR="$CATALINA_HOME/bin/opentelemetry-javaagent.jar"
   # The protocol to use for vFunction - "http" or "https"
   PROTOCOL="https" 
   # The name of the vFunction server
   VF_SERVER_ADDRESS="vfunction.myorg.com"
   # The vFunction application ID
   VF_APP_ID="0664e801-7fbb-4e36-9ce8-6f18c96eb099"
   
   VFUN_OPTS="-javaagent:$PATH_TO_OPENTELEMETRY_JAVAAGENT_JAR -Dotel.exporter.otlp.protocol=http/protobuf -Dotel.exporter.otlp.endpoint=$PROTOCOL://$VF_SERVER_ADDRESS/api/unauth/otlp -Dotel.traces.exporter=otlp -Dotel.exporter.otlp.traces.headers=X-VF-APP=$VF_APP_ID -Dotel.metrics.exporter=none -Dotel.logs.exporter=none"
   
   export CATALINA_OPTS="$VFUN_OPTS $CATALINA_OPTS"
   

4. Restart the Tomcat server (run shutdown.sh and then startup.sh).

5. Go to the Learning page in the vFunction UI of the application, close the instructions if needed, you should see an indication that the agent is connecting after a minute or so.

6. Click START to initiate the learning and run some workloads to verify data is collected.