> Markdown version of [Getting Started](https://vaadin.com/docs/v24/tools/observability/getting-started). Section index: [llms.txt](https://vaadin.com/docs/v24/tools/llms.txt)

# Getting Started with Observability Kit

Observability is the ability to answer questions about an application and its infrastructure. The Vaadin Observability Kit can assist in implementing this ability for Flow-based applications to obtain traceable, actionable information about applications in production.

To help you get started with Observability Kit, this page covers the following topics:

- Downloading and configuring Observability Kit to export data to the infrastructure;

- Setting up an infrastructure for collecting and viewing observability data, such as traces and metrics; and

- Running a Vaadin application with Observability Kit.

## <a id="download-configure"></a>Download & Configure

Observability Kit consists of two parts: the Starter dependency and the Agent. They’re explained in these sub-sections.

### <a id="starter-dependency"></a>Starter Dependency (since V24.1)

The Starter dependency can be added to your project by adding the following to the `pom.xml` file:

`pom.xml`

```xml
<dependency>
  <groupId>com.vaadin</groupId>
  <artifactId>observability-kit-starter</artifactId>
</dependency>
```

### <a id="agent"></a>Agent

The Agent is based on the OpenTelemetry standard and is packaged as a `.jar` file. See the [Observability Kit Reference](https://vaadin.com/docs/v24/tools/observability/reference.md) documentation page for more information.

> **Important: Download the Agent JAR File**
>
> The Agent cannot be used as a dependency. It must be downloaded separately.

[Download Observability Kit Agent](https://repo1.maven.org/maven2/com/vaadin/observability-kit-agent/3.2.0/observability-kit-agent-3.2.0.jar)

Once the Agent has finished downloading to the project directory, it needs to be configured to export telemetry to one or more observability tools. In this guide, traces are exported to Jaeger; metrics are sent to Prometheus. To do this, create an `agent.properties` file in the project directory with the following content:

`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="setup-infrastructure"></a>Setup Infrastructure

This guide uses Jaeger to process traces, and Prometheus to process metrics. They both run locally and are suitable for development and testing. For integration with other vendors, see the [Integrations](https://vaadin.com/docs/v24/tools/observability/integrations.md) page.

[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
```

[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="setup-frontend-package-hilla"></a>Setup Frontend Package (Hilla)

To complete the setup process, you need to install and initialize the client-side component of the kit.

Execute the following in your terminal to install the package:

```terminal
npm install @hilla/observability-kit-client
```

Next, open the `frontend/index.ts` file and add the following code:

```typescript
import { init } from '@hilla/observability-kit-client';
import { ObservabilityEndpoint } from 'Frontend/generated/endpoints.js'

init(ObservabilityEndpoint.export);
```

## <a id="run-the-application"></a>Run the Application

You’re now ready to run your application. If you don’t have one, though, you can download an application from [Vaadin Start](https://start.vaadin.com), and create a production build with the following command:

```terminal
./mvnw package -Pproduction
```

Then run the packaged JAR file from the `target` folder:

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.