OpenTelemetry Semantic Conventions

The Spring portfolio provides built-in instrumentation based on the Micrometer APIs. Arconia lets you configure your applications to export telemetry data adopting the OpenTelemetry Semantic Conventions instead of the default Micrometer conventions.

OpenTelemetry Semantic Conventions are the standard for cloud-native observability and are supported by a wide range of backends, from on-premises to cloud solutions. Arconia provides Dev Services for OpenTelemetry backends you can use during development and testing. Check out the Dev Services documentation for more details.

Getting Started

Add the Arconia OpenTelemetry Semantic Conventions dependency to your project. The module auto-activates when present on the classpath.

Gradle
Maven

dependencies {
  implementation 'io.arconia:arconia-opentelemetry-semantic-conventions'
}

<dependency>
    <groupId>io.arconia</groupId>
    <artifactId>arconia-opentelemetry-semantic-conventions</artifactId>
</dependency>

Your application also needs OpenTelemetry configured for traces and metrics export. The recommended approach is to use the Arconia OpenTelemetry Spring Boot Starter:

Gradle
Maven

dependencies {
  implementation 'io.arconia:arconia-spring-boot-starter-opentelemetry'
}

<dependency>
    <groupId>io.arconia</groupId>
    <artifactId>arconia-spring-boot-starter-opentelemetry</artifactId>
</dependency>

If you use one of the available OpenTelemetry Dev Services during development or testing, Arconia will configure OpenTelemetry automatically to export logs, metrics, and traces to the specific service based on the OpenTelemetry Semantic Conventions.

JVM

Provides semantic conventions for JVM metrics, following the stable OpenTelemetry Semantic Conventions for JVM specification:

Memory metrics
Thread metrics
Class loader metrics
CPU/processor metrics.

Semantic Conventions for JVM are based on the support provided by the Micrometer Metrics project, extended by Arconia to support additional stable conventions.

Table 1. JVM Configuration Properties
Property	Default	Description
`arconia.observations.conventions.opentelemetry.jvm.enabled`	`true`	Whether to enable JVM semantic conventions.

HTTP Server

Activated when the application is a servlet-based web application. Provides semantic conventions for HTTP server request observations, following the stable OpenTelemetry Semantic Conventions for HTTP specification.

Semantic Conventions for HTTP Server are based on the support provided by the Spring Framework project, extended by Arconia to support additional stable conventions.

Table 2. HTTP Configuration Properties
Property	Default	Description
`arconia.observations.conventions.opentelemetry.http.enabled`	`true`	Whether to enable HTTP semantic conventions.
`arconia.observations.conventions.opentelemetry.http.include-url-query`	`false`	Whether to include the URL query string in the HTTP server observations. Disabled by default due to potential PII sensitivity.

Database

Activated when the Datasource Micrometer dependencies are added to the project. They automatically instrument all DataSource beans in your Spring Boot application, generating metrics and traces for database queries executed via JDBC following the stable OpenTelemetry Semantic Conventions for Database. Arconia manages the versions of the dependencies for you.

Gradle
Maven

dependencies {
  implementation 'net.ttddyy.observation:datasource-micrometer-spring-boot'
  implementation 'net.ttddyy.observation:datasource-micrometer-opentelemetry'
}

<dependency>
    <groupId>net.ttddyy.observation</groupId>
    <artifactId>datasource-micrometer-spring-boot</artifactId>
</dependency>
<dependency>
    <groupId>net.ttddyy.observation</groupId>
    <artifactId>datasource-micrometer-opentelemetry</artifactId>
</dependency>

Refer to the Datasource Micrometer documentation for configuration options and more details.

Generative AI

The OpenTelemetry Semantic Conventions for Generative AI are still experimental, and they might change in the future.

Activated when Spring AI is on the classpath. Provides semantic conventions for generative AI observations, following the experimental OpenTelemetry Semantic Conventions for Generative AI specification:

Chat model spans with full parameter tracking (e.g., temperature, max tokens, penalties, stop sequences).
Embedding model spans with dimension tracking.
Tool execution spans.
Chat client observations (including conversation ID tracking via chat memory).
Token usage metrics.
Input/output message content, captured as span attributes or span events.

Content capturing is opt-in due to potential PII sensitivity.

Table 3. Generative AI Configuration Properties
Property	Default	Description
`arconia.observations.conventions.opentelemetry.generative-ai.enabled`	`true`	Whether to enable Generative AI semantic conventions.

Inference

Table 4. Generative AI Inference Configuration Properties
Property	Default	Description
`arconia.observations.conventions.opentelemetry.generative-ai.inference.capture-content`	`none`	How to capture input and output message content. Disabled by default due to potential PII sensitivity. Accepted values: `none`, `span-attributes`, `span-events`.
`arconia.observations.conventions.opentelemetry.generative-ai.inference.include-tool-definitions`	`false`	Whether to include tool definitions in inference observations. Disabled by default due to potential size issues.

Tool Execution

Table 5. Generative AI Tool Execution Configuration Properties
Property	Default	Description
`arconia.observations.conventions.opentelemetry.generative-ai.tool-execution.include-content`	`false`	Whether to include tool content (arguments and result) in tool execution observations. Disabled by default due to potential PII sensitivity.