OpenLIT 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 OpenLIT Semantic Conventions instead of the default Micrometer conventions, enabling rich trace and metric visualization in platforms like OpenLIT.

Arconia provides an OpenLIT Dev Service you can use during development and testing. Check out the OpenLIT Dev Service documentation for more details.

The OpenLIT 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 openlit:

YAML
Properties

arconia:
  observations:
    conventions:
      opentelemetry:
        ai:
          flavor: openlit

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

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>

Dev Service

During development and testing, you can use the OpenLIT Dev Service to spin up a local OpenLIT instance automatically. Add the Dev Service dependency to your project:

Gradle
Maven

dependencies {
  testAndDevelopmentOnly "io.arconia:arconia-dev-services-openlit"
}

<dependency>
    <groupId>io.arconia</groupId>
    <artifactId>arconia-dev-services-openlit</artifactId>
    <scope>runtime</scope>
    <optional>true</optional>
</dependency>

The application logs will show you the URL where you can access the OpenLIT UI.

...i.a.d.s.startup  : Dev Service 'openlit' is ready in container <container-id> (ghcr.io/openlit/openlit, localhost:<port>)
...i.a.d.s.startup  : Dev Service 'openlit' links: OpenLIT UI: http://localhost:<port>

The credentials for the pre-configured demo account are: user@openlit.io (username) and openlituser (password).

When the Dev Service is active, Arconia configures OpenTelemetry automatically to export logs, metrics, and traces to OpenLIT. No additional OTLP configuration is needed for local development. The conventions come from the openlit flavor set above, which the Dev Service doesn’t select for you.

OpenLIT

To send telemetry to a hosted OpenLIT instance, configure the OTLP exporter with your endpoint and API key:

YAML
Properties

arconia:
  otel:
    exporter:
      otlp:
        endpoint: https://<your-openlit-endpoint>
        headers:
          Authorization: Bearer ${OPENLIT_API_KEY}

arconia.otel.exporter.otlp.endpoint=https://<your-openlit-endpoint>
arconia.otel.exporter.otlp.headers[Authorization]=Bearer ${OPENLIT_API_KEY}

Alternatively, you can use the standard OpenTelemetry environment variables:

OTEL_EXPORTER_OTLP_ENDPOINT=https://<your-openlit-endpoint>
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <your-openlit-api-key>"

Features

The openlit flavor records Spring AI observations for OpenLIT:

Chat model calls, with the model, the parameters, the token usage, and the input and output messages.
Embedding and image model calls.
Tool executions, with their arguments and result.
Chat client calls, with their input and output. The conversation ID of the chat memory is recorded on them and on the spans nested in them.
Advisors, following the OpenTelemetry Semantic Conventions.
Token usage metrics.

Content capturing is enabled by default, matching the behavior of the official OpenLIT 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 `openlit`)	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 `openlit`)	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 `openlit`)	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.