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

Provides semantic conventions for Spring AI generative AI observations following the experimental OpenTelemetry Semantic Conventions for Generative AI.

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

Add the dedicated dependency to your project. The conventions auto-activate for Spring AI applications.

Gradle
Maven

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

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

If another Generative AI convention module is also active, Arconia fails at startup with an actionable error message. Disable the unwanted module via its enabled property.

The module supports multiple convention flavors. The default opentelemetry flavor targets standard OTel-compatible backends. For platform-specific setup using alternative conventions, refer to the dedicated pages: OpenLLMetry Semantic Conventions and LangSmith Semantic Conventions.

Features

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.

Configuration Properties

Table 3. OpenTelemetry AI Configuration Properties
Property	Default	Description
`arconia.observations.conventions.opentelemetry.ai.enabled`	`true`	Whether to enable the OpenTelemetry AI Semantic Conventions module.
`arconia.observations.conventions.opentelemetry.ai.flavor`	`opentelemetry`	The convention flavor to apply. Accepted values: `opentelemetry`, `openllmetry`, `langsmith`.
`arconia.observations.conventions.opentelemetry.ai.capture-content`	`none`	How to capture input and output message content. Accepted values: `none`, `span-attributes`, `span-events`.
`arconia.observations.conventions.opentelemetry.ai.include-tool-definitions`	`false`	Whether to include tool definitions in inference observations.
`arconia.observations.conventions.opentelemetry.ai.include-tool-call-content`	`false`	Whether to include tool content (arguments and result) in tool execution observations.