Configure the Agent Observability SDK

All Agent Observability SDKs share the same configuration model. This article covers the available options for generation export, authentication, batching, and telemetry.

Generation export

Parameter	Description
`protocol`	Transport protocol. Use `http` for Grafana Cloud.
`endpoint`	Agent Observability API URL from the Configuration page.

Authentication

Mode	Required fields	Description
`basic`	`tenantId`, `basicPassword`	Uses your Grafana Cloud instance ID and Cloud Access Policy Token.

For basic mode, tenantId is your Grafana Cloud instance ID and basicPassword is a Grafana Cloud Access Policy Token with the sigil:write scope. Refer to Collect credentials from Grafana Cloud for setup instructions.

Batching and retry

Parameter	Default	Description
`batchSize`	100	Maximum generations per export batch.
`flushInterval`	1s	How often the SDK flushes queued generations.
`queueSize`	2000	Maximum number of queued generations before the SDK drops new ones.
`maxRetries`	5	Number of retry attempts for transient failures.
`initialBackoff`	100ms	Initial retry delay.
`maxBackoff`	5s	Maximum retry delay.
`payloadMaxBytes`	16 MB	Maximum payload size per export request.

Client tags

Client tags are key-value pairs that the SDK attaches to every generation, span, and metric it records. Use them for low-cardinality values that you want to filter and group by, for example, team, project, or environment.

Set them with the AGENTO11Y_TAGS environment variable, as a comma-separated list of key=value pairs:

export AGENTO11Y_TAGS=team=ai,env=production

You can also set tags in the client configuration. The SDK merges both sets, and a value you set in code takes precedence for the same key.

On spans and metrics, each key becomes an attribute named agento11y.tag.<KEY>, which arrives in Prometheus as agento11y_tag_<KEY>.

Every distinct tag value adds a metric series. Keep the list of possible values short, for example, your teams or environments. Values that change per user or per request belong on a single generation instead.

The tags and metadata that you pass on a single generation apply to that generation only. The SDK doesn’t turn them into span or metric attributes. In Go, per-request context tags set with WithTag or WithTags are the exception: they reach spans and metrics the same way client tags do.

OpenTelemetry setup

The SDK emits OpenTelemetry spans and metrics internally, but does not create OTel providers. Your application must configure a TracerProvider and MeterProvider before creating the Agent Observability client. Without this setup, traces and metrics are silently lost.

Set the OTLP endpoint and optional auth headers through environment variables. The OTel SDK exporters read them automatically:

# Option A — Direct to Grafana Cloud (no collector needed):
export OTEL_EXPORTER_OTLP_ENDPOINT="https://<your-otlp-gateway-url>"   # from Grafana Cloud portal
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic <base64(instance_id:cloud_api_token)>"

# Option B — Via local Alloy / OTel Collector:
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"

Refer to Send data using the OTLP endpoint to find your stack-specific OTLP gateway URL.

from opentelemetry import trace, metrics
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
from opentelemetry.sdk.resources import Resource
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.exporter.otlp.proto.http.metric_exporter import OTLPMetricExporter

resource = Resource.create({"service.name": "my-agent"})

tp = TracerProvider(resource=resource)
tp.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
trace.set_tracer_provider(tp)

mp = MeterProvider(resource=resource, metric_readers=[
    PeriodicExportingMetricReader(OTLPMetricExporter())
])
metrics.set_meter_provider(mp)

# ... create the Agent Observability client and use it ...

agento11y.shutdown()
tp.shutdown()
mp.shutdown()

This example requires opentelemetry-sdk and opentelemetry-exporter-otlp-proto-http.

import (
    "go.opentelemetry.io/otel"
    sdkmetric "go.opentelemetry.io/otel/sdk/metric"
    sdktrace "go.opentelemetry.io/otel/sdk/trace"
    "go.opentelemetry.io/contrib/exporters/autoexport"
)

traceExp, _ := autoexport.NewSpanExporter(ctx)
tp := sdktrace.NewTracerProvider(sdktrace.WithBatcher(traceExp), sdktrace.WithResource(res))
otel.SetTracerProvider(tp)
defer tp.Shutdown(ctx)

metricExp, _ := autoexport.NewMetricReader(ctx)
mp := sdkmetric.NewMeterProvider(sdkmetric.WithReader(metricExp), sdkmetric.WithResource(res))
otel.SetMeterProvider(mp)
defer mp.Shutdown(ctx)

// ... create the Agent Observability client and use it ...

import { metrics } from "@opentelemetry/api";
import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
import {
  MeterProvider,
  PeriodicExportingMetricReader,
} from "@opentelemetry/sdk-metrics";
import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";

const tp = new NodeTracerProvider({ resource });
tp.addSpanProcessor(new BatchSpanProcessor(new OTLPTraceExporter()));
tp.register();

const mp = new MeterProvider({
  resource,
  readers: [
    new PeriodicExportingMetricReader({ exporter: new OTLPMetricExporter() }),
  ],
});
metrics.setGlobalMeterProvider(mp);

// ... create the Agent Observability client and use it ...

await agento11y.shutdown();
await tp.shutdown();
await mp.shutdown();

// Use OpenTelemetry autoconfigure:
import io.opentelemetry.sdk.autoconfigure.AutoConfiguredOpenTelemetrySdk;

AutoConfiguredOpenTelemetrySdk.initialize();

// ... create the Agent Observability client and use it ...

using OpenTelemetry.Metrics;
using OpenTelemetry.Trace;

using var tracerProvider = Sdk.CreateTracerProviderBuilder()
  .AddSource("github.com/grafana/agento11y/sdks/dotnet")
    .AddOtlpExporter()
    .Build();

using var meterProvider = Sdk.CreateMeterProviderBuilder()
  .AddMeter("github.com/grafana/agento11y/sdks/dotnet")
    .AddOtlpExporter()
    .Build();

// ... create the Agent Observability client and use it ...

OpenTelemetry metrics

The SDK emits these OpenTelemetry metrics:

Metric	Type	Description
`gen_ai.client.operation.duration`	Histogram	LLM call duration.
`gen_ai.client.token.usage`	Histogram	Token consumption per call.
`gen_ai.client.time_to_first_token`	Histogram	Streaming time to first token.
`gen_ai.client.tool_calls_per_operation`	Histogram	Tool calls per generation.

Embedding capture

Embedding capture is off by default. Enable it for debugging only because it may expose sensitive data.

Parameter	Default	Description
`captureInput`	`false`	Capture embedding input content.
`maxInputItems`	20	Maximum embedding inputs to capture.
`maxTextLength`	1024	Maximum text length per input.