🔭 技術調査 - Google Cloud Observability Analytics

■概要

Observability Analytics は、Cloud Logging のログと Cloud Trace のスパンを SQL で横断分析するための統合基盤です。リリースの軸は次の 2 段階に分かれます。

• 2026-05-26 (GA): 3 件が同時 GA — Cloud Trace のクエリ機能、管理・構成用の Observability API、複数プロジェクトを 1 つのクエリ対象に束ねる Trace scopes
• 2026-06-24 (launch blog): 正式タイトル「Log Analytics is now Observability Analytics: Query logs and traces with SQL」として リネームと公式の周知。ログ専用基盤からテレメトリ統合分析基盤への位置づけ変更を表します

(リネームは launch blog で正式に周知された呼称変更で、release notes に独立した GA 項目はありません。)

クエリは BigQuery と同じ標準 SQL で記述します。データは Cloud Logging のログバケットと Cloud Trace の observability バケットに格納されたまま、in-place でクエリできます。BigQuery へのエクスポートやコピーを行わずに集計や JOIN を実行できる点が中心的な価値です。

業務データとの突合が必要な場合は、observability バケットに linked BigQuery dataset をはることで、業務テーブルと観測データを同じ BigQuery 上でクロス JOIN できます。linked dataset は ingest や storage の追加課金がなく、クエリ時に BigQuery analysis charges だけが発生する設計です。

主なユースケースは、AI エージェントのツール失敗率や P95 レイテンシの算出、エージェントの思考ログと分散トレースの SQL JOIN、顧客 ID 別のレイテンシ影響分析です。エージェント運用と SRE 観測を同じクエリ言語に寄せることが本機能の狙いです。

本記事の差別化ポイントは次の 3 つです。

1. エージェント観測の tool failure rate / P95 latency / 思考ログと trace の JOIN / 顧客別影響 を 1 つの SQL 言語で書き切る運用設計
2. LLM token 使用量 × 顧客 × モデル のコスト相関を gen_ai.* semantic conventions の属性で標準化
3. Observability bucket と linked BigQuery dataset、それぞれの IAM 設計と alerting/SQL の制約を一次情報ベースで整理

■特徴

GA とプレビューの範囲

構成要素ごとに段階が異なります。

• 2026-05-26 GA: Cloud Trace のクエリ機能 / Observability API / Trace scopes の 3 件 (Trace release notes で確認できる範囲)
• GA (既存機能): Log Analytics 由来の Log views、Observability Analytics 本体のクエリ機能
• Public Preview: Analytics views (ユーザー定義スキーマの分析専用ビュー)
• 注: Trace を SQL で分析する機能自体は GA ですが、docs 上の UI 表現として "Observability views are in Public Preview" の表記が混在する箇所があります

主要な価値

launch blog が掲げる 3 つの中核ベネフィットです。

• Unified telemetry: 大量のログとトレースを 1 か所で SQL JOIN して分析できる
• Business correlation: BigQuery にある業務データ (売上、コンバージョン率、運用コスト) と観測データを JOIN し、技術課題のビジネス影響を定量化できる
• In-place analysis: Cloud Logging と Cloud Trace に格納されたデータをそのままクエリし、重複エクスポートのコストと運用複雑度を削減する

Observability API の役割

API の GA により、observability バケット・linked BigQuery dataset・暗号化キー・デフォルト保存先をプログラマブルに構成できます。

• observability バケットの linked BigQuery dataset を作成し、BigQuery エコシステムから直接参照可能にする
• Trace データのデフォルト保存ロケーションと CMEK を構成する
• AI エージェントや分析ワークロードが標準 BigQuery API・ツール経由でテレメトリを取得できる経路を整える

BigQuery in-place の意味

データは Cloud Logging・Cloud Trace のバケットに常駐します。linked BigQuery dataset は BigQuery 側からの参照ビューとして機能し、データ実体の複製は行いません。

• ingest と storage の課金は Cloud Logging・Cloud Trace 側のままで、BigQuery 側の storage 課金は発生しない
• BigQuery Studio やデータポータルから観測データを直接クエリできる
• 業務テーブル (BigQuery 上) との JOIN や、reserved slots による性能チューニングは linked dataset 経由で実現する

エージェント運用への適合性

launch blog は AI エージェント観測の文脈を前面に出しています。

• ツール呼び出し失敗率と P95/P99 レイテンシを span 集計で算出
• agent_thoughts や llm_prompt を含むログと trace span を trace_id・span_id で JOIN し、失敗の理由まで遡る
• 顧客 ID をログペイロードに埋めることで、顧客別 SLO 影響を業務 KPI と一緒に評価する

SQL 機能と表示

標準 SQL の集計、グルーピング、JOIN、ネストクエリ、REGEXP_EXTRACT、CAST、フィルタ、ソート、LIMIT に対応します。結果はテーブルとチャートで可視化でき、カスタムダッシュボードに保存できます (BigQuery 一般機能としての pipe syntax |> も書ける場面はありますが、Observability Analytics UI 固有の公式記載はまだ確認できません)。

リネームの背景

旧 Log Analytics はログ専用の SQL クエリ基盤でした。Trace データ対応の GA に伴い、テレメトリ統合分析の位置づけを反映するため Observability Analytics に改称されました。Cloud Trace の _Trace.Spans._AllSpans ビューを通じてスパンも同じ SQL で扱えるため、ログ単独・トレース単独・両者 JOIN の 3 パターンが 1 つの UI と API で完結します。

競合・既存機能との位置づけ

主要観測基盤との特性比較です。

Logs Explorer・Trace Explorer は集計や複雑 JOIN を扱う設計ではなく、調査の初手と単発フィルタ用途に寄っています。Observability Analytics はこの 2 つを SQL で束ねた上位レイヤとして位置づけられます。

■構造

●システムコンテキスト図

開発者・SRE・オンコール・データアナリストが Observability Analytics を介して logs と traces を SQL で横断分析し、結果を Dashboard / Alerting に接続する全体像。OpenTelemetry SDK と各 Google Cloud サービスがテレメトリ供給元となります。

●コンテナ図

Observability API がコントロールプレーン、SQL Engine = BigQuery がクエリプレーン、データプレーンは Cloud Logging buckets と Cloud Trace _Trace bucket。Console UI が Query Builder / SQL Editor / Dashboard saver を提供し、Linked BigQuery Dataset がオプションで external BigQuery と接続します。

●コンポーネント図

Console UI と SQL Engine が触るオブジェクトレベルの構造。Log View / Analytics View / Trace _AllSpans がクエリ対象の最小単位で、Linked Dataset Link が projects/.../buckets/.../datasets/.../links/<id> リソースとして BigQuery 側にミラーします。IAM ロールがアクセス境界を引きます。

■データ

●概念モデル

●情報モデル

抽象型と BigQuery 物理型の対応:

ビューの完全修飾名:

LOG_VIEW_ID / ANALYTICS_VIEW_ID は 100 文字以内、英数字 / アンダースコア / ハイフンのみです。

主要属性のアクセス例:

• t.trace_id / t.span_id / t.parent_span_id — Span 識別子 (STRING)
• t.duration_nano — 経過時間ナノ秒 (INT64)。ミリ秒換算は t.duration_nano / 1000000 (query docs は duration_nano、schema reference には duration_unix_nano の表記もあり、samples / launch blog は duration_nano を採用)
• t.status.code — OTel 由来の状態コード (INT64)。0 = UNSET / 1 = OK / 2 = ERROR (launch blog のサンプルは status.code = 2 で error を抽出する)
• t.kind — span 種別 (INT64、0-5)。OTel SpanKind に対応。launch blog では t.kind.name = 'SPAN_KIND_SERVER' 形式の参照も登場するが、docs.cloud.google.com/trace/docs/analytics-samples の正準サンプルは INT 比較 (WHERE kind = 2 等) を示す
• JSON_VALUE(t.attributes, '$."agent.tool.name"') — span attributes は JSON 型、キー指定で取り出す
• l.trace — projects/PROJECT_ID/traces/TRACE_ID 形式。trace_id 抽出は REGEXP_EXTRACT(L.trace, r'/([^/]+)$') (公式 docs の正準形)、または SPLIT(l.trace, '/')[SAFE_OFFSET(3)] (launch blog 流)
• l.span_id — Log 側の span 参照 (16 桁 hex)。公式 docs の正準形は両側 span_id (snake_case)。launch blog は Logs 側を l.spanId (camelCase) と書くが、docs 経由では span_id で揃える
• l.json_payload.agent_thoughts — JSON payload は JSON_VALUE で取り出す

Linked Dataset は Observability API の Link リソース (projects.locations.buckets.datasets.links) で表現されます。

projects/{PROJECT_ID}/locations/{LOCATION}/buckets/{BUCKET_ID}/datasets/{DATASET_ID}/links/{LINK_ID}

bigquery_dataset_id は Link 作成時に BigQuery 側に生成される dataset ID です。Trace では BUCKET_ID は通常 _Trace、Logs では _Default 等になります。

■構築方法

構築-前提条件 (API・課金・IAM)

gcloud services enable \
  monitoring.googleapis.com \
  observability.googleapis.com \
  logging.googleapis.com \
  cloudtrace.googleapis.com \
  bigquery.googleapis.com \
  --project="${PROJECT_ID}"

PRINCIPAL="user:platform-team@example.com"
for ROLE in roles/observability.editor roles/bigquery.user roles/logging.viewer; do
  gcloud projects add-iam-policy-binding "${PROJECT_ID}" \
    --member="${PRINCIPAL}" --role="${ROLE}"
done

構築-Log Bucket を Observability Analytics 化する

--enable-analytics フラグが「Observability Analytics 化」のスイッチです。--async 推奨 (backfill 起動を待たない)。

gcloud logging buckets update _Default \
  --location=global \
  --enable-analytics \
  --async \
  --project="${PROJECT_ID}"

gcloud logging buckets create app-prod-logs \
  --location=us \
  --enable-analytics \
  --retention-days=30 \
  --project="${PROJECT_ID}"

公式の制約:

• 再構成は不可 (upgrade はワンウェイ。後から analytics を外す操作は提供されていない)
• backfill (過去ログのインデックス化) には数日かかることがある。upgrade 直後は新規ログのみ即時クエリ可能
• linked dataset 経由のクエリでも BigQuery ingest / storage 課金は発生しない (BigQuery analysis charge のみ)
• field-level access control が設定された log view は Observability Analytics から直接クエリ不可 (Logs Explorer または linked BQ 経由のみ)

Console 操作の場合は Logs Storage ページを開き、_Default の行で Observability Analytics available カラムに表示される Upgrade ボタンをクリックして確定します。

構築-Trace の Observability Analytics 化

Cloud Trace 側は _Trace observability bucket が必要に応じて自動構成される仕組みで、Log Analytics のような明示的な「upgrade」操作はありません。Trace ingest が動いていれば PROJECT_ID.LOCATION._Trace.Spans._AllSpans をそのままクエリ対象にできます。空クエリの場合はまず _Trace の存在と Trace ingest の有効化を確認します (トラブルシュート表参照)。

gcloud beta observability buckets list \
  --location=global \
  --project="${PROJECT_ID}"

Trace の bucket ID は _Trace (固定)、dataset ID は Spans (固定)、view ID は _AllSpans (デフォルト) です。

構築-Observability API による Bucket / View 管理

gcloud beta observability ファミリのコマンドで、ログ・トレースを横断する Bucket / View / Dataset Link を CLI で管理できます (GA は API のみ。CLI は beta)。

gcloud beta observability buckets list --location=us --project="${PROJECT_ID}"
gcloud beta observability buckets views list \
  --bucket=_Default --location=us --project="${PROJECT_ID}"

gcloud beta observability buckets create my-obs-bucket \
  --location=us --project="${PROJECT_ID}"

gcloud beta observability buckets views create errors-only \
  --bucket=_Default \
  --location=us \
  --filter='severity >= "ERROR"' \
  --project="${PROJECT_ID}"

view は IAM の付与単位でもあります (roles/observability.viewAccessor を view 粒度で付与可能)。

構築-Linked BigQuery Dataset の作成

Log Bucket の場合、Cloud Logging の薄いラッパが最短です。

gcloud logging links create app_prod_logs_ds \
  --bucket=app-prod-logs \
  --location=us \
  --project="${PROJECT_ID}"

• LINK_ID (例: app_prod_logs_ds) がそのまま BigQuery 上の dataset 名になる
• dataset 名なので英数字 + アンダースコア、プロジェクト内ユニーク、100 文字以内
• Analytics 有効なバケットでなければ link は作れない

Trace は gcloud beta observability 経由で、位置引数に完全修飾 link resource name を渡して作成します。

gcloud beta observability buckets datasets links create \
  projects/${PROJECT_ID}/locations/us/buckets/_Trace/datasets/Spans/links/trace_spans_ds

REST API でも同じです (projects.locations.buckets.datasets.links.create)。

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://observability.googleapis.com/v1/projects/${PROJECT_ID}/locations/us/buckets/_Trace/datasets/Spans/links?linkId=trace_spans_ds" \
  -d '{"description": "Linked BigQuery dataset for Trace Spans (us)"}'

作成後、BigQuery 側には ${PROJECT_ID}.trace_spans_ds._AllSpans として linked dataset 上のビューが現れ、BigQuery Studio や SQL アラートポリシーから直接クエリできます (BigQuery 側からのクエリ path は dataset 名 trace_spans_ds + view 名 _AllSpans です)。

重要: SQL ベースのアラートポリシーは Observability bucket 内のビューを直接は参照できません。SQL アラート化したい場合は必ず linked dataset 経由で投げます。

構築-必要 IAM ロール早見表

構築-OpenTelemetry SDK でテレメトリを投入する

Observability Analytics の SQL ペイロードを充実させるための上流は OpenTelemetry です。エージェント観測では「OTel attribute を lower-case の dot 区切りで揃えるか」が後段の SQL JOIN の取りやすさを決めます。

pip install \
  opentelemetry-api opentelemetry-sdk \
  opentelemetry-exporter-gcp-trace \
  opentelemetry-exporter-gcp-logging \
  opentelemetry-instrumentation

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.cloud_trace import CloudTraceSpanExporter
from opentelemetry.sdk.resources import Resource

resource = Resource.create({
    "service.name": "agent-orchestrator",
    "service.version": "1.4.0",
})

provider = TracerProvider(resource=resource)
provider.add_span_processor(BatchSpanProcessor(CloudTraceSpanExporter()))
trace.set_tracer_provider(provider)

tracer = trace.get_tracer(__name__)

with tracer.start_as_current_span("Agent.executeTool") as span:
    span.set_attribute("agent.tool.name", "search_web")
    span.set_attribute("agent.tool.version", "2.1")
    span.set_attribute("agent.session.id", session_id)

ポイント:

• service.name は resource.attributes に入り、SQL 側で JSON_VALUE(resource.attributes, '$."service.name"') で参照できる
• カスタム属性は agent.tool.name のように lower-case + dot 区切り にしておくと OTel semantic conventions に揃う
• ログ側にも同じ trace_id / span_id を埋めると _Default._AllLogs と _Trace.Spans._AllSpans の JOIN が成立する
• GKE / Cloud Run / Cloud Functions のマネージド計装を有効化すると HTTP/gRPC span が自動取得される

■利用方法

利用-必須パラメータ早見表

利用-Observability Analytics コンソールの UI

1. Query Builder — メニュー駆動で field 選択 → 集計 → group by を組み立てる
2. SQL Editor — そのまま SQL を書く。Builder ⇄ SQL は切替可能
3. Run Query — 実行ボタン
4. Results Table — 実行結果のテーブル表示
5. Chart — 結果から折れ線/棒/分布チャートを生成
6. Save to Dashboard — Cloud Monitoring の Custom Dashboard に保存
7. Settings > Run in BigQuery — クエリを BigQuery 実行エンジンに切替

利用-SQL クエリ例 (Logs only)

ログを全件取得:

SELECT
  timestamp, severity, resource.type, log_name,
  text_payload, proto_payload, json_payload
FROM `PROJECT_ID.LOCATION._Default._AllLogs`
LIMIT 1000

時間粒度 + ステータスごとに集計:

SELECT
  TIMESTAMP_TRUNC(timestamp, HOUR) AS hour,
  JSON_VALUE(json_payload.status) AS status,
  COUNT(*) AS count
FROM `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`
WHERE json_payload IS NOT NULL
  AND JSON_VALUE(json_payload.status) IS NOT NULL
GROUP BY hour, status
ORDER BY hour ASC

URL ごとの平均 HTTP レイテンシ:

SELECT
  JSON_VALUE(labels.checker_location) AS location,
  AVG(http_request.latency.seconds) AS secs,
  http_request.request_url
FROM `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`
WHERE http_request IS NOT NULL
  AND http_request.request_method = 'GET'
GROUP BY http_request.request_url, location
ORDER BY location
LIMIT 100

利用-SQL クエリ例 (Traces only)

サービス別の p50/p95/p99:

SELECT
  COALESCE(
    JSON_VALUE(resource.attributes, '$."service.name"'),
    JSON_VALUE(attributes,          '$."service.name"')
  ) AS service_name,
  COUNT(*)                                                    AS span_count,
  APPROX_QUANTILES(duration_nano, 100)[OFFSET(50)]            AS p50_duration_nano,
  APPROX_QUANTILES(duration_nano, 100)[OFFSET(95)]            AS p95_duration_nano,
  APPROX_QUANTILES(duration_nano, 100)[OFFSET(99)]            AS p99_duration_nano,
  COUNTIF(status.code = 2)                                    AS error_count
FROM `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
WHERE start_time > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 DAY)
GROUP BY service_name
ORDER BY span_count DESC

利用-SQL クエリ例 (Logs と Traces の JOIN)

trace フィールドは projects/<pid>/traces/<trace_id> 形式なので末尾を抽出して trace_id と突き合わせます。公式 docs の正準形は両側 span_id (snake_case) で REGEXP_EXTRACT を使う形です。

SELECT
  T.trace_id, T.span_id, T.name, T.start_time, T.duration_nano,
  L.log_name, L.severity, L.json_payload
FROM `PROJECT_ID.LOCATION._Trace.Spans._AllSpans` AS T
JOIN `PROJECT_ID.LOCATION._Default._AllLogs`      AS L
  ON T.span_id  = L.span_id
 AND T.trace_id = REGEXP_EXTRACT(L.trace, r'/([^/]+)$')
WHERE T.duration_nano > 1000000
LIMIT 10

launch blog のサンプルは L.spanId (camelCase) と SPLIT(L.trace, '/')[SAFE_OFFSET(3)] の組合せを使います。動作は同じですが、公式 docs に揃える場合は上記正準形を採用します。span_id は globally unique ではないため、JOIN には trace_id も必ず併用します。

利用-エージェント観測 SQL (起点 Pick の AI agent tool optimization)

ツール別の失敗率と P95 レイテンシをランキング:

SELECT
  JSON_VALUE(attributes, '$."agent.tool.name"')                       AS tool_name,
  COUNT(span_id)                                                      AS total_calls,
  SAFE_DIVIDE(COUNTIF(status.code = 2), COUNT(span_id)) * 100         AS failure_rate_pct,
  APPROX_QUANTILES(duration_nano / 1000000, 100)[OFFSET(95)]          AS p95_latency_ms
FROM `YOUR_PROJECT_ID.us._Trace.Spans._AllSpans`
WHERE name = 'Agent.executeTool'
  AND start_time BETWEEN TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY)
                     AND CURRENT_TIMESTAMP()
GROUP BY tool_name
ORDER BY failure_rate_pct DESC, p95_latency_ms DESC
LIMIT 10

flaky tool の失敗時に agent の思考ログと LLM プロンプトを引き出す:

SELECT
  t.name                                                  AS tool_name,
  l.timestamp,
  JSON_VALUE(l.json_payload.agent_thoughts)               AS agent_reasoning,
  JSON_VALUE(l.json_payload.llm_prompt)                   AS prompt_sent_to_llm
FROM `YOUR_PROJECT_ID.us._Trace.Spans._AllSpans` t
JOIN `YOUR_PROJECT_ID.us._Default._AllLogs`     l
  ON t.trace_id = REGEXP_EXTRACT(l.trace, r'/([^/]+)$')
 AND t.span_id  = l.span_id
WHERE t.name = 'Agent.executeTool'
  AND JSON_VALUE(t.attributes, '$."agent.tool.name"') = 'NameOfFlakyTool'
  AND t.status.code = 2
  AND l.severity = 'ERROR'

顧客別レイテンシ影響 (ビジネス相関):

SELECT
  JSON_VALUE(l.json_payload.customer_id)                             AS customer_id,
  AVG(t.duration_nano / 1000000)                                     AS avg_latency_ms,
  APPROX_QUANTILES(t.duration_nano / 1000000, 100)[OFFSET(95)]       AS p95_latency_ms,
  COUNT(t.span_id)                                                   AS total_requests
FROM `YOUR_PROJECT_ID.us._Trace.Spans._AllSpans` AS t
JOIN `YOUR_PROJECT_ID.us._Default._AllLogs`     AS l
  ON t.trace_id = REGEXP_EXTRACT(l.trace, r'/([^/]+)$')
 AND t.span_id  = l.span_id
WHERE t.start_time BETWEEN TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 DAY)
                       AND CURRENT_TIMESTAMP()
  AND t.kind.name = 'SPAN_KIND_SERVER'
  AND JSON_VALUE(l.json_payload.customer_id) IS NOT NULL
GROUP BY customer_id
ORDER BY p95_latency_ms DESC
LIMIT 10

利用-Pipe syntax 例

GoogleSQL の pipe syntax (|> 演算子) もそのまま使えます。

FROM `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
|> WHERE start_time > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 HOUR)
|> EXTEND JSON_VALUE(attributes, '$."agent.tool.name"') AS tool_name,
          duration_nano / 1000000                       AS duration_ms
|> AGGREGATE COUNT(*)                                   AS calls,
             APPROX_QUANTILES(duration_ms, 100)[OFFSET(95)] AS p95_ms
   GROUP BY tool_name
|> ORDER BY p95_ms DESC
|> LIMIT 10

利用-BigQuery Studio から直接クエリ (linked dataset 経由)

Linked dataset を作っておくと、BigQuery Studio / Looker Studio / dbt / Connected Sheets などから「ふつうの BigQuery テーブル」として参照できます。

bq query --nouse_legacy_sql \
  'SELECT name, COUNT(*) AS n
   FROM `my-prod-project.trace_spans_ds._AllSpans`
   WHERE start_time > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 HOUR)
   GROUP BY name ORDER BY n DESC LIMIT 20'

linked dataset のメリット:

• 業務系の BigQuery テーブル との JOIN が可能
• BigQuery slot reservation が効く
• SQL ベースの Alerting Policy を貼れる
• BigQuery Studio の Notebook / Saved Queries / Scheduled Queries が使える

■運用

運用-クエリ実行・結果のダッシュボード化

• クエリは Google Cloud console の Observability > Analytics から実行。結果はテーブルと chart で同時表示され、そのまま dashboard に保存できます
• 保存先 dashboard は Cloud Monitoring custom dashboard
• 同じクエリを BigQuery Studio で開きたい場合は、linked dataset を作成してから "Open in BigQuery" → BigQuery 上で notebook 化・Looker Studio 連携・スケジュールクエリ化が可能
• ダッシュボード化の単位:
  • アドホック調査 → Observability Analytics の "Save as chart" だけで十分
  • 定型運用 KPI → linked dataset 経由で BigQuery scheduled query にし、物化テーブルに落として Looker Studio / Grafana に繋ぐ

運用-SQL ベース alerting policy (linked dataset 経由のみ)

重要制約: Observability Analytics の view は alerting policy から直接クエリできません。SQL ベース alerting を組むには linked BigQuery dataset を介す必要があります。

gcloud beta observability buckets datasets links create \
  projects/PROJECT_ID/locations/us/buckets/_Trace/datasets/Spans/links/LINK_ID

注意点:

• alerting policy が使う SQL は BigQuery engine (reserved slots) での実行が前提。VPC SC 環境では BigQuery Enterprise Edition が必要
• linked dataset 経由でも、SQL は scheduled evaluation モデル。秒オーダの即時 alert には不向きで、通常 metric (log-based metric) を併用する
• alert 用クエリは time-range selector ではなく WHERE 句で start_time 範囲を絞る (alerting は selector を持たない)

運用-データ保持期間 / リテンション設定

• ログのリテンションは log bucket 単位。デフォルト _Default は 30 日、_Required は 400 日固定
• Trace は _Trace バケットに集約され、既定 30 日。長期保持は retentionDays を伸ばすことで設定可能 (上限値は要一次確認、30 日超は 長期保持課金)
• Observability Analytics への upgrade は bucket 単位。upgrade 直後は backfill が走り数時間〜数日かかる
• 長期保持を BigQuery 側で持つ場合は linked dataset を起点に scheduled query で集計テーブルに落とすのが安価

gcloud logging buckets update _Default \
  --location=global \
  --retention-days=90

運用-クエリコスト監視

• linked dataset 自体には ingest / storage コストはかからない (ログは observability bucket に常駐)
• ただし クエリ実行時には BigQuery on-demand pricing が課金される。reserved slots を使うなら定額
• コストドライバの 9 割は partition pruning が効いているか。time-range selector または timestamp / start_time 範囲フィルタが無いと 全期間 full scan になる

SELECT user_email, query, total_bytes_billed,
  ROUND(total_bytes_billed / POW(1024,4) * 6.25, 4) AS estimated_usd
FROM `region-us`.INFORMATION_SCHEMA.JOBS_BY_PROJECT
WHERE creation_time > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY)
  AND statement_type = 'SELECT'
  AND referenced_tables[SAFE_OFFSET(0)].dataset_id LIKE '%Default%'
ORDER BY total_bytes_billed DESC
LIMIT 20;

運用-監査・アクセスログ

• Observability Analytics へのアクセスは Cloud Audit Logs (Data Access logs) に記録される (デフォルト無効)
• observability.googleapis.com と logging.googleapis.com の Data Access ログを有効化しておく
• 誰がどのログビューに SQL を投げたかは bigquery.googleapis.com/data_access の Job 実行ログを linked dataset でクエリすると追える (BigQuery エンジン経由のみ)

■ベストプラクティス

ベスト-エージェント観測のためのスキーマ設計

エージェントを SRE 視点で観測する場合、SQL JOIN が成立するスキーマ設計が前提です。

• 理由ログを jsonPayload の構造化フィールドに格納: agent_thoughts / llm_prompt / tool_name / tool_args / customer_id を文字列連結しない
• trace_id / span_id を必ずログに付与: OpenTelemetry SDK を使うと自動で logging.googleapis.com/trace と logging.googleapis.com/spanId が入る
• trace.attributes をエージェント語彙で標準化: agent.tool.name, agent.session_id, agent.model.name のような agent.* ネームスペースを決める。OTel Semantic Conventions の GenAI module (gen_ai.*) に揃えると将来安全
• GenAI semantic conventions の代表属性: gen_ai.request.model (使用モデル) / gen_ai.request.temperature / gen_ai.usage.input_tokens / gen_ai.usage.output_tokens / gen_ai.response.id / gen_ai.response.finish_reasons を span.set_attribute で必ず attach すると、token コスト × 顧客 × モデルの SQL 集計が標準形で書ける (source of truth は OpenTelemetry GenAI semantic conventions の専用リポジトリに移動済みで、属性名は今後変わる可能性があります)
• span name を行動単位で命名: Agent.executeTool / Agent.callLLM / Agent.planStep のように動詞 + 名詞
• 失敗の status.code = 2 を必ず立てる: 起点 Blog の P95 / failure rate 計算は全部これに依存する

ベスト-コスト最適化 (クエリ書き方の鉄則)

SELECT
  resource.labels.service_name AS service,
  APPROX_QUANTILES(duration_nano / 1000000, 100)[OFFSET(95)] AS p95_ms,
  COUNTIF(status.code = 2) AS errors
FROM `PROJECT.us._Trace.Spans._AllSpans`
WHERE start_time BETWEEN @from_ts AND @to_ts
  AND CONTAINS_SUBSTR(name, 'Agent.')
GROUP BY service
ORDER BY p95_ms DESC
LIMIT 50;

ベスト-LLM token 使用量 × 顧客のコスト相関

GenAI semantic conventions に従い gen_ai.usage.input_tokens / gen_ai.usage.output_tokens / gen_ai.request.model を span 属性に詰めておけば、モデル単価テーブルを crm.model_pricing のような業務テーブルに置いて JOIN するだけで「顧客あたり LLM コスト」を出せます。

WITH usage AS (
  SELECT
    JSON_VALUE(l.json_payload.customer_id)                            AS customer_id,
    JSON_VALUE(t.attributes, '$."gen_ai.request.model"')              AS model,
    SUM(CAST(JSON_VALUE(t.attributes, '$."gen_ai.usage.input_tokens"')  AS INT64)) AS in_tokens,
    SUM(CAST(JSON_VALUE(t.attributes, '$."gen_ai.usage.output_tokens"') AS INT64)) AS out_tokens
  FROM `PROJECT.us._Trace.Spans._AllSpans` t
  JOIN `PROJECT.us._Default._AllLogs` l
    ON t.trace_id = REGEXP_EXTRACT(l.trace, r'/([^/]+)$')
   AND t.span_id  = l.span_id
  WHERE t.name = 'Agent.callLLM'
    AND t.start_time > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 DAY)
  GROUP BY customer_id, model
)
SELECT u.customer_id, u.model,
  u.in_tokens, u.out_tokens,
  ROUND(u.in_tokens / 1e6 * p.input_usd_per_mtoken
      + u.out_tokens / 1e6 * p.output_usd_per_mtoken, 4) AS cost_usd
FROM usage u
JOIN `PROJECT.crm.model_pricing` p USING (model)
ORDER BY cost_usd DESC
LIMIT 20;

ベスト-BigQuery 業務データとの相関

• linked dataset を作れば observability の view と業務テーブルは 同じ BigQuery 上で JOIN 可能
• 鉄則: ログ側に business primary key を埋め込む。customer_id / invoice_id / order_id を jsonPayload か labels に出す

WITH agg AS (
  SELECT JSON_VALUE(l.json_payload.customer_id) AS customer_id,
    APPROX_QUANTILES(t.duration_nano/1e6, 100)[OFFSET(95)] AS p95_ms,
    COUNT(*) AS req
  FROM `PROJECT.us._Trace.Spans._AllSpans` t
  JOIN `PROJECT.us._Default._AllLogs` l
    ON t.trace_id = REGEXP_EXTRACT(l.trace, r'/([^/]+)$')
   AND t.span_id = l.span_id
  WHERE t.start_time > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 DAY)
  GROUP BY customer_id
)
SELECT a.customer_id, c.plan, c.mrr_usd, a.p95_ms, a.req
FROM agg a
JOIN `PROJECT.crm.customers` c USING (customer_id)
WHERE c.plan = 'pro'
ORDER BY a.p95_ms DESC
LIMIT 20;

PII を含むログ列は別データセット / column-level access で隔離し、JOIN 時のみ昇格できるサービスアカウントに権限を寄せます。

ベスト-マルチプロジェクト・マルチロケーション運用

• 1 つのクエリで参照する すべての view は同じ location でなければならない
• 例外: global location は他 location との JOIN が可能

gcloud logging sinks create to-aggregator \
  logging.googleapis.com/projects/AGGREGATOR/locations/us/buckets/all-prod \
  --log-filter='severity>=INFO' \
  --project=PROJECT_A

ベスト-field-level access control との互換性

• Cloud Logging field-level access が設定された log bucket は、Observability Analytics から直接クエリできない
• 回避策:
  • 機微フィールドは 別 bucket に分離して書き込む (sink filter で振り分け)
  • メイン bucket では機微フィールドを ハッシュ化 or マスクしてから書き込む
  • 機微データのクエリだけ Logs Explorer / linked BigQuery (BQ 側 column-level security) を使う

ベスト-SLO / エラーバジェット計算を SQL で

WITH base AS (
  SELECT
    TIMESTAMP_TRUNC(start_time, HOUR) AS hour,
    COUNTIF(status.code = 2) AS bad,
    COUNT(*) AS total
  FROM `PROJECT.us._Trace.Spans._AllSpans`
  WHERE start_time > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 28 DAY)
    AND kind.name = 'SPAN_KIND_SERVER'
    AND CONTAINS_SUBSTR(name, 'api.')
  GROUP BY hour
)
SELECT
  SUM(total) AS requests,
  SUM(bad) AS errors,
  SAFE_DIVIDE(SUM(bad), SUM(total)) AS error_rate,
  1 - SAFE_DIVIDE(SUM(bad), SUM(total)) AS sli,
  SAFE_DIVIDE(
    SUM(bad) - SUM(total) * (1 - 0.995),
    SUM(total) * (1 - 0.995)
  ) AS budget_burn_ratio
FROM base;

multi-window multi-burn-rate (Google SRE Workbook) を実装する場合、上記を 1h / 6h / 3d ウィンドウで並列計算し、budget_burn_ratio > 14.4 で alerting policy を組みます。

■トラブルシューティング

症状 → 原因 → 対処

切り分けの定石

1. gcloud logging buckets describe で対象 bucket の状態確認 (analyticsEnabled: true / lifecycleState: ACTIVE)
2. location を gcloud logging views list --bucket=... で確認。クエリ対象が同一 location か
3. linked dataset の有無 を gcloud logging links list --bucket=... --location=... で確認
4. IAM 不足 は gcloud projects get-iam-policy PROJECT --flatten="bindings[].members" で対象アカウントの全ロールを列挙
5. クエリの実コスト は BigQuery INFORMATION_SCHEMA.JOBS の total_bytes_billed を見る。dry-run (bq query --dry_run) で事前確認

■まとめ

Observability Analytics は 2026-05-26 GA の Cloud Trace クエリと Observability API、6-24 launch blog のリネームを通じて、Cloud Logging と Cloud Trace を BigQuery SQL で in-place に束ねる統合分析基盤として位置づけ直されました。エージェント運用では「tool failure rate / P95 latency / 思考ログと trace の JOIN / 顧客別影響」を 1 つの SQL 言語で表現でき、観測スキーマを SQL 集計前提に設計しておくと評価基盤を別建てせずに済みます。

本記事が少しでも参考になった、あるいは改善点などがあれば、ぜひリアクションやコメント、SNS でのシェアをいただけると励みになります！

■参考リンク

概要・launch

• Query logs and traces with SQL in Observability Analytics (launch blog, 2026-06-24)
• Stackdriver release notes
• Cloud Trace release notes

構造・データ

• Query and analyze telemetry with Observability Analytics (overview)
• Cloud Logging LogEntry REST reference
• Observability API: projects.locations.buckets.datasets.links
• Cloud Trace: Export to BigQuery (Span schema source)

構築・利用

• Cloud Logging Log Analytics
• Cloud Logging: Configure log buckets
• Cloud Logging: Analyze logs with Observability Analytics
• Cloud Trace: Linked BigQuery dataset
• Cloud Trace: Analytics samples
• Cloud Trace overview
• Sample SQL queries (Stackdriver)
• Observability Analytics samples (GitHub)

運用・ベストプラクティス

• Stackdriver pricing
• BigQuery on-demand pricing
• Google SRE Workbook (multi-window multi-burn-rate alerting)
• OpenTelemetry GenAI Semantic Conventions

競合・比較

• Datadog Trace Queries docs
• Honeycomb query examples for traces
• Grafana Tempo TraceQL documentation