将 OTLP 日志写入 Telemetry API

本文档介绍了如何将 OTLP 日志直接发送到 Telemetry (OTLP) API 的日志记录端点 telemetry.googleapis.com，以及如何在 Cloud Logging 中查看注入的日志条目。

准备工作

本部分介绍了如何设置环境以使用 Telemetry API。

选择或创建 Google Cloud 项目

为此示例选择一个 Google Cloud 项目。如果您还没有项目，请创建一个： Google Cloud

登录您的 Google Cloud 账号。如果您是 Google Cloud的新用户，请创建一个账号，以评估我们的产品在实际场景中的表现。新客户还可以获得 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 项目标识符，然后运行以下命令。

export GOOGLE_CLOUD_PROJECT=PROJECT_ID

gcloud auth login
gcloud config set project PROJECT_ID

启用 API

在您的 Google Cloud 项目中启用 Cloud Logging API 和 Telemetry API。请特别注意 Telemetry API，telemetry.googleapis.com；此文档可能是您第一次遇到此 API。

如果 API 显示在以下命令的输出中，则表示它们已启用：

gcloud services list

如果任一 API 未启用，请运行相应的命令：

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

获取写入日志的权限

如需获得将日志写入 Telemetry API 并查看创建的日志条目所需的权限，请让您的管理员在您的正文上授予以下 IAM 角色：

Logs Viewer (roles/logging.viewer)
Logs Writer (roles/logging.logWriter)

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

使用 Telemetry API 写入 OTLP 日志

本部分介绍了如何创建 OTLP 格式的日志记录，以及如何使用 curl 实用程序将该记录发送到 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 项都会成为一个单独的 Cloud Logging 日志条目，该日志条目的名称与 OTLP 日志记录中 eventName 字段的值相同。如需详细了解如何将 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 日志记录文件，请务必更改 OTLP_LOG_JSON_FILE 变量在 curl 命令。

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 日志

您可以使用任何 Cloud Logging 工具（包括 Logs Explorer 和 Observability Analytics）查看 OTLP 日志生成的日志条目。以下部分介绍了如何使用以下工具查看日志条目：

gcloud CLI
Logs Explorer

使用 `gcloud` 查看日志

您可以使用 gcloud logging read 命令检索刚刚创建的日志条目。以下命令会将输出限制为 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"
  }
]

使用 Logs Explorer 查看日志

如需在 Google Cloud 控制台中查看从 OTLP 日志创建的日志条目，请执行以下操作：

在 Google Cloud 控制台中，前往 Logs Explorer 页面：
前往 Logs Explorer

如果您使用搜索栏查找此页面，请选择子标题为 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 日志条目。