OTLP ログを Telemetry API に書き込む

このドキュメントでは、Telemetry（OTLP）API のロギングエンドポイント telemetry.googleapis.com に OTLP ログを直接送信する方法と、取り込まれたログエントリを Cloud Logging で表示する方法について説明します。

始める前に

このセクションでは、Telemetry API を使用するための環境を設定する方法について説明します。

Google Cloud プロジェクトを選択または作成する

この例では、 Google Cloud プロジェクトを選択します。 Google Cloud プロジェクトが存在しない場合は作成します。

Google Cloud アカウントにログインします。 Google Cloudを初めて使用する場合は、アカウントを作成して、実際のシナリオでの Google プロダクトのパフォーマンスを評価してください。新規のお客様には、ワークロードの実行、テスト、デプロイができる無料クレジット $300 分を差し上げます。

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

`gcloud` のご設定のお願い

gcloud ツールは Google Cloud CLI に含まれています。インストールの詳細については、Google Cloud CLI コンポーネントの管理をご覧ください。インストールされている gcloud CLI コンポーネントを確認するには、次のコマンドを実行します。

gcloud components list

使用するように gcloud CLI を構成するには、PROJECT_ID 変数をGoogle Cloud プロジェクトの ID に置き換えてから、次のコマンドを実行します。

export GOOGLE_CLOUD_PROJECT=PROJECT_ID

gcloud auth login
gcloud config set project PROJECT_ID

API を有効にする

Google Cloud プロジェクトで Cloud Logging API と Telemetry API を有効にします。テレメトリー API（telemetry.googleapis.com）に特に注意してください。この API を初めて使用する可能性があります。

次のコマンドの出力に API が表示される場合、それらの API はすでに有効になっています。

gcloud services list

いずれかの API が有効になっていない場合は、対応するコマンドを実行します。

gcloud services enable logging.googleapis.com
gcloud services enable telemetry.googleapis.com

ログを書き込む権限を取得する

テレメトリー API にログを書き込み、作成されたログエントリを表示するために必要な権限を取得するには、プリンシパルに対する次の IAM ロールを付与するよう管理者に依頼してください。

ログ閲覧者（roles/logging.viewer）
ログ書き込み（roles/logging.logWriter）

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

Telemetry API を使用して OTLP ログを書き込む

このセクションでは、curl ユーティリティを使用して OTLP 形式のログレコードを作成し、そのレコードを Telemetry API に送信する方法について説明します。

OTLP ログを作成する

OTLP 形式のログレコードを含む JSON ファイルを作成します。次のタブには、非常に単純なログレコードと、より複雑なマルチログレコードが含まれています。いずれかを選択するか、両方を連続して送信できます。

シンプルな OTLP ログ

{
  "resourceLogs": [
    {
      "resource": {
        "attributes": [
          {"key": "gcp.project_id", "value": {"stringValue": "PROJECT_ID"}},
          {"key": "cloud.platform", "value": {"stringValue": "gcp_compute_engine"}},
          {"key": "zone", "value": {"stringValue": "us-central1"}},
          {"key": "instance_id", "value": {"stringValue": "12345"}},
        ]
      },
      "scopeLogs": [
      {
        "logRecords": [
          { "eventName": "otlp-test-log",
            "body": { "stringValue": "This is a trivial log message." },
          }
        ]
      }
      ]
    }
  ]
}

より複雑な OTLP ログ

{
  "resourceLogs": [
    {
      "resource": {
        "attributes": [
          {"key": "gcp.project_id", "value": {"stringValue": "PROJECT_ID"}},
          {"key": "cloud.platform", "value": {"stringValue": "gcp_compute_engine"}},
          {"key": "zone", "value": {"stringValue": "us-central1"}},
          {"key": "instance_id", "value": {"stringValue": "12345"}},
        ]
      },
      "scopeLogs": [
      {
        "logRecords": [
          { "eventName": "otlp-test-log",
            "severityText": "INFO",
            "body": { "stringValue": "This is an informational message." },
            "attributes": [
              {"key": "string.attribute",
               "value": { "stringValue": "Here's some general info."}},
              {"key": "int.attribute",
               "value": { "intValue": "666"}},
              {"key": "double.attribute",
               "value": { "doubleValue": "3.14159"}},
              {"key": "boolean.attribute",
               "value": { "boolValue": true}},
            ]
          },
          { "eventName": "otlp-test-log",
            "severityText": "DEBUG",
            "body": { "stringValue": "This is a debug message." },
            "attributes": [
              {"key": "string.attribute",
               "value": { "stringValue": "Here's some debug info."}},
              {"key": "int.attribute",
               "value": { "intValue": "42"}},
              {"key": "double.attribute",
               "value": { "doubleValue": "6373.392"}},
              {"key": "boolean.attribute",
               "value": { "boolValue": false}},
             ]
          }
        ]
      }
      ]
    }
  ]
}

いずれかのタブから JSON コンテンツをコピーしてファイルに保存します。

これらの JSON の例では、どちらも gce_instance モニタリング対象リソースタイプに対して書き込まれる Cloud Logging ログエントリが生成されます。scopedLogs 配列内の各 logRecord 項目は、OTLP ログレコードの eventName フィールドの値で名前が付けられたログ内の個別の Cloud Logging ログエントリになります。OTLP ログが Logging ログエントリにマッピングされる方法の詳細については、以下をご覧ください。

ログを Telemetry API に送信する

OTLP_LOG_JSON_FILE 変数を作成したファイルの名前に置き換えたら、次の curl コマンドを使用して、ファイルの内容を Telemetry API のロギングエンドポイント https://telemetry.googleapis.com/v1/logs に投稿します。

curl -i -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" -H "X-Goog-User-Project: ${PROJECT_ID}" \
-d @OTLP_LOG_JSON_FILE \
"https://telemetry.googleapis.com/v1/logs"

JSON ログレコードのファイルを複数作成する場合は、curl コマンドの OTLP_LOG_JSON_FILE 変数を必ず変更してください。

curl コマンドは一連のメッセージを生成し、成功した場合は空のレスポンス（{}）を生成します。出力は次のようになります。

HTTP/2 200
x-google-esf-cloud-client-params: backend_service_name: "telemetry.googleapis.com" backend_fully_qualified_method: "opentelemetry.proto.collector.logs.v1.LogsService.Export"
[...]
x-google-gfe-response-code-details-trace: response_code_set_by_backend
x-google-gfe-response-body-transformations: gunzipped,chunked
x-google-shellfish-status: CA0gBEBG
x-google-gfe-version: 2.970.1
alt-svc: h3=":443"; ma=2592000,h3-29=":443"; ma=2592000
accept-ranges: none

{}

取り込まれた OTLP ログを表示する

OTLP ログから生成されたログエントリは、ログエクスプローラや Observability Analytics などの Cloud Logging ツールを使用して表示できます。以降のセクションでは、次の方法でログエントリを表示する方法について説明します。

gcloud CLI
ログエクスプローラ

`gcloud` を使用してログを表示する

作成したログエントリを取得するには、gcloud logging read コマンドを使用します。次のコマンドは、出力を、過去 5 分間に書き込まれた otlp-test-log ログのログエントリに制限します。

gcloud logging read "LOG_ID(otlp-test-log)" --freshness=5m --format=json

サンプル OTLP ログに対応するログエントリは次のようになります。

シンプルなログエントリ

[
  {
    "insertId": "1yt9bu7a0",
    "logName": "projects/PROJECT_ID/logs/otlp-test-log",
    "otel": {
      "resource": {
        "attributes": {
          "cloud.platform": "gcp_compute_engine",
          "gcp.project_id": "PROJECT_ID",
          "instance_id": "12345",
          "zone": "us-central1"
        }
      }
    },
    "receiveTimestamp": "2026-03-18T20:17:00.128801819Z",
    "resource": {
      "labels": {
        "instance_id": "12345",
        "project_id": "PROJECT_ID",
        "zone": "us-central1"
      },
      "type": "gce_instance"
    },
    "textPayload": "This is a trivial log message.",
    "timestamp": "2026-03-18T20:17:00.128801819Z"
  }
]

より複雑なログエントリ

[
  {
    "insertId": "1aw7fsja1",
    "labels": {
      "boolean.attribute": "false",
      "double.attribute": "6373.39",
      "int.attribute": "42",
      "string.attribute": "Here's some debug info."
    },
    "logName": "projects/PROJECT_ID/logs/otlp-test-log",
    "otel": {
      "resource": {
        "attributes": {
          "cloud.platform": "gcp_compute_engine",
          "gcp.project_id": "PROJECT_ID",
          "instance_id": "12345",
          "zone": "us-central1"
        }
      }
    },
    "receiveTimestamp": "2026-03-16T17:11:19.461096569Z",
    "resource": {
      "labels": {
        "instance_id": "12345",
        "project_id": "PROJECT_ID",
        "zone": "us-central1"
      },
      "type": "gce_instance"
    },
    "severity": "DEBUG",
    "textPayload": "This is a debug message.",
    "timestamp": "2026-03-16T17:11:19.461096569Z"
  },
  {
    "insertId": "1aw7fsja0",
    "labels": {
      "boolean.attribute": "true",
      "double.attribute": "3.14159",
      "int.attribute": "666",
      "string.attribute": "Here's some general info."
    },
    "logName": "projects/PROJECT_ID/logs/otlp-test-log",
    "otel": {
      "resource": {
        "attributes": {
          "cloud.platform": "gcp_compute_engine",
          "gcp.project_id": "PROJECT_ID",
          "instance_id": "12345",
          "zone": "us-central1"
        }
      }
    },
    "receiveTimestamp": "2026-03-16T17:11:19.461096569Z",
    "resource": {
      "labels": {
        "instance_id": "12345",
        "project_id": "PROJECT_ID",
        "zone": "us-central1"
      },
      "type": "gce_instance"
    },
    "severity": "INFO",
    "textPayload": "This is an informational message.",
    "timestamp": "2026-03-16T17:11:19.461096569Z"
  }
]

ログエクスプローラを使用してログを表示する

Google Cloud コンソールで OTLP ログから作成されたログエントリを表示する手順は次のとおりです。

Google Cloud コンソールで、 [ログエクスプローラ] ページに移動します。
[ログエクスプローラ] に移動

検索バーを使用してこのページを検索する場合は、小見出しが [Logging] の結果を選択します。
OTLP ログを送信した Google Cloud プロジェクトを選択します。
[クエリ] ペインでクエリを入力します。このドキュメントのサンプルは、otlp-test-log という名前のログに書き込まれます。このログでエントリを検索するには、次のクエリを入力します。
```
LOG_ID(otlp-test-log)
```
[クエリを実行] をクリックします。

クリーンアップ

新しいプロジェクトを作成し、それが不要になった場合は、プロジェクトを削除して、 Google Cloud アカウントに課金されないようにします。

次のステップ

Telemetry API の詳細については、次のドキュメントをご覧ください。

API の概要では、ログ、指標、トレースの Telemetry API について説明します。
v1.logs は、ロギング用の Telemetry API エンドポイントについて説明し、OTLP ログレコードが Cloud Logging ログエントリとして取り込まれる方法に関する詳細情報を提供します。