BigQuery

​

Overview

• SQL-native analytics — Query traces directly, or join them against the rest of your warehouse.
• One row per request — A wide, denormalized table that is easy to aggregate, with no span-tree traversal.
• Cost & token attribution — Per-request cost plus fine-grained token breakdowns, attributable to teams, customers, virtual keys, and users.
• Long-term retention — Keep history far beyond what a logs database or APM retention window allows.
• Zero request-latency impact — Traces are buffered and flushed asynchronously in the background.

​

Authentication

​

Configuration

{
  "plugins": [
    {
      "enabled": true,
      "name": "bigquery",
      "config": {
        "project_id": "my-gcp-project"
      }
    }
  ]
}

{
  "plugins": [
    {
      "enabled": true,
      "name": "bigquery",
      "config": {
        "project_id": "my-gcp-project",
        "dataset_id": "bifrost_traces",
        "table_id": "traces",
        "location": "US",
        "service_account_key": "env.GCP_SERVICE_ACCOUNT_KEY",
        "create_table_if_not_exists": true,
        "flush_interval_seconds": 5,
        "buffer_size": 500,
        "disable_content_logging": false,
        "request_headers": ["X-Tenant-ID", "x-custom-*"],
        "custom_labels": {
          "environment": "production",
          "region": "env.DEPLOY_REGION"
        }
      }
    }
  ]
}

export GCP_SERVICE_ACCOUNT_KEY='{"type":"service_account","project_id":"...", ...}'

​

Table Schema

-- Step 1: Create the dataset (if it doesn't exist)
CREATE SCHEMA IF NOT EXISTS `my-gcp-project.bifrost_traces`
OPTIONS (
  location = 'US'
);

-- Step 2: Create the traces table with partitioning and clustering
CREATE TABLE IF NOT EXISTS `my-gcp-project.bifrost_traces.traces`
(
  trace_id STRING NOT NULL,
  timestamp TIMESTAMP NOT NULL,
  request_type STRING,
  provider STRING,
  model STRING,
  virtual_key_id STRING,
  -- ... remaining columns from the categories above ...
  labels STRING,
  inserted_at TIMESTAMP
)
PARTITION BY DATE(timestamp)
CLUSTER BY provider, model, virtual_key_id;

​

Content & Header Capture

• disable_content_logging — Set to true to omit conversation content. The input_history and output_message columns are left empty, while all metadata (tokens, cost, latency, attribution) is still recorded. Use this for privacy-sensitive workloads.
• request_headers — A list of header-name patterns whose values are captured into the request_headers column as a JSON map. Supports exact names (X-Tenant-ID) and wildcards (x-custom-*, or * for all headers).
  Using * captures all request headers, including sensitive ones like Authorization. Prefer explicit names or scoped wildcards.
• custom_labels — Static key-value pairs attached to every row in the labels column (JSON). Values support env.VAR_NAME, which is handy for environment or region tags.
• dimensions — Per-request dimensions sent via x-bf-dim-* headers are captured automatically into the dimensions column (JSON). No configuration required.

​

Example Queries

SELECT
  team_name,
  ROUND(SUM(cost), 4) AS total_cost_usd,
  COUNT(*) AS requests
FROM `my-gcp-project.bifrost_traces.traces`
WHERE DATE(timestamp) >= DATE_SUB(CURRENT_DATE(), INTERVAL 7 DAY)
  AND status = 'success'
GROUP BY team_name
ORDER BY total_cost_usd DESC;

SELECT
  model,
  APPROX_QUANTILES(latency_ms, 100)[OFFSET(95)] AS p95_latency_ms,
  COUNT(*) AS requests
FROM `my-gcp-project.bifrost_traces.traces`
WHERE DATE(timestamp) = CURRENT_DATE()
GROUP BY model
ORDER BY requests DESC;

SELECT
  provider,
  COUNTIF(status = 'error') AS errors,
  COUNT(*) AS total,
  ROUND(SAFE_DIVIDE(COUNTIF(status = 'error'), COUNT(*)) * 100, 2) AS error_rate_pct
FROM `my-gcp-project.bifrost_traces.traces`
WHERE timestamp >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 24 HOUR)
GROUP BY provider
ORDER BY error_rate_pct DESC;

SELECT
  DATE(timestamp) AS day,
  SUM(prompt_tokens) AS input_tokens,
  SUM(completion_tokens) AS output_tokens,
  SUM(total_tokens) AS total_tokens
FROM `my-gcp-project.bifrost_traces.traces`
WHERE DATE(timestamp) >= DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY)
GROUP BY day
ORDER BY day;

​

Plugin Span Filtering

{
  "plugins": [
    {
      "name": "bigquery",
      "enabled": true,
      "config": {
        "project_id": "my-gcp-project",
        "plugin_span_filter": {
          "mode": "exclude",
          "plugins": ["logging", "compat", "telemetry"]
        }
      }
    }
  ]
}

​

Troubleshooting

​

Table or dataset not found

​

Authentication failures

echo "$GCP_SERVICE_ACCOUNT_KEY" | head -c 40

​

No rows appearing

bifrost-http --log-level debug

​

Missing conversation content

​

Next Steps

• OpenTelemetry (OTel) — Stream traces to any OTLP-compatible backend.
• Datadog — Native Datadog APM and LLM Observability integration.
• Built-in Observability — Local logging for development and simple deployments.
• Telemetry — Prometheus metrics and dashboards.