Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

v1.logs 概览

本文档介绍了使用 Telemetry (OTLP) API 发送到 Google Cloud 项目的日志数据如何映射到 Cloud Logging 结构。此 API 实现了 OpenTelemetry Line Protocol。当您使用 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 会执行以下操作：

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

以下文档介绍了系统如何根据 OTLP 日志数据填充 LogEntry：
- OTLP 日志记录到日志条目的映射。
- OTLP 属性到 Cloud Logging 资源类型映射。
由于每个 LogEntry 都包含有关相应 Cloud Logging 资源类型的信息，因此每个 LogEntry 可能都比相应的 OTLP logRecord 大。

从 OTLP resourceLogs 结构到一系列 LogEntry 结构的转换可能会有损失。也就是说，您可能无法从 LogEntry 结构转换为原始的 resource 和 logRecord 字段。
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 项目，您还必须执行以下操作：

配置配额项目。如需了解详情，请参阅设置配额项目。
向应用使用的用户或服务账号授予相应配额项目的 Service Usage Consumer 角色 (roles/serviceusage.serviceUsageConsumer)。
为应用所使用的用户或服务账号授予项目中的以下角色：
- Logs Writer (roles/logging.logWriter)
- Monitoring Metric Writer (roles/monitoring.metricWriter)
- Cloud Telemetry Traces Writer (roles/telemetry.tracesWriter)

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