Arconia tracing with Future AGI

About

Arconia (io.arconia, Apache-2.0) is an OpenTelemetry starter for Spring Boot. Add arconia-opentelemetry-spring-boot-starter and your application exports traces, logs and metrics over OTLP. Future AGI ingests traces only, so this recipe configures the trace exporter and turns the other two signals off.

Arconia exports what your Spring Boot application already traces, including HTTP server spans and Micrometer observations. It does not add LLM attributes. For Spring AI applications, check the Spring AI compatibility guidance before choosing a tracing integration.

This recipe uses Arconia 0.31.0 with Spring Boot 4.1.1 and Java 21, sending HTTP server traces over OTLP/HTTP to a self-hosted Future AGI collector. Arconia requires Spring Boot 4 and Java 21 or newer. See Arconia tracing and resource configuration.

1. Add the dependencies

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>4.1.1</version>
</parent>

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.arconia</groupId>
            <artifactId>arconia-bom</artifactId>
            <version>0.31.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-webmvc</artifactId>
    </dependency>
    <dependency>
        <groupId>io.arconia</groupId>
        <artifactId>arconia-opentelemetry-spring-boot-starter</artifactId>
    </dependency>
</dependencies>

Do not set a version on the starter, it comes from the BOM.

2. Set environment variables

export FI_API_KEY="YOUR_API_KEY"
export FI_SECRET_KEY="YOUR_SECRET_KEY"
export FI_PROJECT_NAME="my-service"
# Required: your reachable self-hosted collector, no trailing slash.
export FI_BASE_URL="http://localhost:14338"

Keep the keys in the environment or a secret store, not in application.yaml.

3. Configure Arconia

arconia:
  otel:
    traces:
      exporter:
        otlp:
          endpoint: ${FI_BASE_URL}/tracer/v1/traces
          compression: none
          headers:
            X-Api-Key: ${FI_API_KEY}
            X-Secret-Key: ${FI_SECRET_KEY}
    metrics:
      exporter:
        type: none
    logs:
      exporter:
        type: none
    resource:
      attributes:
        project_name: ${FI_PROJECT_NAME}
        project_type: observe

Setting	Why
endpoint	Arconia’s HTTP default is http://localhost:4318/v1/traces. Future AGI’s route is /tracer/v1/traces.
compression: none	Sends uncompressed bodies. Arconia 0.31.0 defaults to gzip; use none for this recipe.
protocol	Leave it unset. HTTP/protobuf is the default. See the warning below.
headers	Both keys are needed. One header is a failed setup.
resource.attributes.project_name	A resource attribute, not a span attribute. Arconia adds any key under arconia.otel.resource.attributes to the resource. Without it the batch is dropped.
metrics and logs exporter none	Arconia exports both over OTLP by default. Future AGI has no logs or metrics route, and log bodies can contain prompts. Never point them at /tracer/v1/traces.

4. Install the error-detail filter

Before starting the application, copy ErrorDetailRedaction.java into your application’s Java source tree. Change its package declaration to a package beneath your @SpringBootApplication, so Spring discovers its @Configuration class, or import the class explicitly with @Import(ErrorDetailRedaction.class).

Leave FI_EXPORT_ERROR_DETAILS unset or false. The class wraps the exporter and removes exception messages, stack traces and span-status descriptions before export. Without this class, plain Arconia sends raw error details. This filter does not redact arbitrary attributes added by your own instrumentation.

The complete example includes this configuration and a /hello endpoint. Use that example for the commands below, or substitute an endpoint in your own application.

5. Run it

mvn spring-boot:run
curl localhost:8080/hello

Stop the process with SIGTERM or Ctrl-C so Spring closes the context. Closing the context flushes Arconia’s batch span processor, which otherwise waits up to 5 seconds. A process killed with kill -9, or a short command-line app that calls System.exit before the context closes, loses the last batch.

Sampling: Arconia’s default strategy is parent-based-always-on, so every request is traced and management.tracing.sampling.probability is ignored. It only applies if you choose trace-id-ratio or parent-based-trace-id-ratio; a lower value then drops traces on purpose.

What is captured

One HTTP request is one trace with one SERVER span named like http get /hello. In the Observe list it appears with type unknown, no input, no output and no tokens, because it carries no fi.span.kind or LLM attributes.

Attribute	Value
Span	http get /hello, kind SERVER, status UNSET, or ERROR for a 5xx / unhandled exception
Span attributes	method, uri (the route template, for example /users/{id}), status, outcome, exception, http.url (the path only, no query string)
Event on failure	exception with exception.type only (see Privacy)
Resource	project_name, project_type, service.name, service.instance.id, telemetry.sdk.*, webengine.name, webengine.version

Other application instrumentation through Micrometer, such as @Observed or RestClient, can also produce spans.

Privacy

In the configured example’s HTTP server spans, query strings, request and response bodies, and header values are absent. Review your own instrumentation separately for sensitive data.

One thing is exported by default by Arconia: when a request fails, Micrometer records the exception on the server span with exception.message, the whole exception.stacktrace, and copies the message into the span status description. Messages often contain user input or identifiers.

The example therefore ships ErrorDetailRedaction, a small Spring configuration class that wraps the span exporter and strips those three fields before they leave the JVM. It keeps the span, its ERROR status and exception.type. Step 4 installs this mandatory class before the application runs. It is application code, Arconia has no switch for this.

Mode	How	What Future AGI stores
Default	ErrorDetailRedaction present, nothing else set	ERROR status, empty status message, exception event name and time, exception class in attrs_string.exception
Opt in to raw error text	FI_EXPORT_ERROR_DETAILS=true	The status message contains the exception message (failed: <your text>)

Spring AI

For LLM tracing, use the Spring AI compatibility guidance to choose a setup for your Spring AI version. This configuration covers Arconia-only HTTP server tracing. Combining it with traceai-spring-ai is outside this recipe; do not infer compatibility or duplicate-span behavior from this setup.

Limitations

• Spans created by Arconia alone have type unknown in Observe, with no input, output, model or tokens.
• Arconia states Spring Boot 4 and Java 21 as its minimum. This recipe targets Boot 4.1.1 only.
• Traces only. No metrics or logs in Future AGI.
• This recipe uses HTTP/protobuf only; it supplies no gRPC setup.
• OTEL_EXPORTER_OTLP_* environment variables take precedence over arconia.otel.* properties.

Troubleshooting

• No project appears and nothing is logged. Check protocol. Remove http-protobuf. Run with --debug and look for otlpHttpSpanExporter under “Did not match”.
• Traces go to localhost or another backend. OTEL_EXPORTER_OTLP_TRACES_ENDPOINT (or OTEL_EXPORTER_OTLP_ENDPOINT) overrides the YAML configuration. Unset it or set it to the same collector URL.
• Spans are in the wrong project, or dropped. project_name must be under arconia.otel.resource.attributes, not a span attribute.
• No spans for HTTP requests. Check the exporter first (the protocol warning above). The example runs with only spring-boot-starter-webmvc and the Arconia starter, no Actuator dependency.
• Last requests missing from a short run. The process exited before the context closed. Let Spring shut down.
• Logs or metrics errors. Set arconia.otel.logs.exporter.type and arconia.otel.metrics.exporter.type to none.