Docs

Docs

Configuring Observability Kit

How to configure Observability Kit and what are its default settings.

Instrumentation can be configured in the agent.properties file that’s used with the Java agent.

Service Configuration

The service attributes are used to differentiate traces from services or applications which might have many instances running simultaneously, such as horizontally scaled services.

The service attributes are as follows:

service.name

is an attribute that’s used to distinguish a service by name. The default value is vaadin — the only attribute with a default value. It’s also the only one required.

service.namespace

helps to distinguish a group of services.

service.instance.id

helps to distinguish instances of the same service that exist simultaneously. It must be unique for each instance of the same service.namespace, service.name pair.

service.version

is the semantic versioning string of the service version.

The service.name attribute is configured using the otel.service.name property, either in the agent.properties configuration file as a system property, or as an environment variable.

Add the following line to the agent.properties file:

Source code
properties
otel.service.name=myapp
properties
terminal
terminal
terminal
terminal

Other service attributes are configured using the otel.resource.attributes property, either in the agent.properties configuration file as a system property, or as en environment variable. Multiple attributes are separated by commas.

Add the following line to the agent.properties file:

Source code
properties
otel.resource.attributes=service.namespace=myservices,service.instance.id=myapp-eu
properties
terminal
terminal
terminal
terminal

For more information about service configuration, see the OpenTelemetry documentation.

Default OpenTelemetry Instrumentation

The custom distribution disables default OpenTelemetry instrumentation for Vaadin and servlets.

The default instrumentation is disabled because logging all requests for a single-page application isn’t helpful — although it does generate plenty of data. It was disabled to have control over which requests generate a trace.

The jetty, servlet, and tomcat instrumentation modules are disabled by default. To enable any of them, add the following line to the agent.properties file:

Source code
properties
otel.instrumentation.${instrumentationName}.enabled=true

Frontend Observability Configuration

Frontend observability is enabled by default, with all the client-side instrumentation active. The configuration can be tuned statically by editing the agent.properties file, or by providing environment variables or system properties.

With static configuration, the same settings are applied to all UI instances. Changes to the configuration require a server restart.

Frontend Observability Static Configuration

Static frontend observability configuration can be provided by adding entries to the agent.properties file or with environment variables or system properties, as mentioned earlier.

The following properties can be used to tune frontend instrumentation:

Property Name Description Default Value

otel.instrumentation.vaadin.frontend.enabled

Enables or disables all frontend instrumentation.

true

otel.instrumentation.vaadin.frontend.document-load

Enables or disables the Document Load instrumentation.

true

otel.instrumentation.vaadin.frontend.user-interaction

Enables or disables the User Interaction instrumentation.

true

otel.instrumentation.vaadin.frontend.xml-http-request

Enables or disables the XML HTTP Request instrumentation.

true

otel.instrumentation.vaadin.frontend.long-task

Enables or disables the Long Task instrumentation.

true

otel.instrumentation.vaadin.frontend.frontend-error

Enables or disables the Frontend Error instrumentation.

true

For more information about the frontend instrumentation, consult the Observability Kit Reference page.

Frontend Observability Configuration (Hilla)

To enable frontend observability, you need to add the @hilla/observability-kit-client package to your package.json file. After that, you can use the init function provided by the package.

The init function requires two parameters: the export method from the ObservabilityEndpoint that comes with the starter artifact; and a list of options.

The options list has the following structure:

Source code
TypeScript
export interface TelemetryInitializationOptions {
  /** Specifies URLs to ignore */
  ignoredURLs?: readonly string[];
  /** Disables tracking of internal Vaadin/Hilla URLs */
  ignoreVaadinURLs?: boolean;
  /** Frontend-specific `service.instance.id` attribute */
  instanceId?: string;
  /** Frontend-specific `service.name` attribute */
  serviceName?: string;
  /** Frontend-specific `service.version` attribute */
  serviceVersion?: string;
  /** Enables or disables the Document Load instrumentation. */
  traceDocumentLoad?: boolean;
  /** Enables or disables the Frontend Error instrumentation. */
  traceErrors?: boolean;
  /** Enables or disables the Long Task instrumentation. */
  traceLongTask?: boolean;
  /** Enables or disables the User Interaction instrumentation. */
  traceUserInteraction?: readonly EventName[] | null;
  /** Enables or disables the XML HTTP Request instrumentation. */
  traceXmlHTTPRequest?: boolean;
}

By default, the options are set as follows:

Source code
TypeScript
const options = {
  serviceName: 'hilla',
  traceDocumentLoad: true,
  traceErrors: true,
  traceLongTask: true,
  traceUserInteraction: ['click'],
  traceXmlHTTPRequest: true,
};

Updated –