---
title: "Use AI Observability on Grafana Cloud | Grafana Cloud documentation"
description: "Enable Grafana AI Observability on your Grafana Cloud stack and start sending generation data."
---

> For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt).

# Use AI Observability on Grafana Cloud

Grafana Cloud provides a managed AI Observability deployment. You enable the plugin, collect five values from three Cloud pages, configure your SDK with environment variables, and start sending data.

> Note
> 
> AI Observability is referred to as “Sigil” in SDKs, package names, and configuration. For example, the Python package is `sigil-sdk` and environment variables use the `SIGIL_` prefix.

## Before you begin

- A Grafana Cloud account. If you don’t have one, [sign up at grafana.com](/auth/sign-up/create-user).
- Administrator access to your Grafana Cloud stack.

## Enable the plugin

An administrator must enable the plugin for your stack:

1. Sign in to Grafana Cloud as an administrator.
2. Navigate to **Observability** > **AI Observability**.
3. Review and accept the terms.
4. Click **Save**.

After you enable the plugin, **AI Observability** is available under **Observability** in the left sidebar.

## Collect credentials from Grafana Cloud

You need three values to send conversation data: a Sigil endpoint URL, a Sigil instance ID, and a Cloud Access Policy Token. To send OpenTelemetry traces and metrics directly to Grafana Cloud, you also need an OTLP endpoint URL and an OTLP instance ID. The values come from three Grafana Cloud pages.

### AI Observability Configuration page

URL pattern: `https://<stack>.grafana.net/plugins/grafana-sigil-app`. In the AI Observability plugin, navigate to **Configuration**. Copy:

- **API URL**: use as `SIGIL_ENDPOINT`.
- **Instance ID**: use as `SIGIL_AUTH_TENANT_ID`. Numeric Grafana Cloud stack ID.

### Cloud access policy

URL pattern: `https://<stack>.grafana.net/a/grafana-auth-app`. Click **Create access policy**.

- **Display name** and **Name**: any descriptive label, for example `sigil-sdk`.
- **Scopes**: open the **Add scope** dropdown and select **`sigil:write`** . The Enable the plugin step makes this scope available in the dropdown.
- If you want to send OpenTelemetry traces and metrics with the same token, also select `metrics:write`, `traces:write`, and `logs:write` in the Read/Write/Delete grid. One token covers both channels and is easier to rotate than two.
- Click **Create**, then on the new policy click **Add token**, give it a name, and copy the token shown once. Tokens start with `glc_…`.

Use the token as `SIGIL_AUTH_TOKEN`.

> Warning
> 
> The token is shown only once. Store it securely, for example in an environment variable or secret manager.

### OpenTelemetry card on the Cloud portal

Only needed if you want to send OpenTelemetry traces and metrics directly to Grafana Cloud. Skip this section if you’ll use a local Alloy or OpenTelemetry Collector instead.

URL pattern: `https://grafana.com/orgs/<org>/stacks/<stack-id>`. Find the **OpenTelemetry** card. Copy:

- **OTLP endpoint URL**: use as `OTEL_EXPORTER_OTLP_ENDPOINT`.
- **Instance ID** on the OpenTelemetry card: the basic-auth username for OTLP. This is not necessarily the same as the AI Observability Instance ID. Use the number shown on this card.

Don’t click **Generate now** on the OpenTelemetry card. The access policy token already covers the OTLP scopes if you selected them.

## Configure your SDK

Set these environment variables in your application’s process:

Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
export SIGIL_ENDPOINT="<API URL from the Configuration page>"
export SIGIL_PROTOCOL=http
export SIGIL_AUTH_MODE=basic
export SIGIL_AUTH_TENANT_ID="<Instance ID from the Configuration page>"
export SIGIL_AUTH_TOKEN="<glc_... token from the access policy>"
```

The SDK reads them at client construction. No additional configuration is required:

Python ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```python
from sigil_sdk import Client

client = Client()
```

For language-specific installation and code, refer to:

- [Instrument Python agents](/docs/grafana-cloud/machine-learning/ai-observability/get-started/python)
- [Instrument TypeScript and JavaScript agents](/docs/grafana-cloud/machine-learning/ai-observability/get-started/javascript)
- [Instrument Go agents](/docs/grafana-cloud/machine-learning/ai-observability/get-started/go)
- [Instrument Java agents](/docs/grafana-cloud/machine-learning/ai-observability/get-started/java)
- [Instrument .NET agents](/docs/grafana-cloud/machine-learning/ai-observability/get-started/dotnet)

## Set up traces and metrics

The SDK emits OpenTelemetry spans and metrics (`gen_ai.client.operation.duration`, `gen_ai.client.token.usage`, `gen_ai.client.time_to_first_token`, `gen_ai.client.tool_calls_per_operation`). These are separate from generation data and require an OTLP endpoint and an installed `TracerProvider` and `MeterProvider`.

> Warning
> 
> **Alloy and the OpenTelemetry Collector are not Sigil generation-ingest receivers.** They carry OpenTelemetry traces and metrics only. Generation data goes directly to the Sigil endpoint via the SDK.

> Warning
> 
> Without a configured `TracerProvider` and `MeterProvider` in your application, SDK-emitted traces and metrics go to the default no-op and are dropped. The SDK doesn’t create OTel providers. Your application must set them up.

You can send OTLP data to Grafana Cloud in two ways.

### Send directly to Grafana Cloud

Send OTLP directly to the Grafana Cloud OTLP gateway. Use the values from the OpenTelemetry card.

Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
export OTEL_EXPORTER_OTLP_ENDPOINT="<OTLP endpoint URL>"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic <base64(otlp-instance-id:glc_token)>"
```

Compute the basic-auth header value with the OTLP Instance ID and the access policy token:

Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
printf '%s' '<otlp-instance-id>:<glc_token>' | base64 | tr -d '\n'
```

The `tr -d '\n'` is not optional. `base64` adds a trailing newline that invalidates the header.

### Send via Alloy or OTel Collector

Run a local [Grafana Alloy](/docs/grafana-cloud/send-data/alloy/) or OpenTelemetry Collector that receives unauthenticated OTLP and forwards to Grafana Cloud with credentials. This is useful for centralized token management, retries, relabeling, and metadata enrichment, at the cost of running another process.

Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"
```

This path covers traces and metrics only. Generation data still goes directly to the Sigil endpoint via the SDK.

### Configure providers in your application

After setting the environment variables, configure `TracerProvider` and `MeterProvider` in your application before creating the Sigil client. For example, in Python:

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)
```

Shut down providers after `sigil.shutdown()`:

Python ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```python
sigil.shutdown()
tp.shutdown()
mp.shutdown()
```

Refer to [SDK configuration](/docs/grafana-cloud/machine-learning/ai-observability/configure/sdk/#opentelemetry-setup) for setup snippets in all supported languages.

## Verify data

Run your instrumented agent and open **Conversations** in the AI Observability plugin. Your first generation should appear within a few seconds. Check your Grafana Cloud **Traces** and **Metrics** data sources for SDK-emitted spans and metrics.

## Try the demo

If you want to explore AI Observability before instrumenting your own agent, seed the built-in demo data:

1. Navigate to **Observability** &gt; **AI Observability**.
2. On the onboarding screen, click **One-click demo**.

AI Observability seeds sample conversations, agents, and evaluation rules so you can explore every feature immediately. Demo resources display a demo badge throughout the UI.

## Next steps

- [Configure SDK options](/docs/grafana-cloud/machine-learning/ai-observability/configure/sdk)
- [Set up online evaluation](/docs/grafana-cloud/machine-learning/ai-observability/guides/evaluation)