本文档介绍了如何将 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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
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 日志记录文件，请务必更改 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 日志
您可以使用任何 Cloud Logging 工具（包括 Logs Explorer 和 Observability Analytics）查看 OTLP 日志生成的日志条目。以下部分介绍了如何使用以下工具查看日志条目：
使用 gcloud 查看日志
您可以使用 gcloud logging read 命令检索刚刚创建的日志条目。以下命令会将输出限制为 otlp-test-log 日志中在过去 5 分钟内写入的日志条目：
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 页面：
如果您使用搜索栏查找此页面，请选择子标题为 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 日志条目进行提取。