结构化日志记录

在 Stackdriver Logging 中,结构化日志是指使用 jsonPayload 字段为其负载添加结构的日志条目。如果使用 Stackdriver Logging API 或命令行实用程序 gcloud logging,则可以控制负载结构。如果使用 Stackdriver Logging 代理来获取日志条目,则可以指定 Logging 代理将负载转换为 JSON 格式。如需详细了解不同的负载格式,请参阅 LogEntry

下面的示例展示了一个日志条目,其结构化负载以粗体突出显示:


        {
         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"
        }

结构化日志记录操作

Logging 代理 google-fluentdFluentd 日志数据收集器的修订版。Logging 代理默认采用 Fluentd 配置,并使用 Fluentd 输入插件从外部源(例如磁盘上的文件)拉取事件日志,或者使用该插件解析传入的日志记录。

Fluentd 支持多种解析器,这些解析器可提取日志并将日志转换为结构化 (JSON) 负载。

使用 format [PARSER_NAME] 配置日志源之后,您便可以利用 Fluentd 提供的内置解析器。

以下代码示例展示了 Fluentd 配置、输入日志记录,以及属于 Stackdriver Logging 日志条目一部分的输出结构化负载:

  • Fluentd 配置:

      <source>
        @type tail
    
        format syslog # <--- This uses a predefined log format regex named
                      # `syslog`. See details at https://docs.fluentd.org/parser/syslog.
    
        path /var/log/syslog
        pos_file /var/lib/google-fluentd/pos/syslog.pos
        read_from_head true
        tag syslog
      </source>
    
  • 日志记录(输入):

      <6>Feb 28 12:00:00 192.168.0.1 fluentd[11111]: [error] Syslog test
    
  • 结构化负载:

        jsonPayload: {
            "pri": "6",
            "host": "192.168.0.1",
            "ident": "fluentd",
            "pid": "11111",
            "message": "[error] Syslog test"
        }
    

如需了解有关 syslog 解析器工作原理的更多信息,请参阅详细的 Fluentd 文档

默认启用的标准解析器

下表列出了启用结构化日志记录后代理中包含的标准解析器:

解析器名称 配置文件
syslog /etc/google-fluentd/config.d/syslog.conf
nginx /etc/google-fluentd/config.d/nginx.conf
apache2 /etc/google-fluentd/config.d/apache.conf
apache_error /etc/google-fluentd/config.d/apache.conf

请参阅下文的安装部分,了解如何在安装 Logging 代理时启用结构化日志记录。

安装

如需启用结构化日志记录,您必须在安装或重新安装 Logging 代理时更改其默认配置。启用结构化日志记录为您获取最新版代理,并替换之前列出的配置文件。代理本身的运行不会发生变化。

启用结构化日志记录时,列出的日志将转换为与启用结构化日志之前的格式不同的日志条目。如果正在将日志从 Stackdriver Logging 中导出,发生的更改可能会影响所有后处理应用。如果是导出到 BigQuery,BigQuery 会因架构有误而拒绝当天其余时间内的所有新日志条目。

以下步骤说明了如何安装代理并启用结构化日志记录:

  1. 使用 SSH 或类似工具打开到虚拟机实例的终端连接。

  2. 通过在您的虚拟机实例上运行以下命令来下载 Logging 代理的安装脚本:

        curl -sSO "https://dl.google.com/cloudagents/install-logging-agent.sh"
    
  3. 使用以下命令运行安装脚本:

        sudo bash install-logging-agent.sh --structured
    
  4. 验证安装是否成功,请在日志查看器中查找该代理的测试日志条目。

  5. 您可以在安装脚本成功运行后将其删除。

您可以在 /etc/google-fluentd/config.d/ 下找到 Logging 代理配置文件,其中应该已经包括了默认启用的标准解析器

如需了解详情,请参阅安装 Logging 代理

配置 Apache 访问日志格式

默认情况下,Logging 代理将 Apache 访问日志数据存储在 jsonPayload 字段中。例如:

{
  "logName": ...,
  "resource": ...,
  "httpRequest": ...,
  "jsonPayload": {
    "user"   : "some-user",
    "method" : "GET",
    "code"   : 200,
    "size"   : 777,
    "host"   : "192.168.0.1",
    "path"   : "/some-path",
    "referer": "some-referer",
    "agent"  : "Opera/12.0"
  },
  ...
}

或者,您可以配置 Logging 代理以将某些字段提取到 httpRequest 字段。例如:

{
  "logName": ...,
  "resource": ...,
  "httpRequest": {
    "requestMethod": "GET",
    "requestUrl": "/some-path",
    "requestSize": "777",
    "status": "200",
    "userAgent": "Opera/12.0",
    "serverIp": "192.168.0.1",
    "referrer":"some-referrer",
  },
  "jsonPayload": {
    "user":"some-user"
  },
  ...
}

如上所示,配置 httpRequest 字段有助于跟踪:GCP Console 在父子层次结构中显示给定 HTTP 请求的所有日志。

要配置此提取,请将以下内容添加到 /etc/google-fluentd/config.d/apache.conf 的末尾:

  <filter apache-access>
    @type record_transformer
    enable_ruby true
    <record>
      httpRequest ${ {"requestMethod" => record['method'], "requestUrl" => record['path'], "requestSize" => record['size'], "status" => record['code'], "userAgent" => record['agent'], "serverIp" => record['host'],
      "referer" => record['referer']} }
    </record>
    remove_keys method, path, size, code, agent, host, referer
  </filter>

如需详细了解如何配置日志条目,请参阅修改日志记录

配置 nginx 访问日志格式

默认情况下,Logging 代理将 nginx 访问日志数据存储在 jsonPayload 字段中。例如:

  {
    "logName": ...,
    "resource": ...,
    "httpRequest": ...,
    "jsonPayload": {
      "remote":"127.0.0.1",
      "host":"192.168.0.1",
      "user":"some-user",
      "method":"GET",
      "path":"/some-path",
      "code":"200",
      "size":"777",
      "referrer":"some-referrer",
      "agent":"Opera/12.0",
      "http_x_forwarded_for":"192.168.3.3"
    },
    ...
  }

或者,您可以配置 Logging 代理以将某些字段提取到 httpRequest 字段。例如:

  {
    "logName": ...,
    "resource": ...,
    "httpRequest": {
      "requestMethod": "GET",
      "requestUrl": "/some-path",
      "requestSize": "777",
      "status": "200",
      "userAgent": "Opera/12.0",
      "remoteIp": "127.0.0.1",
      "serverIp": "192.168.0.1",
      "referrer":"some-referrer",
    },
    "jsonPayload": {
      "user":"some-user",
      "http_x_forwarded_for":"192.168.3.3"
    },
    ...
  }

如上所示,配置 httpRequest 字段有助于跟踪:GCP Console 在父子层次结构中显示给定 HTTP 请求的所有日志。

要配置此提取,请将以下内容添加到 /etc/google-fluentd/config.d/nginx.conf 的末尾:

<filter nginx-access>
  @type record_transformer
  enable_ruby true
  <record>
    httpRequest ${ {"requestMethod" => record['method'], "requestUrl" => record['path'], "requestSize" => record['size'], "status" => record['code'], "userAgent" => record['agent'], "remoteIp" => record['remote'], "serverIp" => record['host'], "referer" => record['referer']} }
  </record>
  remove_keys method, path, size, code, agent, remote, host, referer
</filter>

如需详细了解如何配置日志条目,请参阅修改日志记录

自行编写解析器

如果标准解析器不支持您的日志,您可以自行编写解析器。解析器包含一个用于匹配日志记录并将标签应用于各部分的正则表达式。

以下 3 个代码示例分别显示了日志记录中的日志行、包含指示日志行格式的正则表达式的配置,以及提取的日志条目:

  • 日志记录中的日志行:

    REPAIR CAR $500
    
  • 包含指示日志行格式的正则表达式的配置:

    $ sudo vim /etc/google-fluentd/config.d/test-structured-log.conf
    $ cat /etc/google-fluentd/config.d/test-structured-log.conf
    <source>
      @type tail
    
      # Format indicates the log should be translated from text to
      # structured (JSON) with three fields, "action", "thing" and "cost",
      # using the following regex:
      format /(?<action>\w+) (?<thing>\w+) \$(?<cost>\d+)/
      # 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>
    
  • 生成的日志条目:

     {
      insertId:  "eps2n7g1hq99qp"
      jsonPayload: {
        action:  "REPAIR"
        thing:  "CAR"
        cost:  "500"
      }
      labels: {
        compute.googleapis.com/resource_name:  "add-structured-log-resource"
      }
      logName:  "projects/my-sample-project-12345/logs/structured-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"
      }
      timestamp:  "2018-03-21T01:47:05.051902169Z"
     }
    

查看结构化日志

如需使用日志查看器搜索日志和查看日志条目,请参阅查看日志

如需使用 SDK 或 API 读取日志条目,请参阅读取日志条目

问题排查

如需排查在安装 Logging 代理或与之交互时出现的常见问题,请参阅排查代理问题

此页内容是否有用?请给出您的反馈和评价:

发送以下问题的反馈:

此网页
Stackdriver Logging
需要帮助?请访问我们的支持页面