配置代理

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

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

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

  • 您想要更改 Cloud Logging 代理的配置。

默认配置

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

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

Logging 代理的工作原理

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

代理通过 fluentd 的内置 in_tail 插件在虚拟机实例上读取日志文件中所存储的日志记录。每个日志记录均转换为 Cloud Logging 的日志条目结构。每个日志记录的内容主要记录在日志条目的载荷中,但日志条目还包含 timestampseverity 等标准元素。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.confforward.conf 之外,每个文件均表示一个应用(例如,apache.conf 表示 Apache 应用)。

  • 请参阅配置代码库

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

1 如果您使用的是 <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_limitretry_waitmax_retry_wait 中的详细规范。
retry_limit 整数 3 如果缓冲区区块刷新失败,则默认情况下 fluentd 会稍后重试。此配置设置在删除一个有问题的缓冲区区块之前要执行的重试次数。
retry_wait 整数 10s 如果缓冲区区块刷新失败,则默认情况下 fluentd 会稍后重试。此配置设置第一次重试之前的等待间隔(以秒为单位)。每次后续重试时,等待间隔将加倍(20 秒、40秒…),直到达到 retry_ limitmax_retry_wait
max_retry_wait 整数 300 如果缓冲区区块刷新失败,则默认情况下 fluentd 会稍后重试。每次后续重试时,等待间隔将加倍(20 秒、40 秒…)。此配置设置最大等待间隔(以秒为单位)。如果等待间隔达到此限制,则停止加倍。
num_threads 整数 8 输出插件可以处理的同时刷新日志的次数。
use_grpc 布尔值 true 是否使用 gRPC 而非 REST/JSON 与 Logging API 通信。启用 gRPC 后,CPU 使用率通常会下降。
partial_success 布尔值 true 是否支持日志提取部分成功。如果为 true,则整个集内的无效日志条目会被删除,并且有效日志条目会成功提取到 Logging API 中。如果为 false,则只要整个集合包含任何无效日志条目,系统就会删除整个集合。
enable_monitoring 布尔值 true 如果设置为 true,则 Logging 代理会导出内部遥测数据。如需了解详情,请参阅输出插件遥测
monitoring_type 字符串 opencensus 监控的类型。支持的选项有 opencensusprometheus。如需了解详情,请参阅输出插件遥测
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 代理的正常运行时间。
  • 带有 grpccode 标签的 stackdriver_successful_requests_count:对 Logging API 的成功请求数。
  • 带有 grpccode 标签的 stackdriver_failed_requests_count:对 Logging API 的失败请求数,按错误代码细分。
  • 带有 grpccode 标签的 stackdriver_ingested_entries_count:Logging API 提取的日志条目数。
  • 带有 grpccode 标签的 stackdriver_dropped_entries_count:Logging API 拒绝的日志条目数。
  • 带有 grpccode 标签的 stackdriver_retried_entries_count:由于暂时性错误,Google Cloud fluentd 输出插件未能提取和进行了重试的的日志条目数。

prometheus 和 prometheus_monitor 插件配置

  • 配置文件位置/etc/google-fluentd/google-fluentd.conf

  • 说明:此文件包含用于控制 prometheusprometheus_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 对象中写入 Logging API 的特定字段。

下表中的所有字段如果存在的话,都会从载荷中删除。

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 中。如果您的日志条目包含异常堆栈轨迹,则应在此 message JSON 日志字段中设置异常堆栈轨迹,以便系统可以解析该异常堆栈跟踪并将其保存到 Error Reporting 之中。
log(仅限旧版 Google Kubernetes Engine) textPayload 仅适用于旧版 Google Kubernetes Engine:如果在删除特殊用途字段后,只留下一个日志字段,则该日志将另存为 textPayload
httpRequest httpRequest 采用 LogEntry HttpRequest 字段格式的结构化记录。 "httpRequest":{"requestMethod":"GET"}
与时间相关的字段 timestamp 如需了解详情,请参阅与时间相关的字段 "timestamp":"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"

注意:如果未向 stdoutstderr 写入数据,此字段的值应设置为 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 此字段的值必须是 truefalse。如需了解详情,请参阅 LogEntry 页面上的 traceSampled logging.googleapis.com/trace_sampled":"false"

任何其余的结构化记录字段都仍为 jsonPayload 的一部分。在没有 detect_json 的情况下,如果只留下一个 message 字段,则该字段的值将存储为日志条目中的 textPayload

与时间相关的字段

Logging 代理可以接收和处理采用多种 JSON 格式的时间相关字段。如果结构化记录中存在以下某个 JSON 时间戳表示法,则 Logging 代理会从 jsonPayload 中删除这些字段,并在 LogEntry 对象的 timestamp 字段中将其收起,显示为一种表示形式:

  • jsonPayload 包含一个 timestamp 字段,其中包含 secondsnanos 字段,分别表示从世界协调时间 (UTC) epoch 时间(1970 年 1 月 1 日 0 时 0 分 0 秒)起有符号的秒数和非负小数秒:

    {
      "timestamp": {
        "seconds": CURRENT_SECONDS,
        "nanos": CURRENT_NANOS
      }
    }
    
  • jsonPayload 包含 timestampSecondstimestampNanos 字段:

    {
       "timestampSeconds": CURRENT_SECONDS,
       "timestampNanos": CURRENT_NANOS
    }
    
  • jsonPayload 包含一个 time 字段,其中包含相同的秒信息(采用 RFC 3339 定义的字符串形式):

    {
        "time": CURRENT_TIME_RFC3339
    }
    

一旦 Logging 代理检测到时间戳表示法,则即使结构化记录中存在可接受格式的其他表示法,也不会进一步执行时间戳相关的删除操作。

自定义代理配置

除了默认情况下 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 发送更多日志。

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

  1. 从 Linux 命令提示符创建一个日志文件:

    touch /tmp/test-unstructured-log.log
    
  2. 在其他配置目录 /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
    

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

  3. 重启代理以应用配置更改:

    sudo service google-fluentd restart
    
  4. 在日志文件中生成日志记录:

    echo 'This is a log from the log file at test-unstructured-log.log' >> /tmp/test-unstructured-log.log
    
  5. 检查日志浏览器以查看提取的日志条目:

      {
       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 格式的内容,请执行以下操作:

  1. 从 Linux 命令提示符创建一个日志文件:

    touch /tmp/test-structured-log.log
    
  2. 在其他配置目录 /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
    

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

  3. 重启代理以应用配置更改:

    sudo service google-fluentd restart
    
  4. 在日志文件中生成日志记录:

    echo '{"code": "structured-log-code", "message": "This is a log from the log file at test-structured-log.log"}' >> /tmp/test-structured-log.log
    
  5. 检查日志浏览器以查看提取的日志条目:

    {
     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-loglogName 进行过滤。

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

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

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

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

  1. 在已安装 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
    
  2. 检查日志浏览器以查看提取的日志条目:

      {
       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 设置将具有给定字面量值的标签附加到日志条目(无论该条目是否已经有标签),而不是使用映射将一个标签替换为另一个标签。即使您要发送非结构化日志,也可以使用此方法。

如需详细了解如何配置 labelslabel_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_typebuf_file,则还需要指定 buffer_path
buffer_path 字符串 用户指定 缓冲区区块的存储路径。如果 buffer_typefile,则此参数是必需的。此配置必须是唯一的,以避免出现争用情况。
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 代理的底层 GCP 或 AWS 项目。
zone 字符串 nil 如果指定,则此配置会替换地区。
vm_id 字符串 nil 如果指定,则此配置会替换虚拟机 ID。
vm_name 字符串 nil 如果指定,则此配置会覆盖虚拟机名称。

其他输出插件配置选项

配置名称 类型 默认值 说明
detect_json1 布尔值 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 字符都将替换为此处指定的字符串。

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

应用自定义代理配置

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

Linux 实例

  1. 将您的配置文件复制到以下目录:

    /etc/google-fluentd/config.d/
    
  2. 通过运行以下命令重启代理:

    sudo service google-fluentd force-reload
    

Logging 代理安装脚本用默认万能配置文件填充此目录。如需了解详情,请参阅获取 Logging 代理源代码

Windows 实例

  1. 将您的配置文件复制到代理安装目录的 config.d 子目录中。如果您已接受默认安装目录,则此目录为:

    C:\Program Files (x86)\Stackdriver\LoggingAgent\config.d\
    
  2. 通过在命令行 shell 中运行以下命令来重启代理:

    net stop  StackdriverLogging
    net start StackdriverLogging
    

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