Grafana Cloud

​

Step 1: Get your Grafana Cloud credentials

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

​

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

​

Step 3: Configure Grafana Cloud

• 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

​

Step 4: Test and save

​

Step 5: Send a test trace

​

Viewing your traces

​

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:

{ resource.service.name = "openrouter" }

{ 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

​

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

​

Custom Metadata

​

Supported Metadata Keys

​

Example

{
  "model": "openai/gpt-4o",
  "messages": [{ "role": "user", "content": "Analyze this metric..." }],
  "user": "user_12345",
  "session_id": "session_abc",
  "trace": {
    "trace_id": "monitoring_pipeline_001",
    "trace_name": "Metric Analysis Pipeline",
    "generation_name": "Anomaly Detection",
    "environment": "production",
    "alert_id": "alert_789"
  }
}

​

Querying Custom Metadata with TraceQL

{ resource.service.name = "openrouter" && span.trace.metadata.environment = "production" }

{ resource.service.name = "openrouter" && span.trace.metadata.alert_id = "alert_789" }

​

Additional Context

• The user field maps to user.id in span attributes
• The session_id field maps to session.id in span attributes
• Custom metadata keys from trace appear under the trace.metadata.* namespace in span attributes
• You can create Grafana dashboards and alerts based on custom metadata attributes

​

Example TraceQL queries

​

Find slow requests (> 5 seconds)

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

​

Find requests by user

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

​

Find errors

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

​

Find requests by model

{ 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

​

Additional resources

• Grafana Cloud OTLP Documentation
• TraceQL Query Language
• Grafana Tempo Documentation

​

Privacy Mode