---
title: "Configure the AI Observability SDK | Grafana Cloud documentation"
description: "Tune generation export, authentication, batching, retry, and telemetry settings in your AI Observability SDK client."
---

# 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

Expand table

| 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

Expand table

| 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](/docs/grafana-cloud/machine-learning/ai-observability/get-started/grafana-cloud/#create-an-api-key) 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.                            |

## 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:

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://<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](/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 Sigil client and use it ...

sigil.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 Sigil 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 Sigil client and use it ...

await sigil.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 Sigil 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/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:

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

- [Configure deployment options](/docs/sigil/next/configure/deployment)
- [Get started guides](/docs/grafana-cloud/machine-learning/ai-observability/get-started)