Documentation

Documentation

Observability Kit Reference

Details on traces, metrics that Observability Kit provides, and their attributes.

Observability Kit is a custom Java agent based on the OpenTelemetry standard, with preconfigured instrumentation for Vaadin Flow applications.

A Java agent is a special set of classes which, by using the Java Instrumentation API, can intercept applications running on the JVM and inject code to provide more functionality.

OpenTelemetry is an emerging standard for generating, collecting and exporting telemetry data, such as traces, metrics, and logs. It’s supported by various tools and vendors. Vaadin tests and supports integration with a specific selection of vendors. Check the documentation for your preferred observability platform to learn how to use traces and spans.

Caution
New Standard
Observability Kit should work with any vendor that supports the OpenTelemetry standard. However, support from specific vendors may still be limited or incomplete.

Observability Kit builds on the automatic instrumentation provided by OpenTelemetry by implementing instrumentation on Vaadin-specific classes. This provides plenty of framework-specific details that can be used to identify issues, track performance, or observe user behavior.

Traces

A trace represents an operation that happened within the application. Traces consist of spans, which are nested operations that happened during the trace (e.g., method, database or API calls). Spans can contain attributes, which contain information about the operation, as well as events indicating something occurring at a specific time.

Observability Kit collects traces for all requests made against the application, and generates spans for internal framework calls, as well as external calls to databases and remote services. Observability Kit can also be customized to provide specific details about what happens in the application. See the Customization page for more on this.

Observability Kit creates traces for all Flow-specific requests against the application, and spans for framework-specific operations. It also adds span attributes that can be used to filter traces or spans, or to inspect more details about an operation.

The following sections list the most relevant traces and spans, and their attributes created by Observability Kit.

UI Requests

This creates a trace for every request that’s related to a UI, using the current view’s route template as name (e.g., /products/:productId).

Static File Requests

This creates a trace for all static files that are served, using the path as name (e.g., /static/image.png).

Dynamic Stream Requests

This creates a trace for all dynamic content streamed from a StreamResource, using the resource’s name (e.g., /dynamic/[ui]/[secret]/export.csv).

This creates a nested span whenever a navigation is triggered, either from the client or the server. The span name contains the view’s route template (e.g., Navigation: /products/:productId).

Attribute Description

vaadin.navigation.isForwardTo

Whether the navigation was a result of a forwarding request.

vaadin.navigation.route

The target route of the navigation.

vaadin.navigation.trigger

Whether the navigation was triggered from the client or the server.

Browser Events

This creates a span whenever a browser event is handled by a UI, such as click events. The span name contains a descriptive label of the element that was the source of the event, as well as the event name (e.g., Event: vaadin-button[Save] :: click).

Attribute Description

vaadin.element.tag

The tag name of the element that was the source of the event.

vaadin.event.type

The event type.

vaadin.view

The simple Java class name of the UI’s currently active view, for example ProductView.

Element Synchronization

This creates a span whenever an element property has changed and is synchronized to the server. The span name contains a descriptive label for the element, as well as the property name (e.g., Sync: vaadin-text-field[label='Customer Name'].value).

Attribute Description

vaadin.element.property

The property that was synchronized.

vaadin.element.tag

The tag name of the element that was the source of the event.

vaadin.view

The simple Java class name of the UI’s currently active view (e.g., ProductView).

Server Calls

This creates a span whenever the client calls a server method that’s annotated with ClientCallable (e.g., Invoke server method: Grid.select).

Attribute Description

vaadin.callable.method

The signature of the method that was called.

vaadin.component

The qualified class name of the component on which the method was called.

Data Provider Fetches

This creates a span whenever a component fetches data from a data provider (e.g., Data Provider Fetch).

Attribute Description

vaadin.dataprovider.limit

The requested amount of items to load.

vaadin.dataprovider.offset

The offset from where to start loading items.

vaadin.dataprovider.type

The qualified class name of the data provider class.

Common Attributes

In addition to the span-specific attributes, some spans have the following set of attributes:

Attribute Description Set On Usage

http.host

The host name that triggered the request.

All traces and root spans.

To filter traces by host name.

http.route

A view’s route template, excluding any actual parameter values, or a path for file and stream requests.

All traces and root spans.

To filter traces for specific views.

http.target

A view’s actual route, including parameter values, or a path for file and stream requests.

All traces and root spans.

To check which parameters were provided to a view through its route.

vaadin.flow.version

The Flow version used by the application.

All traces and root spans.

vaadin.request.type

The type of Flow request made against the application.

All traces and root spans.

To filter traces for a specific request type.

vaadin.session.id

The Vaadin session ID for the request.

All spans.

To filter traces for a specific session.

Spans

Each span represents a unit of work or an operation of an application. Observability Kit creates spans for Vaadin-specific operations and attaches some useful attributes and any errors that arise.

Errors

The Kit records an error when the root span and any nested spans have handled an exception. If an exception is thrown, the corresponding stack trace is in the span details.

An exception may be handled and wrapped or re-thrown, which may result in several nested span levels reporting errors. In such a case, the original exception stack trace is in the details of the lowest span in the tree with an error marked against it.

Attributes

Each span has attributes associated with it. Along with the attributes that OpenTelemetry provides, Observability Kit provides Vaadin-specific attributes that can help diagnose problems with an application.

Global Attributes

All Vaadin-specific spans contain the vaadin.session.id attribute. This uniquely identifies the Vaadin session involved.

Request Attributes

Request spans have the following attributes:

Attribute Description

http.request.file

For a static file request, this contains the requested file.

vaadin.flow.version

The version of Vaadin Flow that’s being used (e.g., 23.1.6).

vaadin.request.type

The type of request, such as heartbeat, push or uidl.

vaadin.resolution

For a successful static file request, this contains "Up to date".

The attributes for navigation spans (e.g., Navigate: /index) are listed in the table here. They provide context for the cause of the navigation.

Attribute Description

vaadin.navigation.isForwardTo

Whether the navigation event is the result of a BeforeEvent.forwardTo call.

vaadin.navigation.route

The requested navigation case (e.g., "/index").

vaadin.navigation.trigger

The type of user interaction that triggered the navigation event (e.g., CLIENT_SIDE).

View Attributes

These are attributes of spans related to a Vaadin view.

Attribute Description

vaadin.component

When a component is being rendered, this shows the component class name.

vaadin.element.property

When an element’s properties are synced from the client, this shows the property that’s affected.

vaadin.element.tag

The corresponding HTML tag for the element related to the span.

vaadin.element.target

When an element is being attached, this shows the target element to which it’s being attached.

vaadin.event.type

The type of event that has been fired by a Vaadin component. This is discussed further in Event Types.

vaadin.state.change

For an opened-changed event, this shows whether the element is being opened or closed.

vaadin.view

This contains the related view’s class name.

vaadin.webcomponent.url

This contains the service URL of a web component.

Other Attributes

The table here lists and describes other attributes.

Attribute Description

vaadin.callable.method

When a server event is handled, this shows the method that was called.

vaadin.dataprovider.limit

When data is being fetched, this contains the result limit, the number of rows to be returned.

vaadin.dataprovider.offset

When data is being fetched, this contains the result offset, the number of rows to skip.

vaadin.dataprovider.type

When data is being fetched, this contains the data provider class name.

Event Types

Components in Vaadin fire events when certain properties are changed or actions are performed. These are captured by Observability Kit instrumentation. The vaadin.event.type attribute can be found on the corresponding span. The attribute contains the type of event that was fired.

Here are some of the more important events:

Event Description Note

change

Fired when the user commits a change.

input

Fired when a field value is changed by the user.

value-changed

Fired when the value property of a component is changed. Most form components fire this event.

The event doesn’t contain the new value.

invalid-changed

Fired when the invalid property of a component is changed. Most form components fire this event.

The event doesn’t contain the new value.

opened-changed

Fired when the opened property of a component is changed. For example, a select field, accordion, or dialog.

Check the vaadin.state.change attribute to see whether the component is opening or closing.

checked-changed

Fired when the checked property of a component is changed. Checkbox and radio components fire this event.

The event doesn’t contain the new value.

selected-items-changed

Fired when the selectedItems property of a component is changed. Grid, grid pro and multi select combo box components fire this event.

The event doesn’t contain the new value.

Metrics

A metric is a measurement of a service, captured at runtime. Observability Kit captures a range of JVM metrics, such as memory usage and CPU usage. It also captures Vaadin-specific metrics, including the number of open sessions and session duration.

Application and request metrics are important indicators of availability and performance. Custom metrics can provide insights into how availability indicators impact user experience.

Metrics are categorized into three types:

Counter

A single value that only increases. An example is the number of classes loaded into the JVM.

Gauge

A single value that’s measured in intervals. The memory used by the JVM is an example of this.

Histogram

Samples observations (e.g., individual request durations) and distributes them into buckets. Each bucket counts the number of observations that fall into a specific value range. Histograms are typically used to calculate quantiles. They also provide a total sum of all observed values and the total count of observations. This allows calculations of averages.

Vaadin-Specific Metrics

Metric Type Description

vaadin.session.count

Gauge

The number of open sessions.

vaadin.session.duration

Histogram

The duration of individual sessions.

vaadin.ui.count

Gauge

The number of current UIs managed by the application.

Database Connection Pool Metrics

Metric Type Description

db.client.connections.create_time

Histogram

The time it took to create a new connection.

db.client.connections.idle.min

Gauge

The minimum number of idle connections allowed.

db.client.connections.max

Gauge

The maximum number of connections allowed.

db.client.connections.pending_requests

Gauge

The number of pending requests for an open connection, cumulative for the entire pool.

db.client.connections.use_time

Histogram

The time between borrowing a connection and returning it to the pool.

db.client.connections.wait_time

Histogram

The time it took to get an open connection from the pool.

JVM Metrics

Below is a list of JVM metrics, each one’s type, and a description of each:

Metric Type Description

process.runtime.jvm.buffer.count

Gauge

The number of buffers in the pool.

process.runtime.jvm.buffer.limit

Gauge

Total capacity of the buffers in this pool, in bytes.

process.runtime.jvm.buffer.usage

Gauge

Memory that the Java virtual machine is using for this buffer pool, in bytes.

process.runtime.jvm.classes.current_loaded

Gauge

Number of classes currently loaded.

process.runtime.jvm.classes.loaded

Counter

Number of classes loaded since JVM start.

process.runtime.jvm.classes.unloaded

Counter

Number of classes unloaded since JVM start.

process.runtime.jvm.cpu.utilization

Gauge

Recent CPU usage for the process.

process.runtime.jvm.system.cpu.load_1m

Gauge

Average CPU load of the whole system for the last minute.

process.runtime.jvm.system.cpu.utilization

Gauge

Recent CPU usage for the whole system.

process.runtime.jvm.memory.committed

Gauge

Measure of memory committed, in bytes.

process.runtime.jvm.memory.init

Gauge

Measure of initial memory requested, in bytes.

process.runtime.jvm.memory.limit

Gauge

Measure of maximum obtainable memory, in bytes.

process.runtime.jvm.memory.usage

Gauge

Measure of memory used, in bytes.

process.runtime.jvm.threads.count

Gauge

Number of executing threads.

Frontend Traces

Frontend traces provide spans with data related to operations and events initiated by the frontend application — within the browser. Observability Kit provides several instrumentation modules for observing the frontend, which are detailed below.

All frontend spans have the following attributes:

Attribute Description

component

The instrumentation module name. For example, document-load.

vaadin.frontend.id

A unique identification for the Vaadin UI associated with the span. This can be used to track spans being emitted from a particular browser tab.

Document Load

This creates spans when a page is first loaded (e.g., Frontend: documentLoad). These represent the initial document load, document fetch, and each resource fetch. Each span has the following attributes:

Attribute Description

http.url

The URL of the requested document or resource.

User Interaction

This creates spans when a user interacts with the application (e.g., Frontend: click). This includes events such as click. Each span has the following attributes:

Attribute Description

event_type

The type of user interaction event (e.g., click).

target_element

The document element that is the target of the event.

target_xpath

The XPath query for the target element.

XMLHttpRequest

This creates spans when there is an asynchronous request from the frontend (e.g., Frontend: HTTP POST) — also known as AJAX. Each span has the following attributes:

Attribute Description

http.method

The HTTP method used for the request (e.g., POST).

http.status_code

The response code.

http.url

The URL of the AJAX request.

Long Task

A long task (e.g., Frontend: longtask) is defined as any operation that takes more than 50 milliseconds to complete. This creates spans to record when an operation is considered a long task. Each span has the following attributes:

Attribute Description

longtask.duration

The duration of the task in milliseconds.

longtask.name

The browsing context or frame that can be attributed to the long task.

Frontend Error

Frontend error instrumentation (e.g., Frontend: windowError) creates spans for errors and unhandled rejection events fired on the browser. Each span has the following attributes, that may be present or not based on the type of the intercepted event:

Attribute Description

exception.type

The exception type.

exception.message

The exception message.

code.filepath

The source code file name that identifies the code unit as uniquely as possible.

code.lineno

The line number in code.filepath best representing the operation that raised the error.

http.url

Full HTTP request URL in the form scheme://host[:port]/path?query[#fragment].

Spans may also contain an event representing the error reason, with the following attributes:

Attribute Description

exception.type

The exception type.

exception.message

The exception message.

exception.stacktrace

The error stack trace as a string.