Getting Started with Observability Kit

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

Create a Hilla Application
Download & Configure
Setup Infrastructure
Setup Frontend Package
Run the 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:

<dependency>
  <groupId>dev.hilla</groupId>
  <artifactId>observability-kit-starter</artifactId>
</dependency>

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

<configuration>
    <parser>
        <packages>
            <package>dev.hilla.observability</package>
        </packages>
    </parser>
</configuration>

Agent

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:

Download Observability Kit Agent

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 agent.properties file in the project directory with the following content:

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

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:

Download Jaeger

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:

./jaeger-all-in-one

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

Download Prometheus

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:

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:

./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'

init(ObservabilityEndpoint.export);

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/agent.properties \
     -jar myapp.jar

Important

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.

Docs