Set up Agent Observability in Grafana Cloud
Enable Agent Observability on your Grafana Cloud stack, then connect your application with an SDK or OpenTelemetry instrumentation.
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.
Before you send data, refer to Privacy and access for pricing, data handling, and permissions, and Protect agents for guards and redaction controls.
Enable Agent Observability
An administrator must enable Agent Observability for your stack:
- Sign in to Grafana Cloud as an administrator.
- Navigate to Observability > Agent Observability.
- Review and accept the terms.
- Click Save.
After you enable Agent Observability, Agent Observability is available under Observability in the left sidebar.
Choose your instrumentation
If you use OpenTelemetry generative AI instrumentation, continue to Instrument agents with OpenTelemetry. That guide uses your Grafana Cloud OTLP credentials; you don’t need the SDK credentials below.
If you use an Agent Observability SDK, continue with the setup below.
Collect credentials from Grafana Cloud
You need three values to send conversation data: an Agent Observability endpoint URL, an instance ID, and a Grafana Cloud Access Policy Token. To send OpenTelemetry metrics and traces 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.
Grafana 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 metrics, logs, and traces with the same token, also select
metrics:write,logs:write, andtraces:writein 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 metrics and traces 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:
export AGENTO11Y_ENDPOINT="<AGENTO11Y_ENDPOINT>"
export AGENTO11Y_PROTOCOL=http
export AGENTO11Y_AUTH_MODE=basic
export AGENTO11Y_AUTH_TENANT_ID="<AGENTO11Y_INSTANCE_ID>"
export AGENTO11Y_AUTH_TOKEN="<ACCESS_POLICY_TOKEN>"Replace AGENTO11Y_ENDPOINT and AGENTO11Y_INSTANCE_ID with the values from Configuration, and ACCESS_POLICY_TOKEN with your token. The SDK reads these environment variables when you create the client:
from agento11y import Client
client = Client()For language-specific installation and code, refer to:
- Instrument Python agents
- Instrument TypeScript and JavaScript agents
- Instrument Go agents
- Instrument Java agents
- Instrument .NET agents
Set up metrics and traces
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 don’t accept the generation export API used by the SDK. With the SDK setup on this page, generation data goes directly to the Agent Observability endpoint.
Warning
Without a configured
TracerProviderandMeterProviderin your application, SDK-emitted metrics and traces 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.
export OTEL_EXPORTER_OTLP_ENDPOINT="<OTLP_ENDPOINT>"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic%20<BASE64_CREDENTIALS>"Replace OTLP_ENDPOINT with the endpoint URL from the OpenTelemetry card, including /otlp but excluding signal paths such as /v1/traces. For the Python exporter below, use %20 for the space after Basic.
Replace BASE64_CREDENTIALS with the Base64-encoded OTLP instance ID and access policy token. In the following command, replace OTLP_INSTANCE_ID with the Instance ID from the OpenTelemetry card, and ACCESS_POLICY_TOKEN with your access policy token. Use the OTLP instance ID, which can differ from the Agent Observability instance ID:
printf '%s' '<OTLP_INSTANCE_ID>:<ACCESS_POLICY_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.
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"With this SDK setup, Alloy or the collector forwards metrics and traces only. Generation data goes directly to the Agent Observability endpoint.
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:
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():
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:
- Navigate to Observability > Agent Observability.
- 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.


