Langfuse 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 traces that Langfuse turns into its observations: generations, embeddings, tool calls, agents, and chains, with their inputs, outputs, token usage, and costs.

Langfuse ingests the OpenTelemetry Semantic Conventions for Generative AI, so the langfuse flavor builds on the OpenTelemetry flavor and only adds what Langfuse needs on top of it.

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

The OpenTelemetry Semantic Conventions for Generative AI 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 langfuse:

YAML
Properties

arconia:
  observations:
    conventions:
      opentelemetry:
        ai:
          flavor: langfuse

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

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 Langfuse Dev Service to spin up a local Langfuse instance automatically. Add the Dev Service dependency to your project:

Gradle
Maven

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

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

When the Dev Service is active, Arconia configures OpenTelemetry automatically to send the traces to Langfuse, authenticated with the API keys of the Langfuse project. No additional OTLP configuration is needed for local development.

Langfuse Cloud

To send traces to Langfuse Cloud or to your own Langfuse deployment, configure the OTLP exporter with the endpoint of your Langfuse instance and the API keys of your project, encoded as base64(<public-key>:<secret-key>) in a LANGFUSE_AUTH environment variable:

YAML
Properties

arconia:
  otel:
    exporter:
      otlp:
        endpoint: https://cloud.langfuse.com/api/public/otel
        headers:
          Authorization: Basic ${LANGFUSE_AUTH}
          x-langfuse-ingestion-version: 4

arconia.otel.exporter.otlp.endpoint=https://cloud.langfuse.com/api/public/otel
arconia.otel.exporter.otlp.headers[Authorization]=Basic ${LANGFUSE_AUTH}
arconia.otel.exporter.otlp.headers[x-langfuse-ingestion-version]=4

For the US region of Langfuse Cloud, use https://us.cloud.langfuse.com/api/public/otel as the endpoint. Langfuse requires the x-langfuse-ingestion-version header from OpenTelemetry exporters.

Alternatively, you can use the standard OpenTelemetry environment variables:

OTEL_EXPORTER_OTLP_ENDPOINT=https://cloud.langfuse.com/api/public/otel
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic <base64-encoded-api-keys>,x-langfuse-ingestion-version=4"

Since Langfuse supports only traces via OTLP with the HTTP/Protobuf protocol, 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 langfuse flavor records the same attributes as the OpenTelemetry flavor, which Langfuse maps to its observations:

Chat model calls become generations, with the model, its parameters, the token usage, and the input and output messages. Langfuse computes their costs from the model and the token usage.
Embedding model calls become embeddings, and image model calls become generations.
Tool executions become tool calls, with their arguments and result.
Chat client calls become agents, grouped into a Langfuse session by the conversation ID of the chat memory.
Advisors become chains, which Langfuse doesn’t derive from the OpenTelemetry Semantic Conventions on its own.

The input and output messages are always recorded as span attributes, since Langfuse accepts traces only.

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