Documentationbreadcrumb arrow Grafana Cloudbreadcrumb arrow AI and machine learningbreadcrumb arrow Grafana AI Observabilitybreadcrumb arrow Get startedbreadcrumb arrow Grafana Cloud
Grafana Cloud

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.
  • 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 
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 
from sigil_sdk import Client

client = Client()

For language-specific installation and code, refer to:

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 
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 
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 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 
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 
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 
sigil.shutdown()
tp.shutdown()
mp.shutdown()

Refer to SDK configuration 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 > 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