OpenInference 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 OpenInference Semantic Conventions instead of the default Micrometer conventions, enabling rich trace visualization in platforms like Arize Phoenix and Arize AX.
Arconia provides a Phoenix Dev Service you can use during development and testing. Check out the Phoenix Dev Service documentation for more details.
|
The OpenInference Semantic Conventions are still experimental, and they might change in the future. |
Getting Started
Add the Arconia OpenInference AI Semantic Conventions dependency to your project.
-
Gradle
-
Maven
dependencies {
implementation 'io.arconia:arconia-openinference-ai-semantic-conventions'
}<dependency>
<groupId>io.arconia</groupId>
<artifactId>arconia-openinference-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 |
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 Phoenix Dev Service to spin up a local Arize Phoenix instance automatically. Add the Dev Service dependency to your project:
-
Gradle
-
Maven
dependencies {
testAndDevelopmentOnly "io.arconia:arconia-dev-services-phoenix"
}<dependency>
<groupId>io.arconia</groupId>
<artifactId>arconia-dev-services-phoenix</artifactId>
<scope>runtime</scope>
<optional>true</optional>
</dependency>When the Dev Service is active, Arconia configures OpenTelemetry automatically to export traces to Phoenix based on the OpenInference Semantic Conventions. No additional OTLP configuration is needed for local development.
Arize Phoenix
| The Arconia integration guide in the Arize Phoenix documentation shows a complete example. |
To send telemetry to a hosted Arize Phoenix instance, configure the OTLP exporter with your endpoint:
-
YAML
-
Properties
arconia:
otel:
exporter:
otlp:
endpoint: https://<your-phoenix-endpoint>
headers:
Authorization: Bearer ${PHOENIX_API_KEY}arconia.otel.exporter.otlp.endpoint=https://<your-phoenix-endpoint>
arconia.otel.exporter.otlp.headers[Authorization]=Bearer ${PHOENIX_API_KEY}Alternatively, you can use the standard OpenTelemetry environment variables:
OTEL_EXPORTER_OTLP_ENDPOINT=https://<your-phoenix-endpoint>
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <your-phoenix-api-key>"You can also set the project name to control how traces are grouped in Phoenix:
-
YAML
-
Properties
arconia:
observations:
conventions:
openinference:
ai:
project-name: my-apparconia.observations.conventions.openinference.ai.project-name=my-appThe project name is the openinference.project.name resource attribute, which Arconia contributes through the resource support of the Arconia OpenTelemetry Spring Boot Starter, using the service name when the property is not set. With the Spring Boot OpenTelemetry support, set the resource attribute directly instead, otherwise Phoenix files the traces under its default project:
-
YAML
-
Properties
management:
opentelemetry:
resource-attributes:
openinference.project.name: my-appmanagement.opentelemetry.resource-attributes.openinference.project.name=my-appSince Phoenix only supports traces, you might want to disable the export of logs and metrics, or export them to a different backend:
-
YAML
-
Properties
arconia:
otel:
logs:
exporter:
type: none
metrics:
exporter:
type: nonearconia.otel.logs.exporter.type=none
arconia.otel.metrics.exporter.type=noneArize AX
| The Arconia integration guide in the Arize AX documentation shows a complete example. |
To send traces to Arize AX, configure the OTLP exporter with the Arize endpoint, the gRPC protocol, and the API key and space ID of your Arize AX space, defined in the ARIZE_API_KEY and ARIZE_SPACE_ID environment variables:
-
YAML
-
Properties
arconia:
otel:
exporter:
otlp:
protocol: grpc
endpoint: https://otlp.arize.com:443
headers:
authorization: ${ARIZE_API_KEY}
arize-space-id: ${ARIZE_SPACE_ID}
arize-interface: javaarconia.otel.exporter.otlp.protocol=grpc
arconia.otel.exporter.otlp.endpoint=https://otlp.arize.com:443
arconia.otel.exporter.otlp.headers[authorization]=${ARIZE_API_KEY}
arconia.otel.exporter.otlp.headers[arize-space-id]=${ARIZE_SPACE_ID}
arconia.otel.exporter.otlp.headers[arize-interface]=javaAlternatively, you can use the standard OpenTelemetry environment variables:
OTEL_EXPORTER_OTLP_PROTOCOL=grpc
OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp.arize.com:443
OTEL_EXPORTER_OTLP_HEADERS="authorization=<your-arize-api-key>,arize-space-id=<your-arize-space-id>,arize-interface=java"Exporting over gRPC requires additional dependencies, as described in the gRPC exporter documentation.
Arize AX files the traces under the project name configured as described for Phoenix. Since Arize AX also supports only traces, the same configuration to disable the export of logs and metrics applies.
Features
The module records OpenInference spans for:
-
Chat model calls, with the model, the parameters, the available tools, the input and output messages, and the token usage.
-
Embedding model calls, with the model and the input texts. Vectors are recorded as their dimension count, not their values.
-
Tool executions, with the arguments and the result.
-
Chat client calls, recorded as agents and grouped into sessions by the conversation ID of the chat memory.
-
Advisors, recorded as chains or guardrails.
Content is captured by default, following the OpenInference specification. Use the hide-* properties below to leave out what must not be recorded.
|
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. |
The hide-* properties follow the OpenInference configuration. They also hide any other attribute carrying the same content, such as input.value when hiding the input messages, so Arconia sometimes hides more than the reference instrumentations.
Configuration Properties
You can configure the OpenInference Semantic Conventions via configuration properties.
| Property | Default | Description |
|---|---|---|
|
|
Whether to enable the OpenInference AI Semantic Conventions module. |
|
- |
Name of the project in the OpenInference backend where to send the telemetry data. If not set, the |
|
|
Maximum length of a base64-encoded media in the messages, such as an image or a document. Longer media are redacted. |
|
|
Whether to hide all embedding text. |
|
|
Whether to hide the dimension summary recorded in place of embedding vectors, which are never recorded. |
|
|
Whether to hide the LLM invocation parameters. |
|
|
Whether to hide the definitions of the tools available to the model. They are also hidden when hiding all inputs. |
|
|
Whether to hide all inputs, including the input messages, the tool definitions, and the embedding text. |
|
|
Whether to hide all images from the input messages. |
|
|
Whether to hide all input messages. |
|
|
Whether to hide all texts from the input messages. |
|
|
Whether to hide all outputs, including the output messages and the embedding vector summary. |
|
|
Whether to hide all texts from the output messages. |
|
|
Whether to hide all output messages. |
Environment Variables
Arconia supports the OpenInference Environment Variable Specification for configuring the OpenInference semantic conventions. If both the OpenInference Environment Variables and the Arconia configuration properties are set, the OpenInference Environment Variables will take precedence.
As in the OpenInference reference implementation, the boolean environment variables accept only true and false, in any case. Arconia logs a warning for any other value and ignores it, so the configuration property applies instead.
| Environment Variable | Configuration Property |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|