Observability Kit Reference
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
Navigation
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 |
---|---|
| Whether the navigation was a result of a forwarding request. |
| The route that was navigated to. |
| 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 |
---|---|
| The tag name of the element that was the source of the event. |
| The type of the event. |
| The simple Java class name of the UI’s currently active view, for example |
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 |
---|---|
| The property that was synchronized. |
| The tag name of the element that was the source of the event. |
| The simple Java class name of the UI’s currently active view.
For example, |
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 |
---|---|
| The signature of the method that was called. |
| 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 |
---|---|
| The requested amount of items to load. |
| The offset from where to start loading items. |
| 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 |
---|---|
| The host name that triggered the request. Set on all traces and root spans. Can be used to filter traces by host name. |
| 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. |
| 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. |
| The Flow version used by the application. Set on all traces and root spans. |
| 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. |
| 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 |
---|---|
| For static file requests, this contains the requested file. |
| The version of Vaadin Flow that’s being used, for example, 23.1.6. |
| The type of request, for example, |
| For a successful static file request, this contains "Up to date". |
Navigation Attributes
Navigation spans have the following attributes. For example, "Navigate: /index". They provide context for the cause of the navigation.
Attribute | Description |
---|---|
| Whether the navigation event is the result of a |
| The requested navigation case, for example, "/index". |
| The type of user interaction that triggered the navigation event, for example, |
View Attributes
These are attributes of spans related to a Vaadin view.
Attribute | Description |
---|---|
| When a component is being rendered, this shows the component class name. |
| When an element’s properties are synced from the client, this shows the property that’s affected. |
| The corresponding HTML tag for the element related to the span. |
| When an element is being attached, this shows the target element to which it’s being attached. |
| The type of event that has been fired by a Vaadin component. This is discussed further in Event Types. |
| For an |
| This contains the related view class name. |
| This contains the service URL of a web component. |
Other Attributes
Attribute | Description |
---|---|
| When a server event is handled, this shows the method that was called. |
| When data is being fetched, this contains the result limit, meaning, the number of rows to be returned. |
| When data is being fetched, this contains the result offset, meaning, the number of rows to skip. |
| 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 | The event doesn’t contain the new value. |
invalid-changed | Fired when the | The event doesn’t contain the new value. |
opened-changed | Fired when the | Check the |
checked-changed | Fired when the | The event doesn’t contain the new value. |
selected-items-changed | Fired when the | 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 |
---|---|---|
| Gauge | The number of open sessions. |
| Histogram | Records the duration of individual sessions. |
| Gauge | The number of current UIs managed by the application. |
Database Connection Pool Metrics
Metric | Type | Description |
---|---|---|
| Histogram | The time it took to create a new connection. |
| Gauge | The minimum number of idle connections allowed. |
| Gauge | The maximum number of connections allowed. |
| Gauge | The number of pending requests for an open connection, cumulative for the entire pool. |
| Histogram | The time between borrowing a connection and returning it to the pool. |
| Histogram | The time it took to get an open connection from the pool. |
JVM Metrics
Metric | Type | Description |
---|---|---|
| Gauge | The number of buffers in the pool. |
| Gauge | Total capacity of the buffers in this pool, in bytes. |
| Gauge | Memory that the Java virtual machine is using for this buffer pool, in bytes |
| Gauge | Number of classes currently loaded. |
| Counter | Number of classes loaded since JVM start. |
| Counter | Number of classes unloaded since JVM start. |
| Gauge | Recent CPU usage for the process. |
| Gauge | Average CPU load of the whole system for the last minute. |
| Gauge | Recent CPU usage for the whole system. |
| Gauge | Measure of memory committed, in bytes. |
| Gauge | Measure of initial memory requested, in bytes. |
| Gauge | Measure of max obtainable memory, in bytes. |
| Gauge | Measure of memory used, in bytes. |
| Gauge | Number of executing threads. |