Documentation

You are viewing documentation for Vaadin 23. View latest documentation

Documentation

Observability Kit Reference

Details on all the traces, metrics, and their attributes, which Observability Kit provides.

Technically, 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. As an industry-wide standard, it’s supported by various tools and vendors. Vaadin tests and supports integrations with a specific selection of vendors. Read the documentation for your preferred observability platform to learn how to use traces and spans.

Caution
OpenTelemetry is a new standard
Observability Kit should work with any vendor that supports the OpenTelemetry standard. 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, such as method, database or API calls. Spans can contain attributes which contain information about the operation, as well as events indicating something happening 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 Customization for instructions.

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

Creates a trace for every request that’s related to a UI, using the current view’s route template as name.

Example: /products/:productId

Static File Requests

Creates a trace for all static files that are served, using the path as name.

Example: /static/image.png

Dynamic Stream Requests

Creates a trace for all dynamic content streamed from a StreamResource, using the resources' name.

Example: /dynamic/[ui]/[secret]/export.csv

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.

Example: Navigation: /products/:productId

Attribute Description

vaadin.navigation.isForwardTo

Whether the navigation was a result of a forwarding request.

vaadin.navigation.route

The route that was navigated to.

vaadin.navigation.trigger

Whether the navigation was triggered from the client or server.

Browser Events

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.

Example: 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 type of the event.

vaadin.view

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

Element Synchronization

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.

Example: 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. For example, ProductView.

Server Calls

Creates a span whenever the client calls a server method that’s annotated with ClientCallable.

Example: 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

Creates a span whenever a component fetches data from a data provider.

Example: 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

http.host

The host name that triggered the request. Set on all traces and root spans. Can be used 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. Set on all traces and root spans. Can be used to filter traces for specific views.

http.target

A view’s actual route, including parameter values, or a path for file and stream requests. Set on all traces and root spans. Can be used to check which parameters were provided to a view through its route.

vaadin.flow.version

The Flow version used by the application. Set on all traces and root spans.

vaadin.request.type

The type of Flow request made against the application. Set on all traces and root spans. Can be used to filter traces for a specific request type.

vaadin.session.id

The Vaadin session ID for the request. Set on all spans. Can be used 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

An error is recorded against the root span and any nested spans that 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 an error. In this 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 may help you diagnose application problems.

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 static file requests, this contains the requested file.

vaadin.flow.version

The version of Vaadin Flow that’s being used, for example, 23.1.6.

vaadin.request.type

The type of request, for example, heartbeat, push or uidl.

vaadin.resolution

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

Navigation spans have the following attributes. For example, "Navigate: /index". 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, for example, "/index".

vaadin.navigation.trigger

The type of user interaction that triggered the navigation event, for example, 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 class name.

vaadin.webcomponent.url

This contains the service URL of a web component.

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, meaning, the number of rows to be returned.

vaadin.dataprovider.offset

When data is being fetched, this contains the result offset, meaning, 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, as well as Vaadin-specific metrics, such as 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. For example, the number of classes loaded into the JVM.

Gauge

A single value that’s measured in intervals. For example, the memory used by the JVM.

Histogram

Samples observations, like 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

Records 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

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 max 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.