Documentationbreadcrumb arrow Grafana Cloudbreadcrumb arrow Observe and actbreadcrumb arrow Agent Observabilitybreadcrumb arrow Get startedbreadcrumb arrow Set up
Grafana Cloud

Set up Agent Observability

Enable Agent Observability on your Grafana Cloud stack, collect five values from three Grafana Cloud pages, configure your SDK with environment variables, and start sending data.

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 Agent Observability

An administrator must enable Agent Observability for your stack:

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

After you enable Agent Observability, Agent Observability is available under Observability in the left sidebar.

Collect credentials from Grafana Cloud

You need three values to send conversation data: an Agent Observability endpoint URL, an 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.

Agent Observability Configuration page

In Agent Observability, navigate to Configuration. Copy:

  • API URL: use as AGENTO11Y_ENDPOINT.
  • Instance ID: use as AGENTO11Y_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 agento11y.
  • Scopes: open the Add scope dropdown and select sigil:write. The Enable Agent Observability 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 AGENTO11Y_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 Grafana 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 Agent 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 AGENTO11Y_ENDPOINT="<API URL from the Configuration page>"
export AGENTO11Y_PROTOCOL=http
export AGENTO11Y_AUTH_MODE=basic
export AGENTO11Y_AUTH_TENANT_ID="<Instance ID from the Configuration page>"
export AGENTO11Y_AUTH_TOKEN="<glc_... token from the access policy>"

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

Python 
from agento11y 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 generation-ingest receivers. They carry OpenTelemetry traces and metrics only. Generation data goes directly to the Agent Observability 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 Agent Observability endpoint via the SDK.

Configure providers in your application

After setting the environment variables, configure TracerProvider and MeterProvider in your application before creating the 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 client.shutdown():

Python 
client.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 Agent Observability. 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 Agent Observability before instrumenting your own agent, seed the built-in demo data:

  1. Navigate to Observability > Agent Observability.
  2. On the onboarding screen, click One-click demo.

Agent Observability seeds sample conversations, agents, evaluation rules, a generation dependency DAG, and workflow-step telemetry so you can explore every feature immediately. Demo resources display a demo badge throughout the UI.

Next steps