v1.logs 概览

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

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

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

当日志数据使用 Telemetry API 发送到您的项目时，此 数据必须采用与 OTLP 一致的格式。 Google Cloud 此数据的一般结构如下所示：

"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 库。

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 字段。