v1.logs 概览

本文档介绍了如何将使用 Telemetry (OTLP) API 发送到 Google Cloud 项目的日志数据映射到 Cloud Logging 结构。此 API 实现了 OpenTelemetry 协议。当您使用 otlphttp 导出器和 OpenTelemetry 收集器对应用进行插桩时，或者当您使用 OpenTelemetry SDK 时，可以将数据发送到此 API。

OpenTelemetry 是一个受 Google Cloud支持的开源项目，配备 Google Cloud工程师来确保支持注入和直观呈现遥测数据。

OTLP 格式日志数据的一般结构

使用 Telemetry API 将日志数据发送到 Google Cloud 时，这些数据必须采用与 OTLP 一致的格式。此数据的常规结构如下所示：

"resourceLogs": [
    {
      "resource": {
        "attributes": [...]
      },
      "scopeLogs": [
        {
          "logRecords": [...]
        }
      ]
    }
]

请注意，OpenTelemetry 会批量处理各个日志，每个日志都由 logRecord 结构表示，并包含有关这些日志来源的信息，这些信息由 resource 结构表示。

当 Google Cloud Observability 收到 resourceLogs 对象时，它会为每个 logRecord 构造一个 LogEntry。与 OTLP 将来源信息与一系列单独的日志进行批处理不同，每个 LogEntry 结构都包含有关日志来源和日志本身的信息。

如需详细了解 OTLP 格式的日志数据的结构，请参阅 OpenTelemetry logs.proto。

OTLP 格式的日志数据的处理方式

当您向 Telemetry API 发送 OTLP resourceLogs 结构时，Google Cloud Observability 会执行以下操作：

1. 系统会为每个 logRecord 创建一个 LogEntry。

   以下文档介绍了系统如何根据 OTLP 日志数据填充 LogEntry：

   • OTLP 日志记录到日志条目映射。
   • OTLP 属性到 Cloud Logging 资源类型的映射。

   由于每个 LogEntry 都包含有关相应 Cloud Logging 资源类型的信息，因此每个 LogEntry 可能大于相应的 OTLP logRecord。

   从 OTLP resourceLogs 结构转换为一系列 LogEntry 结构可能会造成数据丢失。也就是说，您可能无法从 LogEntry 结构转换为原始 resource 和 logRecord 字段。

2. LogEntry 由项目层次结构中的汇总接收器和项目中的接收器路由，其方式与使用 Cloud Logging API 将日志条目发送到项目的方式完全相同。

最佳做法

在对应用进行插桩处理以将跟踪记录数据发送到Google Cloud 项目时，我们建议您使用将 OTLP 格式的数据写入收集器的导出器，收集器随后会将跟踪记录数据发送到 Telemetry API。在收集器中，仅指定根网址：

exporters:
  otlphttp:
    encoding: proto
    endpoint: https://telemetry.googleapis.com

OpenTelemetry 会检测数据类型，并根据需要自动附加 /v1/traces、/v1/metrics 或 /v1/logs。如需了解详情，请参阅 OTLP/HTTP 请求。

如需查看将跟踪记录或指标数据导出到 Telemetry API 的示例，请参阅以下文档：

• 基于收集器的插桩示例概览。
• OTLP 提取概览。

如果无法使用收集器，您可以使用包含进程内 OTLP 导出器的 OpenTelemetry 库，将遥测数据发送到 Telemetry API。如需了解如何直接导出跟踪记录数据，请参阅从 Cloud Trace 导出器迁移到 OTLP 端点。

身份验证

您必须为导出器配置将数据发送到 Google Cloud 项目所需的凭据。例如，使用收集器时，您通常会使用 googleclientauth 扩展程序通过 Google 凭据进行身份验证。

如需查看直接导出跟踪记录数据时进行身份验证的示例，请参阅配置身份验证。此示例说明了如何使用 Google Cloud应用默认凭证 (ADC) 配置导出器，以及如何向应用添加特定于语言的 Google Auth 库。

如需使用 Telemetry API 将遥测数据发送到您的 Google Cloud 项目，您还必须执行以下操作：

• 配置配额项目。如需了解详情，请参阅设置配额项目。

• 向用户或应用使用的服务账号授予以下 Identity and Access Management (IAM) 角色：

  • 配额项目上的 Service Usage Consumer 角色 (roles/serviceusage.serviceUsageConsumer)。
  • 项目的 Cloud Telemetry Writer 角色 (roles/telemetry.writer)。此角色可让您的应用写入日志、指标和跟踪记录数据。

Cloud Logging 和数据驻留

默认情况下，Cloud Logging 会将源自某个项目的日志条目路由到系统创建的日志存储桶。日志存储桶属于区域级资源。您可以更新默认日志接收器，以将日志条目发送到您选择的位置中的自定义日志存储桶。如需了解详情，请参阅区域化存储日志。

Cloud Logging 提供了可为组织和文件夹配置的设置。这些设置指定了系统创建的新日志存储桶的位置、这些日志存储桶是否使用客户管理的加密密钥 (CMEK)，以及默认日志接收器的配置。如需了解详情，请参阅对组织和文件夹的支持。

在何处查看注入的数据

您可以使用 Logs Explorer 和Observability Analytics页面查看日志数据。如需了解相关信息，请参阅以下内容：

• 查看和分析日志。
• 使用 SQL 查询和分析日志。

限制

本部分介绍了相关限制。还介绍了 Google Cloud Observability 如何处理某些类型的数据。

限制

说明	值	备注
每个 OTLP 请求的日志数量上限	8192	指 OTLP resourceLogs 结构中 logRecords 的数量上限。限制。
每个请求的大小上限	5 MiB	限制。
根据 OTLP 日志记录创建的 LogEntry 的大小上限	256 KiB	Cloud Logging 会在必要时截断或舍弃 OTLP 日志记录中的数据。限制。
属性键的长度上限	512 B	当 OTLP 日志记录转换为 LogEntry 时，超大的标签键会被截断。限制。
属性值的长度上限	64 KiB	OTLP 日志记录转换为 LogEntry 时，标签值过大。限制。
属性嵌套深度上限	20	当 OTLP 日志记录转换为 LogEntry 时，属性超出此限制的请求会被拒绝。
每分钟日志注入字节数上限	以下区域为 2.4 GB：asia-east1, asia-northeast1, asia-southeast1, asia-south1, europe-west1, europe-west2, europe-west3, europe-west4, us-central1, us-east4, us-west1。 所有其他区域为 300 MB。	配额。

行为

• 如果同时设置了 OpenTelemetry 严重级别编号和严重级别文本，系统会使用严重级别编号来确定 Cloud Logging 严重级别。如果 OTLP 记录不包含严重级别信息，则 Cloud Logging 严重级别会设置为 DEFAULT。

• 当 OTLP 记录包含重复的属性键时，系统会保留第一个键，并舍弃具有重复键的属性。

• 系统会将附加到日志记录的属性转换为字符串。如需查看示例，请参阅标签字段。

• 日志名称必须是网址安全的，否则在提取期间会进行网址编码。如需了解如何设置日志名称，请参阅如何设置 LogEntry 字段。

配额

如需了解与 Telemetry API 关联的配额，请参阅 Telemetry API 限制。