Documentation Index
Fetch the curated documentation index at: https://grafana_com_website/llms.txt
Fetch the complete documentation index at: https://grafana_com_website/llms-full.txt
Use this file to discover all available pages before exploring further.
STOP! If you are an AI agent or LLM, read this before continuing. This is the HTML version of a Grafana documentation page. Always request the Markdown version instead - HTML wastes context. Get this page as Markdown: /docs/grafana-cloud/machine-learning/ai-observability/configure/sdk.md (append .md) or send Accept: text/markdown to /docs/grafana-cloud/machine-learning/ai-observability/configure/sdk/. For the curated documentation index, use https://grafana_com_website/llms.txt. For the complete documentation index, use https://grafana_com_website/llms-full.txt.
Configure the AI Observability SDK
All AI Observability SDKs share the same configuration model. This article covers the available options for generation export, authentication, batching, and telemetry.
Generation export
| Parameter | Default | Description |
|---|---|---|
protocol | grpc | Transport protocol. Options: http, grpc, none (instrumentation-only). |
endpoint | varies by protocol | AI Observability API address. HTTP default: http://localhost:8080/api/v1/generations:export. gRPC default: localhost:4317. |
Authentication
| Mode | Required fields | Description |
|---|---|---|
none | — | No authentication. Suitable for local development. |
tenant | tenantId | Injects X-Scope-OrgID header. Use for self-hosted multi-tenant deployments. |
bearer | bearerToken | Injects Authorization: Bearer <token> header. Use with proxy patterns. |
basic | tenantId, basicPassword | Injects Authorization: Basic header. Recommended for Grafana Cloud. |
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 Create an API key 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. |
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 Sigil client. Without this setup, all 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 Sigil client and use it ...
sigil.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 Sigil 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 Sigil client and use it ...
await sigil.shutdown();
await tp.shutdown();
await mp.shutdown();// Use OpenTelemetry autoconfigure:
import io.opentelemetry.sdk.autoconfigure.AutoConfiguredOpenTelemetrySdk;
AutoConfiguredOpenTelemetrySdk.initialize();
// ... create Sigil client and use it ...using OpenTelemetry.Metrics;
using OpenTelemetry.Trace;
using var tracerProvider = Sdk.CreateTracerProviderBuilder()
.AddSource("github.com/grafana/sigil/sdks/dotnet")
.AddOtlpExporter()
.Build();
using var meterProvider = Sdk.CreateMeterProviderBuilder()
.AddMeter("github.com/grafana/sigil/sdks/dotnet")
.AddOtlpExporter()
.Build();
// ... create Sigil 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. |
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
Was this page helpful?
Related resources from Grafana Labs


