> Markdown version of [Jaeger & Prometheus](https://vaadin.com/docs/v24/tools/observability/integrations/jaeger-prometheus). Section index: [llms.txt](https://vaadin.com/docs/v24/tools/llms.txt)

# Jaeger & Prometheus Integration

This page contains instructions on how to set up local Jaeger and Prometheus, a simple local setup that can be used for testing with support for metrics and traces, that collects telemetry from a Vaadin application with Observability Kit.

> **Caution: Not Production-Ready**
>
> This setup is intended for local testing, only. It’s not ready for use in production. See the [Jaeger documentation](https://www.jaegertracing.io/) for more information on how to prepare your setup for production.

## <a id="download-run-jaeger"></a>Download & Run Jaeger

[Jaeger](https://www.jaegertracing.io/) is a tool for collecting traces. Download it by clicking on the button here:

[Download Jaeger](https://www.jaegertracing.io/download/)

Then extract the contents of the downloaded archive (i.e., the `tar.gz`) file. After you’ve done that, open a terminal to the Jaeger directory and start Jaeger:

```terminal
./jaeger-all-in-one
```

## <a id="download-run-prometheus"></a>Download & Run Prometheus

[Prometheus](https://prometheus.io/) is a tool for collecting metrics.

[Download Prometheus](https://prometheus.io/download/)

Extract the contents of the downloaded archive (i.e., the `tar.gz` file). Create a Prometheus configuration with a scraper that reads metrics data from the OpenTelemetry exporter:

config.yml

```yaml
global:
  scrape_interval: 15s # Default is every 1 minute.

scrape_configs:
  - job_name: 'opentelemetry'
    # metrics_path defaults to '/metrics'
    # scheme defaults to 'http'.
    static_configs:
      - targets: ['localhost:9464']
    # Host and port need to match the
    # OpenTelemetry prometheus exporter configuration
```

Open a terminal to the Prometheus directory and start Prometheus with the configuration file:

```terminal
./prometheus --config.file=/PATH/TO/config.yml
```

Remember to substitute the correct path to the `config.yml` file.

## <a id="configuration-file"></a>Observability Kit Configuration

Create a new properties file named `agent.properties` and add the following lines to it:

`agent.properties`

```properties
otel.traces.exporter=jaeger
otel.exporter.jaeger.endpoint=http://localhost:14250
otel.metrics.exporter=prometheus
otel.exporter.prometheus.host=0.0.0.0
otel.exporter.prometheus.port=9464
```

## <a id="running-the-application"></a>Running the Application

Run the application using the Java binary and pass the respective arguments for the Agent and configuration like so:

**JAR file**

```terminal
java -javaagent:PATH/TO/observability-kit-agent-VERSION.jar \
     -Dotel.javaagent.configuration-file=PATH/TO/agent.properties \
     -jar myapp.jar
```

Create a file, `setenv.bat` in your Tomcat installation’s `bin` folder. This script runs automatically with the startup script.

Copy the content below and paste it into that file. Be sure to change it to your particular installation’s file path. Then start Tomcat using `bin/startup.bat`.

**Tomcat (Windows)**

```terminal
set CATALINA_OPTS=%CATALINA_OPTS% -javaagent:PATH\TO\observability-kit-agent-VERSION.jar
set OTEL_JAVAAGENT_CONFIGURATION_FILE=PATH\TO\agent.properties
```

Create a file, `setenv.sh` in your Tomcat installation’s `bin` folder. This script runs automatically with the startup script. Copy the content below and paste it into that file. Be sure to change it to your particular installation’s file paths. Then start Tomcat using `bin/startup.sh`.

**Tomcat (macOS/Linux)**

```terminal
export CATALINA_OPTS="$CATALINA_OPTS -javaagent:PATH/TO/observability-kit-agent-VERSION.jar"
export OTEL_JAVAAGENT_CONFIGURATION_FILE=PATH/TO/agent.properties
```

Start Jetty and pass the respective arguments for the Java agent and the agent configuration:

**Jetty**

```terminal
java -javaagent:PATH/TO/observability-kit-agent-VERSION.jar \
     -Dotel.javaagent.configuration-file=PATH/TO/agent.properties \
     -jar /PATH/TO/jetty_home/start.jar
```

If you want to run an application with the agent through Maven for testing, set the `MAVEN_OPTS` variable as shown below. Then run your Maven goal, for example, `mvn jetty:run`.

**Maven (Windows)**

```terminal
set MAVEN_OPTS="-javaagent:PATH\TO\observability-kit-agent-VERSION.jar -Dotel.javaagent.configuration-file=PATH\TO\agent.properties"
```

If you want to run an application with the agent through Maven for testing, set the `MAVEN_OPTS` variable as shown below. Then run your Maven goal, for example, `mvn jetty:run`.

**Maven (macOS/Linux)**

```terminal
export MAVEN_OPTS="-javaagent:PATH/TO/observability-kit-agent-VERSION.jar -Dotel.javaagent.configuration-file=PATH/TO/agent.properties"
```

> **Note: Replace Placeholder Paths & Version**
>
> Remember to correct the path to the `agent.properties` file, as well as the path and version of the Agent `.jar` file.

## <a id="viewing-traces-in-jaeger"></a>Viewing Traces in Jaeger

The default address for the Jaeger user interface is `http://localhost:16686`. From there you can select your service name — **vaadin** by default — from the **Service** field and click the **Find Traces** button.

<!-- vale Vaadin.Wordiness = NO -->

The default time period to search is within the last hour. To search further back, select a time period from the **Lookback** field.

<!-- vale Vaadin.Wordiness = YES -->

The default number of results is 20. To see more results, increase the value in the **Limit Results** field.

On the right, there is now a graph of timeline versus duration. From there you can see events that are causing delays, expressed by larger circles, or errors, expressed by red circles. Clicking one of the circles opens the [trace detail page](#trace-detail).

A list of the root spans is also available. Each span shows the duration relative to the other root spans, how many nested spans it contains, and how many errors. Once again, clicking on an item opens up the trace detail page.

### <a id="trace-detail"></a>Trace Detail

The trace detail page has a tree list showing the root span and all nested spans. If any of the spans has an error, it’s be marked by a red exclamation (!) icon.

For each of the spans, you can view more details by clicking on the row. In the span details, you can expand **Tags** to view attributes for the span. Vaadin-specific attributes are detailed in the [reference page](https://vaadin.com/docs/v24/tools/observability/reference.md#span-attributes). If there has been an error, you can find any related stack traces under **Logs**.

## <a id="viewing-metrics-in-prometheus"></a>Viewing Metrics in Prometheus

The default address for the Prometheus user interfaces is `http://localhost:9090`. Enter a metric name into the search field and click **Execute**.

If you don’t know the metric name, you can use the metrics explorer, by clicking the Earth icon next to **Execute**. This provides an alphabetical list of available metrics.

To view the results as a graph, click the **Graph** tab.