LangSmith 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 LangSmith Semantic Conventions instead of the default Micrometer conventions, enabling rich trace visualization in the LangSmith platform.

The LangSmith 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 langsmith:

YAML
Properties

arconia:
  observations:
    conventions:
      opentelemetry:
        ai:
          flavor: langsmith

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

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>

LangSmith

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

YAML
Properties

arconia:
  otel:
    exporter:
      otlp:
        endpoint: https://eu.api.smith.langchain.com/otel
        headers:
          x-api-key: ${LANGSMITH_API_KEY}
          Langsmith-Project: my-project

arconia.otel.exporter.otlp.endpoint=https://eu.api.smith.langchain.com/otel
arconia.otel.exporter.otlp.headers[x-api-key]=${LANGSMITH_API_KEY}
arconia.otel.exporter.otlp.headers[Langsmith-Project]=my-project

For US-hosted LangSmith, use https://api.smith.langchain.com/otel as the endpoint. The Langsmith-Project header selects the LangSmith project receiving the traces, which is default when the header is not set.

Alternatively, you can use the standard OpenTelemetry Environment Variables:

OTEL_EXPORTER_OTLP_ENDPOINT=https://eu.api.smith.langchain.com/otel
OTEL_EXPORTER_OTLP_HEADERS="x-api-key=<your-langsmith-api-key>,Langsmith-Project=my-project"

Since LangSmith 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 langsmith flavor records Spring AI observations for LangSmith:

Chat model calls, with the model, the parameters, and the token usage, including the cached input tokens.
Embedding and image model calls.
Tool executions, with their arguments and result.
Chat client calls, grouped into a LangSmith thread by the conversation ID of the chat memory.
Advisors, recorded as chains.
The input and output messages, recorded the way the LangSmith SDKs do.

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