Monitor Apache Tomcat with OpenTelemetry
Using OpenTelemetry with Tomcat, you can instrument your Java web applications running on Tomcat to collect telemetry data and gain insights into their performance. This instrumentation can help you monitor requests, traces, and other metrics to troubleshoot issues, optimize performance, and ensure the reliability of your applications.
What is OpenTelemetry?
OpenTelemetry is an open source and vendor-neutral API for OpenTelemetry tracing, logs, and metrics.
OpenTelemetry provides a set of APIs, libraries, and instrumentation tools to instrument applications and collect data about their behavior and performance.
The goal of OpenTelemetry is to provide a standardized and vendor agnostic way to instrument applications for observability, for example, many open source tracing tools already support OpenTelemetry.
OpenTelemetry Java Agent
OpenTelemetry Java Agent is a powerful tool for automatically instrumenting Java applications to collect telemetry data, such as traces and metrics, without requiring code changes. It's an alternative to manual instrumentation and is particularly useful for instrumenting third-party libraries or applications where you don't have direct access to the source code.
You can download the OpenTelemetry Java Agent from the official GitHub releases page:
wget https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar
The OpenTelemetry Java Agent will automatically instrument your application and collect telemetry data. You can configure the agent to export this data to various distributed tracing tools such as Uptrace, OpenTelemetry Collector, Jaeger etc.
Configuring Tomcat and OpenTelemetry
To customize Apache Tomcat, you can use the setenv.sh script that allows you to set environment variables and configure Java Virtual Machine (JVM) options for your Tomcat instance. This script is not included by default but can be created in the Tomcat's bin directory.
Create a new file named setenv.sh in the Tomcat's bin directory with the following content:
export CATALINA_OPTS="$CATALINA_OPTS -javaagent:/path/to/opentelemetry-javaagent.jar"
export OTEL_RESOURCE_ATTRIBUTES=service.name=myservice,service.version=1.0.0
export OTEL_TRACES_EXPORTER=otlp
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_COMPRESSION=gzip
export OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp.uptrace.dev:4317
export OTEL_EXPORTER_OTLP_HEADERS="uptrace-dsn=https://token@api.uptrace.dev/project_id"
export OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=DELTA
export OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION=BASE2_EXPONENTIAL_BUCKET_HISTOGRAM
export CATALINA_OPTS="$CATALINA_OPTS -javaagent:/path/to/opentelemetry-javaagent.jar"
export OTEL_RESOURCE_ATTRIBUTES=service.name=myservice,service.version=1.0.0
export OTEL_TRACES_EXPORTER=otlp
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_COMPRESSION=gzip
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:14317
export OTEL_EXPORTER_OTLP_HEADERS="uptrace-dsn=http://project2_secret_token@localhost:14318?grpc=14317"
export OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=DELTA
export OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION=BASE2_EXPONENTIAL_BUCKET_HISTOGRAM
Ensure that the setenv.sh script is executable. You can do this by running the following command in the bin directory:
chmod +x setenv.sh
To apply the changes, you'll need to restart your Tomcat server. Use the shutdown.sh script to stop Tomcat and then the startup.sh script to start it again:
./shutdown.sh
./startup.sh
You can verify that your environment variables and JVM options are set correctly by checking the Tomcat logs or using utilities like ps (on Unix-based systems) to inspect the running Tomcat process and its JVM options.
OpenTelemetry Backend
Once the metrics are collected and exported, you can visualize them using a compatible backend system. For example, you can use Uptrace to create dashboards that display metrics from the OpenTelemetry Collector.
Uptrace is an open source APM for OpenTelemetry that supports distributed tracing, metrics, and logs. You can use it to monitor applications and troubleshoot issues.
Uptrace comes with an intuitive query builder, rich dashboards, alerting rules, notifications, and integrations for most languages and frameworks.
Uptrace can process billions of spans and metrics on a single server and allows you to monitor your applications at 10x lower cost.
In just a few minutes, you can try Uptrace by visiting the cloud demo (no login required) or running it locally with Docker. The source code is available on GitHub.
What's next?
Next, you can learn more about configuring OpenTelemetry Collector. To start using OpenTelemetry and Uptrace, see Getting started with Uptrace.
