OpenLLMetry Semantic Conventions

Spring AI provides built-in instrumentation for models, tools, and agentic workflows based on the Micrometer APIs. Arconia lets you configure your Spring AI applications to export telemetry data adopting the OpenLLMetry Semantic Conventions instead of the default Micrometer conventions, enabling rich trace visualization in platforms like Traceloop.

The OpenLLMetry Semantic Conventions are still experimental, and they might change in the future.

Getting Started

Add the Arconia OpenTelemetry AI Semantic Conventions dependency to your project.

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.

Set the convention flavor to openllmetry:

YAML
Properties

arconia:
  observations:
    conventions:
      opentelemetry:
        ai:
          flavor: openllmetry

arconia.observations.conventions.opentelemetry.ai.flavor=openllmetry

Your application also needs OpenTelemetry configured to export telemetry data, using either the Arconia OpenTelemetry Spring Boot Starter or the Spring Boot OpenTelemetry partial support (spring-boot-starter-opentelemetry). The recommended approach is the Arconia OpenTelemetry Spring Boot Starter:

Gradle
Maven

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

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

Traceloop

Configure the OTLP exporter to send traces to Traceloop, making sure you defined your Traceloop API Key in a TRACELOOP_API_KEY environment variable:

YAML
Properties

arconia:
  otel:
    exporter:
      otlp:
        endpoint: https://api.traceloop.com
        headers:
          Authorization: Bearer ${TRACELOOP_API_KEY}

arconia.otel.exporter.otlp.endpoint=https://api.traceloop.com
arconia.otel.exporter.otlp.headers[Authorization]=Bearer ${TRACELOOP_API_KEY}

Alternatively, you can use the standard OpenTelemetry environment variables:

OTEL_EXPORTER_OTLP_ENDPOINT=https://api.traceloop.com
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <your-traceloop-api-key>"

Since Traceloop supports only traces, you might want to disable the export of logs and metrics:

YAML
Properties

arconia:
  otel:
    logs:
      exporter:
        type: none
    metrics:
      exporter:
        type: none

arconia.otel.logs.exporter.type=none
arconia.otel.metrics.exporter.type=none

Features

The openllmetry flavor records Spring AI observations for Traceloop:

Chat model, embedding model, and image model calls, following the OpenTelemetry Semantic Conventions for Generative AI, as the current OpenLLMetry instrumentations do.
Tool executions, with their arguments and result.
Chat client calls, recorded as Traceloop workflows with their input and output, and grouped into a Traceloop session by the conversation ID of the chat memory.
Advisors, recorded as Traceloop tasks.
Token usage, including the total and the cached input tokens.

Content capturing is enabled by default, matching the behavior of the official OpenLLMetry SDKs. Set the capture-* properties below to false to turn it off.

The captured content, such as prompts, completions, tool arguments and results, and tool definitions, can contain personal or confidential data. Review what your application sends to the models before exporting the telemetry to a shared backend, and turn the capturing off where that data must not leave the application.

Model calls, embeddings, tool executions, and chat client calls ending in an error get the error.type attribute when the error conventions of the Arconia OpenTelemetry Semantic Conventions module are also on the classpath.

Configuration Properties

Table 1. 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`, `openlit`, `openllmetry`, `langsmith`, `langfuse`.
`arconia.observations.conventions.opentelemetry.ai.capture-message-content`	`true` (when flavor is `openllmetry`)	Whether to capture the input and output messages of model calls. The default depends on the flavor: the `opentelemetry` flavor doesn’t capture them, the other flavors do.
`arconia.observations.conventions.opentelemetry.ai.capture-tool-definitions`	`true` (when flavor is `openllmetry`)	Whether to capture the definitions of the tools available to the model in model calls. The default depends on the flavor: the `opentelemetry` flavor doesn’t capture them, the other flavors do.
`arconia.observations.conventions.opentelemetry.ai.capture-tool-call-content`	`true` (when flavor is `openllmetry`)	Whether to capture the arguments and result of tool executions. The default depends on the flavor: the `opentelemetry` flavor doesn’t capture them, the other flavors do.