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 格式的日志数据的处理方式

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

  1. 对于每个 logRecord，系统都会创建一个 LogEntry。

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

    由于每个 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 导出器的 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 页面查看日志数据。如需了解相关信息，请参阅以下内容：

限制

本部分介绍了限制。此外，还介绍了 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时，系统会截断过大的标签值。限制。
属性嵌套的深度上限 5 当 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 限制。