Getting Started with Observability Kit

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

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.

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>com.vaadin</groupId>
  <artifactId>observability-kit-starter</artifactId>
</dependency>

Agent

The Agent is based on the OpenTelemetry standard and is packaged as a .jar file. See the Observability Kit Reference 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

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:

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. For integration with other vendors, see the Integrations page.

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.

Download Prometheus

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:

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 the config.yml file.

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:

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. If you don’t have one, though, you can download an application from Vaadin Start, and create a production build with the following command:

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

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

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.

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.

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

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.

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.

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. If there has been an error, you can find any related stack traces under Logs.

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.

Docs