--- title: "Configure the Agent Observability SDK | Grafana Cloud documentation" description: "Tune generation export, authentication, batching, retry, and telemetry settings in your Agent Observability SDK client." --- > For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt). # 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 Expand table | Parameter | Description | |------------|--------------------------------------------------------------| | `protocol` | Transport protocol. Use `http` for Grafana Cloud. | | `endpoint` | Agent Observability API URL from the **Configuration** page. | ## Authentication Expand table | 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](/docs/grafana-cloud/observe-and-act/agent-observability/get-started/grafana-cloud/#collect-credentials-from-grafana-cloud) for setup instructions. ## Batching and retry Expand table | 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: Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash 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.`, which arrives in Prometheus as `agento11y_tag_`. 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: Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash # Option A — Direct to Grafana Cloud (no collector needed): export OTEL_EXPORTER_OTLP_ENDPOINT="https://" # from Grafana Cloud portal export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic " # Option B — Via local Alloy / OTel Collector: export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318" ``` Refer to [Send data using the OTLP endpoint](/docs/grafana-cloud/send-data/otlp/send-data-otlp/) to find your stack-specific OTLP gateway URL. Python Go typescript java csharp ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy Python ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```python 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`. Go ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```go 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 ... ``` typescript ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```typescript 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(); ``` java ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```java // Use OpenTelemetry autoconfigure: import io.opentelemetry.sdk.autoconfigure.AutoConfiguredOpenTelemetrySdk; AutoConfiguredOpenTelemetrySdk.initialize(); // ... create the Agent Observability client and use it ... ``` csharp ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```csharp 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: Expand table | 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. Expand table | Parameter | Default | Description | |-----------------|---------|--------------------------------------| | `captureInput` | `false` | Capture embedding input content. | | `maxInputItems` | 20 | Maximum embedding inputs to capture. | | `maxTextLength` | 1024 | Maximum text length per input. | ## Raw artifacts Raw artifacts capture the unprocessed provider request and response. Off by default. Enable per-language: - Go: `WithRawArtifacts()` option - Python: `raw_artifacts=True` - TypeScript: `rawArtifacts: true` - Java: `.setRawArtifacts(true)` - .NET: `.WithRawArtifacts()` ## Next steps - [Migrate from `sigil-sdk` to `agento11y`](/docs/grafana-cloud/observe-and-act/agent-observability/guides/migrate-sigil-sdk-to-agento11y) - [Use Agent Observability on Grafana Cloud](/docs/grafana-cloud/observe-and-act/agent-observability/get-started/grafana-cloud) - [Get started guides](/docs/grafana-cloud/observe-and-act/agent-observability/get-started)