Getting Started with Observability Kit

Step-by-step guide on how to use Observability Kit in an application.

To use Observability Kit, you’ll have to create a Hilla application, as well as download and configure the Kit. Then you’ll have to setup an infrastructure and a frontend package. Once you’ve done all of that, you can run the application. The sections that follow explain these steps.

Create a Hilla Application

You can create a Hilla application by entering the following from the command-line:

npx @hilla/cli init <your-project-name>

Download & Configure

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

Starter Dependency

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


The starter includes a Hilla endpoint. To include and activate the endpoint, add the following configuration to your hilla-engine-plugin.



The Observability Kit Agent is based on the OpenTelemetry standard and is packaged as a .jar file. The Agent cannot be used as a dependency. It must be downloaded separately.

To start, download the Agent by clicking on the button here:

Once the Agent has been downloaded 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 and metrics are sent to Prometheus. To do this, create an file in the project directory with the following content:


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.

Jaeger is a tool for collecting traces. Download it by clicking on the button here:

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:


Prometheus is a tool for collecting metrics. Click on the button here to download it:

When finished downloading, extract the contents of the downloaded archive (i.e., tar.gz) file.

Create a Prometheus configuration with a scraper that reads metrics data from the OpenTelemetry exporter:

  scrape_interval: 15s # Default is every 1 minute.

  - job_name: 'opentelemetry'
    # metrics_path defaults to '/metrics'
    # scheme defaults to 'http'.
      - 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:

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

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

Setup Frontend Package

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:

npm install @hilla/observability-kit-client

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

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


Run the Application

You’re now ready to run your application. Create a production build by executing the following from the command-line:

mvnw package -Pproduction

Next, 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:

java -javaagent:PATH/TO/vaadin-opentelemetry-javaagent-VERSION.jar \
     -Dotel.javaagent.configuration-file=PATH/TO/ \
     -jar myapp.jar
Replace Placeholder Paths & Version
Remember to correct the path to the file, as well as the path and version of the Agent .jar file.