配置 Logging 代理

本页面详细介绍了 Cloud Logging 代理的默认配置和自定义配置。

大多数用户无需阅读此页面。在以下情况下，请阅读本页面：

您有兴趣了解 Cloud Logging 代理配置的深入技术细节。
您想要更改 Cloud Logging 代理的配置。

默认配置

Logging 代理 google-fluentd 是 fluentd 日志数据收集器的修订版。Logging 代理附带默认配置；在大多数常见情况下，不需要其他配置。

在 Logging 代理的默认配置中，Logging 代理会将默认日志列表中包括的日志流式传输到 Cloud Logging。您可以将代理配置为流式传输更多日志；如需了解详情，请参阅本页面上的自定义 Logging 代理配置。

Logging 代理的工作原理。

Logging 代理使用 fluentd 输入插件从外部来源（例如磁盘上的文件）检索和拉取事件日志，或者使用该插件解析传入的日志记录。输入插件与代理捆绑在一起，或者可以单独安装为 Ruby gem；请参阅捆绑插件列表。

代理通过 fluentd 的内置 in_tail 插件在虚拟机实例上读取日志文件中所存储的日志记录。每个日志记录均转换为 Cloud Logging 的日志条目结构。每个日志记录的内容主要记录在日志条目的载荷中，但日志条目还包含 timestamp 和 severity 等标准元素。Logging 代理要求使用字符串格式标记来标记每个日志记录；所有查询和输出插件都与一组特定的标记匹配。日志名称通常遵循格式 projects/[PROJECT-ID]/logs/[TAG]。例如，以下日志名称包含标记 structured-log：

projects/my-sample-project-12345/logs/structured-log

输出插件将每个内部化的结构化消息转换为 Cloud Logging 中的日志条目。载荷会变为文本或 JSON 载荷。

本页面的以下部分详细介绍了默认配置。

默认配置定义

以下部分描述了 syslog 的默认配置定义、转发输入插件、第三方应用日志的输入配置（例如默认日志列表中的输入配置），以及我们的 Google Cloud fluentd 输出插件。

根配置文件位置

Linux：/etc/google-fluentd/google-fluentd.conf

此根配置文件也会导入 /etc/google-fluentd/config.d 文件夹中的所有配置文件。
Windows：C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf

如果您运行的 Logging 代理版本低于 v1-5，则位置为：C:\GoogleStackdriverLoggingAgent\fluent.conf

Syslog 配置

配置文件位置：/etc/google-fluentd/config.d/syslog.conf
说明：此文件包含用于将 syslog 指定为日志输入的配置。
请参阅配置代码库。

配置名称	类型	默认值	说明
`format`	字符串	`/^(?<message>(?<time>[^ ]\s[^ ]* [^ ]) .)$/`	syslog 的格式。
`path`	字符串	`/var/log/syslog`	syslog 文件的路径。
`pos_file`	字符串	`/var/lib/google-fluentd/pos/syslog.pos`	此日志输入的位置文件的路径。`fluentd` 会将上次读到的位置记录到此文件中。请参阅详细的 `fluentd` 文档。
`read_from_head`	布尔值	`true`	是否从文件开头而不是从文件底部开始读取日志。请参阅详细的 `fluentd` 文档。
`tag`	字符串	`syslog`	此日志输入的日志标记。

`in_forward` 输入插件配置

配置文件位置：/etc/google-fluentd/config.d/forward.conf
说明：此文件包含应用于 in_forward fluentd 输入插件的配置。in_forward 输入插件允许您通过 TCP 套接字传入日志。
请参阅此插件的详细 fluentd 文档和配置代码库。

配置名称	类型	默认值	说明
`port`	整数	`24224`	要监控的端口。
`bind`	字符串	`127.0.0.1`	要监控的绑定地址。默认情况下，仅接受来自 localhost 的连接。如需打开该地址，需要将此配置更改为 `0.0.0.0`。

第三方应用日志输入配置

配置文件位置：/etc/google-fluentd/config.d/[APPLICATION_NAME].conf
说明：此目录包含用于将第三方应用的日志文件指定为日志输入的配置文件。除 syslog.conf 和 forward.conf 之外，每个文件均表示一个应用（例如，apache.conf 表示 Apache 应用）。
请参阅配置代码库。

配置名称	类型	默认值	说明
`format`¹	字符串	因应用而异	日志的格式。请参阅详细的 `fluentd` 文档。
`path`	字符串	因应用而异	日志文件的路径。可以指定多个路径（以“,”分隔）。可以包含 * 和 strftime 格式，以动态添加/移除监视文件。请参阅详细的 `fluentd` 文档。
`pos_file`	字符串	因应用而异	此日志输入的位置文件的路径。`fluentd` 会将上次读到的位置记录到此文件中。请参阅详细的 `fluentd` 文档。
`read_from_head`	布尔值	`true`	是否从文件开头而不是从文件底部开始读取日志。请参阅详细的 `fluentd` 文档。
`tag`	字符串	因应用的名称而异。	此日志输入的日志标记。

¹ 如果您使用的是 <parse> Stanza，请使用 @type 来指定日志格式。

Google Cloud `fluentd` 输出插件配置

配置文件位置：
- Linux：/etc/google-fluentd/google-fluentd.conf
- Windows：C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf
  
  如果您运行的 Logging 代理版本低于 v1-5，则位置为：C:\GoogleStackdriverLoggingAgent\fluent.conf
说明：此文件包含用于控制 Google Cloud fluentd 输出插件行为的配置选项。
转到配置代码库。

配置名称	类型	默认值	说明
`buffer_chunk_limit`	字符串	`512KB`	随着日志记录的传入，那些无法足够快地写入下游组件的日志记录将被推送到区块队列中。此配置会设置每个区块的大小限制。默认情况下，我们保守地设置区块限制，以避免 Logging API 中每个写入请求超过建议的 5MB 区块大小。API 请求中的日志条目附带了所有其他元数据，可能会比原始日志大 5 - 8 倍。如果满足以下两个条件之一，则刷新缓冲区区块： 1. `flush_interval` 自动生效。 2. 缓冲区大小达到 `buffer_chunk_limit`。
`flush_interval`	字符串	`5s`	随着日志记录的传入，那些无法足够快地写入下游组件的日志记录将被推送到区块队列中。此配置设置多长时间之后我们必须刷新区块缓冲区。如果满足以下两个条件之一，则刷新缓冲区区块： 1. `flush_interval` 自动生效。 2. 缓冲区大小达到 `buffer_chunk_limit`。
`disable_retry_limit`	布尔值	`false`	对缓冲区区块刷新失败的重试次数强制执行限制。请参阅 `retry_limit`、`retry_wait` 和 `max_retry_wait` 中的详细规范。
`retry_limit`	整数	`3`	如果缓冲区区块刷新失败，则默认情况下 `fluentd` 会稍后重试。此配置设置在删除一个有问题的缓冲区区块之前要执行的重试次数。
`retry_wait`	整数	`10s`	如果缓冲区区块刷新失败，则默认情况下 `fluentd` 会稍后重试。此配置设置第一次重试之前的等待间隔（以秒为单位）。每次后续重试时，等待间隔将加倍（20 秒、40秒…），直到达到 `retry_ limit` 或 `max_retry_wait`。
`max_retry_wait`	整数	`300`	如果缓冲区区块刷新失败，则默认情况下 `fluentd` 会稍后重试。每次后续重试时，等待间隔将加倍（20 秒、40 秒…）。此配置设置最大等待间隔（以秒为单位）。如果等待间隔达到此限制，则停止加倍。
`num_threads`	整数	`8`	输出插件可以处理的同时刷新日志的次数。
`use_grpc`	布尔值	`true`	是否使用 gRPC 而非 REST/JSON 与 Logging API 通信。启用 gRPC 后，CPU 使用率通常会下降
`grpc_compression_algorithm`	枚举	`none`	如果使用 gRPC，则设置要使用的压缩架构。可以是 `none` 或 `gzip`。
`partial_success`	布尔值	`true`	是否支持日志提取部分成功。如果为 `true`，则整个集内的无效日志条目会被删除，并且有效日志条目会成功提取到 Logging API 中。如果为 `false`，则只要整个集合包含任何无效日志条目，系统就会删除整个集合。
`enable_monitoring`	布尔值	`true`	如果设置为 `true`，则 Logging 代理会导出内部遥测数据。如需了解详情，请参阅输出插件遥测。
`monitoring_type`	字符串	`opencensus`	监控的类型。支持的选项有 `opencensus` 和 `prometheus`。如需了解详情，请参阅输出插件遥测。
`autoformat_stackdriver_trace`	布尔值	`true`	如果设置为 `true`，则在结构化载荷字段 `logging.googleapis.com/trace` 的值与 ResourceTrace `traceId` 格式匹配的情况下将重新设置跟踪记录的格式。可以在本页面的结构化载荷中的特殊字段中找到自动设置格式的详细信息。

Monitoring 配置

输出插件遥测

enable_monitoring 选项控制 Google Cloud fluentd 输出插件是否收集其内部遥测数据。如果设置为 true，则 Logging 代理会跟踪请求发送至 Cloud Logging 的日志条目数，以及 Cloud Logging 成功提取的实际日志条目数。设置为 false 时，输出插件不会收集任何指标。

monitoring_type 选项用于控制代理如何公开此遥测数据。请参阅下面的指标列表。

设置为 prometheus 时，Logging 代理会在 Prometheus 端点上公开采用 Prometheus 格式的指标（默认情况下为 localhost:24231/metrics；如需详细了解如何自定义，请参阅 prometheus 和 prometheus_monitor 插件配置））。在 Compute Engine 虚拟机上，必须安装并运行 Monitoring 代理，才能将这些指标写入 Monitoring API。

当设置为 opencensus（从 v1.6.25 开始的默认值）时，Logging 代理会直接将其运行状况指标写入 Monitoring API。这需要向 Compute Engine 默认服务账号授予 roles/monitoring.metricWriter 角色，即使未安装 Monitoring 代理。

Monitoring 代理和 Logging 代理均以 opencensus 模式将以下指标写入 Monitoring API：

带有 version 标签的 agent.googleapis.com/agent/uptime：Logging 代理的正常运行时间。
带有 response_code 标签的 agent.googleapis.com/agent/log_entry_count：Logging 代理写入的日志条目计数。
带有 response_code 标签的 agent.googleapis.com/agent/log_entry_retry_count：Logging 代理写入的日志条目计数。
带有 response_code 标签的 agent.googleapis.com/agent/request_count：来自 Logging 代理的 API 请求计数。

代理指标页面对这些指标进行了更详细的介绍。

此外，输出插件会在 prometheus 模式下公开以下 Prometheus 指标：

带有 version 标签的 uptime：Logging 代理的正常运行时间。
带有 grpc 和 code 标签的 stackdriver_successful_requests_count：对 Logging API 的成功请求数。
带有 grpc 和 code 标签的 stackdriver_failed_requests_count：对 Logging API 的失败请求数，按错误代码细分。
带有 grpc 和 code 标签的 stackdriver_ingested_entries_count：Logging API 提取的日志条目数。
带有 grpc 和 code 标签的 stackdriver_dropped_entries_count：Logging API 拒绝的日志条目数。
带有 grpc 和 code 标签的 stackdriver_retried_entries_count：由于暂时性错误，Google Cloud fluentd 输出插件未能提取和进行了重试的日志条目数。

prometheus 和 prometheus_monitor 插件配置

配置文件位置：/etc/google-fluentd/google-fluentd.conf
说明：此文件包含用于控制 prometheus 和 prometheus_monitor 插件行为的配置选项。prometheus_monitor 插件监控 Fluentd 的核心基础架构。prometheus 插件会通过本地端口，以 Prometheus 格式公开指标，包括上述来自 prometheus_monitor 插件的指标和来自 google_cloud 插件的指标。如需了解详情，请访问 https://docs.fluentd.org/deployment/monitoring-prometheus。
转到配置代码库。

为了监控 Fluentd，内置 Prometheus http 指标服务器默认处于启用状态。您可以从配置中移除以下部分，以阻止此端点启动：

# Prometheus monitoring.
<source>
  @type prometheus
  port 24231
</source>
<source>
  @type prometheus_monitor
</source>

处理载荷

Logging 代理的默认配置下的大多数受支持日志都来自日志文件，并提取作为日志条目中的非结构化（文本）载荷。

唯一的例外是 in_forward 输入插件（此插件也会默认启用）仅接受结构化日志，还会将这些日志作为日志条目中的结构化 (JSON) 载荷提取出来。如需了解详情，请参阅本页面中的通过 in_forward 插件流式传输结构化 (JSON) 日志记录。

如果日志行是序列化 JSON 对象，并且启用了 detect_json 选项，此输出插件会将日志条目转换为结构化 (JSON) 载荷。默认情况下，在 App Engine 柔性环境和 Google Kubernetes Engine 中运行的虚拟机实例内会启用此选项。默认情况下，在 App Engine 标准环境中运行的虚拟机实例内不会启用此选项。通过启用的 detect_json 选项解析的任何 JSON 始终提取为 jsonPayload。

您可以自定义代理的配置，以支持从其他资源中提取结构化日志。如需了解详情，请参阅将结构化 (JSON) 日志记录流式传输到 Cloud Logging。

由自定义配置的 Logging 代理流式传输的日志记录载荷，可以是单个非结构化文本消息 (textPayload)，也可以是结构化 JSON 消息 (jsonPayload)。

结构化负载中的特殊字段

当 Logging 代理收到结构化日志记录时，它会将与下表匹配的任何键移动到 LogEntry 对象中的相应字段。否则，键会成为 LogEntry.jsonPayload 字段的一部分。这样可以设置 LogEntry 对象中的特定字段，即写入 Logging API 的内容。例如，如果结构化日志记录包含 severity 的键，则 Logging 代理将填充 LogEntry.severity 字段。

JSON 日志字段	`LogEntry` 字段	Cloud Logging 代理函数	示例值
`severity`	`severity`	Logging 代理尝试匹配各种常见严重性字符串，其中包括 Logging API 识别的 LogSeverity 字符串列表。	`"severity":"ERROR"`
`message`	`textPayload`（或 `jsonPayload` 的一部分）	日志浏览器中的日志条目行显示的消息。	`"message":"There was an error in the application."` 注意：如果在 Logging 代理移动其他特殊用途字段之后只留下了一个 message 字段并且 `detect_json` 未启用，则该 `message` 将保存为 `textPayload`，否则 `message` 仍保留在 `jsonPayload` 中。`detect_json` 不适用于 Google Kubernetes Engine 等代管式日志记录环境。如果您的日志条目包含异常堆栈轨迹，则应在此 `message` JSON 日志字段中设置异常堆栈轨迹，以便系统可以解析该异常堆栈跟踪并将其保存到 Error Reporting 之中。
`log`（仅限旧版 Google Kubernetes Engine）	`textPayload`	仅适用于旧版 Google Kubernetes Engine：如果在移动特殊用途字段后，只留下一个 `log` 字段，则该字段将保存为 `textPayload`。
`httpRequest`	`httpRequest`	采用 `LogEntry` `HttpRequest` 字段格式的结构化记录。	`"httpRequest":{"requestMethod":"GET"}`
与时间相关的字段	`timestamp`	如需了解详情，请参阅与时间相关的字段。	`"time":"2020-10-12T07:20:50.52Z"`
`logging.googleapis.com/insertId`	`insertId`	如需了解详情，请参阅 `LogEntry` 页面上的 `insertId`。	`"logging.googleapis.com/insertId":"42"`
`logging.googleapis.com/labels`	`labels`	此字段的值必须为结构化记录。如需了解详情，请参阅 `LogEntry` 页面上的 `labels`。	`"logging.googleapis.com/labels":` `{"user_label_1":"value_1","user_label_2":"value_2"}`
`logging.googleapis.com/operation`	`operation`	此字段的值也可用于日志浏览器对相关日志条目进行分组。如需了解详情，请参阅 `LogEntry` 页面上的 `operation`。	`"logging.googleapis.com/operation":` `{"id":"get_data","producer":"github.com/MyProject/MyApplication",` `"first":"true"}`
`logging.googleapis.com/sourceLocation`	`sourceLocation`	与日志条目关联的源代码位置信息（如果有）。如需了解详情，请参阅 `LogEntry` 页面上的 `LogEntrySourceLocation`。	`"logging.googleapis.com/sourceLocation":` `{"file":"get_data.py","line":"142","function":"getData"}`
`logging.googleapis.com/spanId`	`spanId`	与日志条目相关联的跟踪记录内的 Span ID。如需了解详情，请参阅 `LogEntry` 页面上的 `spanId`。	`"logging.googleapis.com/spanId":"000000000000004a"`
`logging.googleapis.com/trace`	`trace`	与日志条目关联的跟踪记录的资源名称（如果有）。如需了解详情，请参阅 `LogEntry` 页面上的 `trace`。	`"logging.googleapis.com/trace":"projects/my-projectid/traces/0679686673a"` 注意：如果未向 `stdout` 或 `stderr` 写入数据，此字段的值应设置为 `projects/[PROJECT-ID]/traces/[TRACE-ID]` 格式，以便日志浏览器和 Trace Viewer 可以使用此字段对日志条目进行分组，并且将日志条目与跟踪记录一起显示。如果 `autoformat_stackdriver_trace` 为 true，并且 `[V]` 与 ResourceTrace `traceId` 的格式相匹配，则 LogEntry `trace` 字段的值将是 `projects/[PROJECT-ID]/traces/[V]`。
`logging.googleapis.com/trace_sampled`	`traceSampled`	此字段的值必须是 `true` 或 `false`。如需了解详情，请参阅 `LogEntry` 页面上的 `traceSampled`。	`"logging.googleapis.com/trace_sampled": false`

与时间相关的字段

通常，与日志条目相关的时间信息存储在 LogEntry 对象的 timestamp 字段中：

{
insertId: "1ad8d08f-6529-47ea-832e-467f869a2da4"
...
resource: {2}
timestamp: "2023-10-30T16:33:15.505196Z"
}

如果日志条目的来源是结构化数据，Logging 代理会使用以下规则在 jsonPayload 条目中的字段中搜索时间相关信息：

搜索 timestamp 字段，该字段一个 JSON 对象，包含 seconds 和 nanos 字段，分别表示 UTC 纪元的有符号秒数和非负小数秒数：
```
jsonPayload: {
  ...
  "timestamp": {
    "seconds": CURRENT_SECONDS,
    "nanos": CURRENT_NANOS
  }
}
```

如果上一个搜索失败，请搜索一对 timestampSeconds 和 timestampNanos 字段：

jsonPayload: {
  ...
  "timestampSeconds": CURRENT_SECONDS,
  "timestampNanos": CURRENT_NANOS
}

如果上一个搜索失败，请搜索 time 字段，该字段是 RFC 3339 格式的字符串：
```
jsonPayload: {
  ...
  "time": CURRENT_TIME_RFC3339
}
```

找到与时间相关的信息后，Logging 代理会使用该信息来设置 LogEntry.timestamp 的值，并且不会将该信息从结构化记录复制到 LogEntry.jsonPayload 对象中。

未用于设置 LogEntry.timestamp 字段的值的时间相关字段会从结构化记录复制到 LogEntry.jsonPayload 对象。例如，如果结构化记录包含 timestamp JSON 对象和 time 字段，则使用 timestamp JSON 对象中的数据来设置 LogEntry.timestamp 字段。LogEntry.jsonPayload 对象包含一个 time 字段，因为此字段未用于设置 LogEntry.timestamp 值。

自定义代理配置

除了默认情况下 Logging 代理流式传输的默认日志列表外，您还可以通过添加输入配置来自定义 Logging 代理，以向 Logging 发送更多日志或者调整代理设置。

这些部分中的配置定义仅适用于 fluent-plugin-google-cloud 输出插件，而且指定日志如何转换并提取到 Cloud Logging 中。

主要配置文件位置：
- Linux：/etc/google-fluentd/google-fluentd.conf
- Windows：C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf
  
  如果您运行的 Logging 代理版本低于 v1-5，则位置为：C:\GoogleStackdriverLoggingAgent\fluent.conf
说明：此文件包含用于控制 fluent-plugin-google-cloud 输出插件行为的配置选项。
请参阅配置代码库。

从其他输入流式传输日志

您可以通过添加输入配置来自定义 Logging 代理以向 Logging 发送更多日志。

通过日志文件流式传输非结构化（文本）日志

从 Linux 命令提示符创建一个日志文件：
```
touch /tmp/test-unstructured-log.log
```

在其他配置目录 /etc/google-fluentd/config.d 中创建标有 test-unstructured-log.conf 的新配置文件：

sudo tee /etc/google-fluentd/config.d/test-unstructured-log.conf <<EOF
<source>
    @type tail
    <parse>
        # 'none' indicates the log is unstructured (text).
        @type none
    </parse>
    # The path of the log file.
    path /tmp/test-unstructured-log.log
    # The path of the position file that records where in the log file
    # we have processed already. This is useful when the agent
    # restarts.
    pos_file /var/lib/google-fluentd/pos/test-unstructured-log.pos
    read_from_head true
    # The log tag for this log input.
    tag unstructured-log
</source>
EOF

创建新文件的替代方案是，将配置信息添加到现有配置文件中。

重启代理以应用配置更改：
```
sudo service google-fluentd restart
```

在日志文件中生成日志记录：

echo 'This is a log from the log file at test-unstructured-log.log' >> /tmp/test-unstructured-log.log

检查日志浏览器以查看提取的日志条目：

{
  insertId:  "eps2n7g1hq99qp"
  labels: {
  compute.googleapis.com/resource_name:  "add-unstructured-log-resource"
  }
  logName:  "projects/my-sample-project-12345/logs/unstructured-log"
  receiveTimestamp:  "2018-03-21T01:47:11.475065313Z"
  resource: {
  labels: {
    instance_id:  "3914079432219560274"
    project_id:  "my-sample-project-12345"
    zone:  "us-central1-c"
  }
  type:  "gce_instance"
  }
  textPayload:  "This is a log from the log file at test-unstructured-log.log"
  timestamp:  "2018-03-21T01:47:05.051902169Z"
}

通过日志文件流式传输结构化 (JSON) 日志

您可以将 Logging 代理配置为要求某些日志输入的每个日志条目都是结构化的。您还可以自定义 Logging 代理，以从日志文件中提取 JSON 格式的内容。当代理配置为提取 JSON 内容时，必须设置输入的格式，以使每个 JSON 对象都用换行符分隔：

    {"name" : "zeeshan", "age" : 28}
    {"name" : "reeba", "age" : 15}

如需将 Logging 代理配置为提取 JSON 格式的内容，请执行以下操作：

从 Linux 命令提示符创建一个日志文件：
```
touch /tmp/test-structured-log.log
```

在其他配置目录 /etc/google-fluentd/config.d 中创建标有 test-structured-log.conf 的新配置文件：

sudo tee /etc/google-fluentd/config.d/test-structured-log.conf <<EOF
<source>
    @type tail
    <parse>
        # 'json' indicates the log is structured (JSON).
        @type json
    </parse>
    # The path of the log file.
    path /tmp/test-structured-log.log
    # The path of the position file that records where in the log file
    # we have processed already. This is useful when the agent
    # restarts.
    pos_file /var/lib/google-fluentd/pos/test-structured-log.pos
    read_from_head true
    # The log tag for this log input.
    tag structured-log
  </source>
  EOF

创建新文件的替代方案是，将配置信息添加到现有配置文件中。

重启代理以应用配置更改：
```
sudo service google-fluentd restart
```

在日志文件中生成日志记录：

echo '{"code": "structured-log-code", "message": "This is a log from the log file at test-structured-log.log"}' >> /tmp/test-structured-log.log

检查日志浏览器以查看提取的日志条目：

{
  insertId:  "1m9mtk4g3mwilhp"
  jsonPayload: {
  code:  "structured-log-code"
  message:  "This is a log from the log file at test-structured-log.log"
  }
  labels: {
  compute.googleapis.com/resource_name:  "add-structured-log-resource"
  }
  logName:  "projects/my-sample-project-12345/logs/structured-log"
  receiveTimestamp:  "2018-03-21T01:53:41.118200931Z"
  resource: {
  labels: {
    instance_id:  "5351724540900470204"
    project_id:  "my-sample-project-12345"
    zone:  "us-central1-c"
  }
  type:  "gce_instance"
  }
  timestamp:  "2018-03-21T01:53:39.071920609Z"
}

在日志浏览器中，按资源类型和 structured-log 的 logName 进行过滤。

如需了解用于为常见第三方应用自定义日志输入格式的其他选项，请参阅常见日志格式及其解析方式。

通过 `in_forward` 插件流式传输结构化 (JSON) 日志

此外，您还可以通过 fluentd in_forward 插件发送日志。fluentd-cat 是一种内置工具，可以帮助您轻松向 in_forward 插件发送日志。如需详细了解此工具，请参阅 fluentd 文档。

若要通过 fluentd in_forward 插件发送日志，请阅读以下说明：

在已安装 Logging 代理的虚拟机上执行以下命令：

echo '{"code": "send-log-via-fluent-cat", "message": "This is a log from in_forward plugin."}' | /opt/google-fluentd/embedded/bin/fluent-cat log-via-in-forward-plugin

检查日志浏览器以查看提取的日志条目：

{
  insertId:  "1kvvmhsg1ib4689"
  jsonPayload: {
  code:  "send-log-via-fluent-cat"
  message:  "This is a log from in_forward plugin."
  }
  labels: {
  compute.googleapis.com/resource_name:  "add-structured-log-resource"
  }
  logName:  "projects/my-sample-project-12345/logs/log-via-in-forward-plugin"
  receiveTimestamp:  "2018-03-21T02:11:27.981020900Z"
  resource: {
  labels: {
    instance_id:  "5351724540900470204"
    project_id:  "my-sample-project-12345"
    zone:  "us-central1-c"
  }
  type:  "gce_instance"
  }
  timestamp:  "2018-03-21T02:11:22.717692494Z"
}

从应用代码流式传输结构化 (JSON) 日志记录

您可以启用各种语言的连接器，以便从应用代码发送结构化日志；如需了解详情，请参阅 fluentd 文档。这些连接器是基于 in_forward 插件构建的。

设置日志条目标签

利用下面的配置选项，您可以在将日志提取到 Cloud Logging 时替换 LogEntry 标签和 MonitoredResource 标签。所有日志条目都与受监控的资源相关联；如需了解详情，请参阅 Cloud Logging 受监控的资源类型列表。

配置名称	类型	默认值	说明
`label_map`	哈希	nil	`label_map`（指定为 JSON 对象）是一组无序的 `fluentd` 字段名称，其值作为标签而非作为结构化载荷的一部分发送。映射中的每个条目都是 {`field_name`: `label_name`} 对。如果遇到 `field_name`（由输入插件解析），则包含对应 `label_name` 的标签将添加到日志条目。该字段的值用作该标签的值。此映射使您能够更灵活地指定标签名称，包括能够在 `fluentd` 字段名称中使用非法字符。如需获取示例，请参阅在结构化日志条目中设置标签。
`labels`	哈希	nil	`labels`（指定为 JSON 对象）是配置时提供的一组自定义标签。它允许您将额外的环境信息注入到每条消息中，也允许您自定义以其他方式自动检测的标签。映射中的每个条目都是 {`label_name`: `label_value`} 对。

Logging 代理输出插件支持使用三种方式来设置 LogEntry 标签：

动态方式，将结构化条目中的特定标签替换为不同标签。如需了解详情，请参阅本页面上的在结构化日志条目中设置标签。
静态方式，将标签附加到值的任何实例。如需了解详情，请参阅本页面上的静态设置标签。

在结构化日志条目中设置标签

假设您编写了一个如下所示的结构化日志条目载荷：

{ "message": "This is a log message", "timestamp": "Aug 10 20:07:00", "env": "production" }

并且假设您要将上述载荷字段 env 转换为元数据标签 environment。为实现此目的，请在主配置文件 /etc/google-fluentd/google-fluentd.conf (Linux) 或 C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf (Windows) 的输出插件配置中添加下列内容：

# Configure all sources to output to Cloud Logging
<match **>
  @type google_cloud
  label_map {
    "env": "environment"
  }
  ...
</match>

这里的 label_map 设置会将载荷中的 env 标签替换为 environment，因此生成的日志条目将具有值为 production 的标签 environment。

静态设置标签

如果载荷不含此信息，并且您只想添加名为 environment 的静态元数据标签，请在主配置文件 /etc/google-fluentd/google-fluentd.conf (Linux) 或 C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf (Windows) 的输出插件配置中添加下列内容：

# Configure all sources to output to Cloud Logging
<match **>
  @type google_cloud
  labels {
    "environment": "production"
  }
  ...
</match>

在此情况下，我们使用 labels 设置将具有给定字面量值的标签附加到日志条目（无论该条目是否已经有标签），而不是使用映射将一个标签替换为另一个标签。即使您要发送非结构化日志，也可以使用此方法。

如需详细了解如何配置 labels、label_map 和其他 Logging 代理设置，请参阅本页面上的设置日志条目标签。

修改日志记录

Fluentd 提供内置过滤条件插件，可用于修改日志条目。

最常用的过滤条件插件是 filter_record_transformer。通过该插件，您可以执行以下操作：

将新字段添加到日志条目
更新日志条目中的字段
删除日志条目中的字段

某些输出插件还允许您修改日志条目。fluent-plugin-record-reformer 输出插件提供与 filter_record_transformer 过滤条件插件类似的功能，不同之处在于此输出插件还允许您修改日志标记。此插件需要使用更多资源：每次更新日志标记时，此插件都会生成一个带有新标记的新日志条目。请注意，配置中的 tag 字段为必填项；我们还建议您修改此字段以避免进入死循环。

fluent-plugin-detect-exceptions 输出插件会扫描日志流（非结构化（文本）或 JSON 格式的日志记录）以找出多行异常堆栈跟踪记录。如果一系列连续日志条目形成异常堆栈跟踪，则这些日志条目将作为一条合并日志消息进行转发。否则，日志条目将按原样转发。

高级（非默认）配置定义

如果您想要自定义 Logging 代理的配置，而不局限于默认配置，请阅读以下部分。

缓冲区相关的配置选项

使用下面的配置选项，您可以调整 Logging 代理的内部缓冲机制。

配置名称	类型	默认值	说明
`buffer_type`	字符串	`buf_memory`	无法足够快地写入 Logging API 的记录将被推送到缓冲区中。缓冲区可以在内存中或在实际文件中。推荐的值：`buf_file`。默认 `buf_memory` 速度快但不持久。存在丢失日志的风险。如果 `buffer_type` 为 `buf_file`，则还需要指定 `buffer_path`。
`buffer_path`	字符串	用户指定	缓冲区区块的存储路径。如果 `buffer_type` 为 `file`，则此参数是必需的。此配置必须是唯一的，以避免出现争用情况。
`buffer_queue_limit`	整数	`64`	指定区块队列的长度限制。当缓冲区队列达到这么多区块时，缓冲区行为由 `buffer_queue_full_action` 控制。默认情况下，将抛出异常。此选项与 `buffer_chunk_limit` 相结合可确定 `fluentd` 进行缓冲所需的最大磁盘空间。
`buffer_queue_full_action`	字符串	`exception`	缓冲区队列已满时控制缓冲区行为。可能的值： 1. `exception`：当队列已满时抛出 `BufferQueueLimitError`。处理 `BufferQueueLimitError` 的方式取决于输入插件。例如，`in_tail` 输入插件会在 `in_forward` 输入插件返回错误时停止读取新行。 2. `block`：除非解决了缓冲区已满状况，否则此模式会停止输入插件线程。此操作适用于类似批处理的使用场景。`fluentd` 建议不要使用阻止操作来避免 `BufferQueueLimitError`。如果您经常遇到 `BufferQueueLimitError`，则表示您的目标容量不足以满足您的流量需求。 3. `drop_oldest_chunk`：此模式会删除最旧的区块。

项目相关和受监控资源相关的配置选项

使用下面的配置选项，您可以手动指定项目以及指定 MonitoredResource 对象中的特定字段。这些值由 Logging 代理自动收集；建议您不要手动指定这些值。

配置名称	类型	默认值	说明
`project_id`	字符串	nil	如果指定，则此配置会替换 `project_id`，从而标识正在其中运行 Logging 代理的底层 Google Cloud 或 AWS 项目。
`zone`	字符串	nil	如果指定，则此配置会替换地区。
`vm_id`	字符串	nil	如果指定，则此配置会替换虚拟机 ID。
`vm_name`	字符串	nil	如果指定，则此配置会覆盖虚拟机名称。

其他输出插件配置选项

配置名称	类型	默认值	说明
`detect_json`¹	布尔值	`false`	是否尝试进行下列检测：日志记录是否为包含需要解析的 JSON 内容的文本日志条目。如果此选项为 `true`，并且检测到包含 JSON 格式内容的非结构化（文本）日志条目，则系统会解析该日志条目，并将其作为结构化 (JSON) 载荷发送。
`coerce_to_utf8`	布尔值	`true`	是否允许在用户日志中使用非 UTF-8 字符。如果设置为 `true`，则任何非 UTF-8 字符都将替换为 `non_utf8_replacement_string` 指定的字符串。如果设置为 `false`，则任何非 UTF-8 字符都将触发插件输出错误。
`require_valid_tags`	布尔值	`false`	是否拒绝带有无效标记的日志条目。如果此选项设置为 `false`，则通过将任何非字符串标记转换为字符串，并清理任何非 UTF-8 字符或其他无效字符，使标记生效。
`non_utf8_replacement_string`	字符串	`""`（空格）	如果 `coerce_to_utf8` 设置为 `true`，则任何非 UTF-8 字符都将替换为此处指定的字符串。

¹默认情况下，在 App Engine 柔性环境和 Google Kubernetes Engine 中运行的虚拟机实例中会启用此功能。

应用自定义代理配置

自定义 Logging 代理允许您添加自己的 fluentd 配置文件：

Linux 实例

将您的配置文件复制到以下目录：
```
/etc/google-fluentd/config.d/
```
Logging 代理安装脚本用默认万能配置文件填充此目录。如需了解详情，请参阅获取 Logging 代理源代码。
可选。运行以下命令以验证配置更改：
```
sudo service google-fluentd configtest
```

通过运行以下命令重启代理：

sudo service google-fluentd force-reload

Windows 实例

将您的配置文件复制到代理安装目录的 config.d 子目录中。如果您已接受默认安装目录，则此目录为：
```
C:\Program Files (x86)\Stackdriver\LoggingAgent\config.d\
```
通过在命令行 shell 中运行以下命令来重启代理：
```
net stop  StackdriverLogging
net start StackdriverLogging
```

如需详细了解 fluentd 配置文件，请参阅 fluentd 的配置文件语法文档。

配置 Logging 代理

默认配置

默认配置定义

根配置文件位置

Syslog 配置

in_forward 输入插件配置

第三方应用日志输入配置

Google Cloud fluentd 输出插件配置

Monitoring 配置

输出插件遥测

prometheus 和 prometheus_monitor 插件配置

处理载荷

结构化负载中的特殊字段

与时间相关的字段

自定义代理配置

从其他输入流式传输日志

通过日志文件流式传输非结构化（文本）日志

通过日志文件流式传输结构化 (JSON) 日志

通过 in_forward 插件流式传输结构化 (JSON) 日志

从应用代码流式传输结构化 (JSON) 日志记录

设置日志条目标签

在结构化日志条目中设置标签

静态设置标签

修改日志记录

高级（非默认）配置定义

缓冲区相关的配置选项

项目相关和受监控资源相关的配置选项

其他输出插件配置选项

应用自定义代理配置

Linux 实例

Windows 实例

`in_forward` 输入插件配置

Google Cloud `fluentd` 输出插件配置

通过 `in_forward` 插件流式传输结构化 (JSON) 日志