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.

1. 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. It’s the only attribute with a default value, which is vaadin.

  • service.namespace is used to distinguish a group of services.

  • service.instance.id distinguishes instances of the same service that exist simultaneously. It must be unique for each instance of the same service.namespace and 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:

otel.service.name=myapp

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

Add the following line to the agent.properties file:

otel.resource.attributes=service.namespace=myservices,service.instance.id=myapp-eu

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

2. Default OpenTelemetry Instrumentation

The custom distribution disables default OpenTelemetry instrumentation for Vaadin and servlets. It’s 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:

otel.instrumentation.${instrumentationName}.enabled=true

3. Frontend Observability Configuration

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:

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:

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