FeaturesBroadcast

Grafana Cloud

Beta
Send traces to Grafana Cloud

Grafana Cloud is a fully-managed observability platform that includes Grafana Tempo for distributed tracing. OpenRouter sends traces via the standard OTLP HTTP/JSON endpoint.

Step 1: Get your Grafana Cloud credentials

You’ll need three values from your Grafana Cloud portal:

  1. Base URL: Your Grafana Cloud OTLP endpoint (e.g., https://otlp-gateway-prod-us-west-0.grafana.net)
  2. Instance ID: Your numeric Grafana Cloud instance ID (e.g., 123456)
  3. API Key: A Grafana Cloud API token with write permissions (starts with glc_...)

Finding your OTLP endpoint

  1. Log in to your Grafana Cloud portal
  2. Navigate to Connections > Add new connection
  3. Search for OpenTelemetry (OTLP) and select it
  4. On the configuration page, you’ll find your OTLP endpoint URL

The base URL should be the OTLP gateway endpoint, not your main Grafana dashboard URL. The format is https://otlp-gateway-prod-{region}.grafana.net.

Finding your Instance ID

  1. Go to your Grafana Cloud account at https://grafana.com/orgs/{your-org}/stacks
  2. Select your stack
  3. Your Instance ID is the numeric value shown in the URL or on the stack details page

Creating an API token

  1. In Grafana Cloud, go to My Account > Access Policies
  2. Create a new access policy with traces:write scope
  3. Generate a token from this policy
  4. Copy the token (starts with glc_...)

Step 2: Enable Broadcast in OpenRouter

Go to Settings > Broadcast and toggle Enable Broadcast.

Enable Broadcast

Step 3: Configure Grafana Cloud

Click the edit icon next to Grafana Cloud and enter:

  • Base URL: Your Grafana Cloud OTLP endpoint (e.g., https://otlp-gateway-prod-us-west-0.grafana.net)
  • Instance ID: Your numeric Grafana Cloud instance ID
  • API Key: Your Grafana Cloud API token with write permissions

Grafana Cloud Configuration

Step 4: Test and save

Click Test Connection to verify the setup. The configuration only saves if the test passes.

Grafana Cloud Configured

Step 5: Send a test trace

Make an API request through OpenRouter and view the trace in Grafana Cloud.

Grafana Cloud Trace

Viewing your traces

Once configured, you can view traces in Grafana Cloud in two ways:

Option 1: Explore with TraceQL

  1. Go to your Grafana Cloud instance (e.g., https://your-stack.grafana.net)
  2. Click Explore in the left sidebar
  3. Select your Tempo data source (e.g., grafanacloud-*-traces)
  4. Switch to the TraceQL tab
  5. Run this query to see all OpenRouter traces:
1{ resource.service.name = "openrouter" }

You can also filter by specific attributes:

1{ resource.service.name = "openrouter" && span.gen_ai.request.model = "openai/gpt-4-turbo" }

Option 2: Drilldown > Traces

  1. Go to your Grafana Cloud instance
  2. Navigate to Drilldown > Traces in the left sidebar
  3. Use the filters to find traces by service name, duration, or other attributes
  4. Click on any trace to see the full span breakdown

Trace attributes

OpenRouter traces include the following key attributes:

Resource attributes

  • service.name: Always openrouter
  • service.version: 1.0.0
  • openrouter.trace.id: The OpenRouter trace ID

Span attributes

  • gen_ai.operation.name: The operation type (e.g., chat)
  • gen_ai.system: The AI provider (e.g., openai)
  • gen_ai.request.model: The requested model
  • gen_ai.response.model: The actual model used
  • gen_ai.usage.input_tokens: Number of input tokens
  • gen_ai.usage.output_tokens: Number of output tokens
  • gen_ai.usage.total_tokens: Total tokens used
  • gen_ai.response.finish_reason: Why the generation ended (e.g., stop)

Custom metadata

Any metadata you attach to your OpenRouter requests will appear under the trace.metadata.* namespace.

Example TraceQL queries

Find slow requests (> 5 seconds)

1{ resource.service.name = "openrouter" && duration > 5s }

Find requests by user

1{ resource.service.name = "openrouter" && span.user.id = "user_abc123" }

Find errors

1{ resource.service.name = "openrouter" && status = error }

Find requests by model

1{ resource.service.name = "openrouter" && span.gen_ai.request.model =~ ".*gpt-4.*" }

Troubleshooting

Traces not appearing

  1. Check the time range: Grafana’s time picker might not include your trace timestamp. Try expanding to “Last 1 hour” or “Last 24 hours”.
  2. Verify the endpoint: Make sure you’re using the OTLP gateway URL (https://otlp-gateway-prod-{region}.grafana.net), not your main Grafana URL.
  3. Check authentication: Ensure your Instance ID is numeric and your API key has write permissions.
  4. Wait a moment: There can be a 1-2 minute delay before traces appear in Grafana.

Wrong data source

If you don’t see any traces, make sure you’ve selected the correct Tempo data source in the Explore view. It’s typically named grafanacloud-{stack}-traces.

Additional resources