--- title: "Set up Agent Observability | Grafana Cloud documentation" description: "Enable Agent 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). # 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](/auth/sign-up/create-user). - 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://.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//stacks/`. 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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash export AGENTO11Y_ENDPOINT="" export AGENTO11Y_PROTOCOL=http export AGENTO11Y_AUTH_MODE=basic export AGENTO11Y_AUTH_TENANT_ID="" export AGENTO11Y_AUTH_TOKEN="" ``` 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 agento11y import Client client = Client() ``` For language-specific installation and code, refer to: - [Instrument Python agents](/docs/grafana-cloud/observe-and-act/agent-observability/get-started/python) - [Instrument TypeScript and JavaScript agents](/docs/grafana-cloud/observe-and-act/agent-observability/get-started/javascript) - [Instrument Go agents](/docs/grafana-cloud/observe-and-act/agent-observability/get-started/go) - [Instrument Java agents](/docs/grafana-cloud/observe-and-act/agent-observability/get-started/java) - [Instrument .NET agents](/docs/grafana-cloud/observe-and-act/agent-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 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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash export OTEL_EXPORTER_OTLP_ENDPOINT="" export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic " ``` 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' ':' | 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/observe-and-act/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 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 ![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 `client.shutdown()`: Python ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```python client.shutdown() tp.shutdown() mp.shutdown() ``` Refer to [SDK configuration](/docs/grafana-cloud/observe-and-act/agent-observability/configure/sdk/#opentelemetry-setup) 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 - [Configure SDK options](/docs/grafana-cloud/observe-and-act/agent-observability/configure/sdk) - [Set up online evaluation](/docs/grafana-cloud/observe-and-act/agent-observability/guides/evaluation)