結構化記錄

在 Stackdriver Logging 中,「結構化記錄檔」是指使用 jsonPayload 欄位在酬載中加入結構的記錄項目。如果您使用的是 Stackdriver Logging API 或指令列公用程式 gcloud logging,就能控制酬載的結構。如果您使用 Stackdriver Logging 代理程式取得記錄項目,則可指定 Stackdriver 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"
        }

結構化記錄作業

Stackdriver Logging 代理程式 google-fluentdFluentd 記錄資料收集器的修改版本。Stackdriver Logging 代理程式預設使用 Fluentd 設定和 Fluentd 輸入外掛程式,會從磁碟中的檔案等外部來源提取事件記錄,或剖析收到的記錄檔記錄。

Fluentd 有一系列支援的剖析器,可擷取記錄並轉換為結構化 (JSON) 酬載。

使用 format [PARSER_NAME] 設定了記錄來源後,就能使用 Fluentd 提供的內建剖析器。

下列程式碼範例顯示的是 Stackdriver Logging 記錄項目中的 Fluentd 設定、輸入記錄檔的記錄,以及輸出的結構化酬載:

  • 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

如需在安裝 Stackdriver Logging 代理程式時啟用結構化記錄的操作說明,請參閱下方的安裝一節。

安裝

如要啟用結構化記錄,必須在安裝 (或重新安裝) Stackdriver Logging 代理程式時,更改其預設設定。啟用結構化記錄可以取得代理程式的最新版本,並取代先前列出的設定檔。代理程式的操作本身並無變化。

啟用結構化記錄後,會將列出的記錄檔轉換為格式與啟用前不同的記錄項目。如果是從 Stackdriver Logging 匯出記錄檔,後續處理的應用程式均會受到變更的影響。如果是使用 BigQuery 匯出,BigQuery 會拒絕當天剩餘時間的新記錄項目,因為這些項目的結構定義不正確。

以下是啟用結構化記錄的代理程式安裝操作說明:

  1. 使用 SSH 或類似工具開啟對 VM 執行個體開啟終端機連線。

  2. 在 VM 執行個體執行以下指令,下載 Stackdriver 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/ 找到 Stackdriver Logging 代理程式的設定檔,其中應已包含預設啟用的標準剖析器

如需更多資訊,請參閱安裝 Stackdriver Logging 代理程式相關頁面。

設定 Apache 存取記錄格式

根據預設,Stackdriver 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"
  },
  ...
}

您也可以設定 Stackdriver 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 主控台以父/子階層方式呈現指定 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 存取記錄格式

根據預設,Stackdriver 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"
    },
    ...
  }

您也可以設定 Stackdriver 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 主控台以父/子階層方式呈現指定 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 讀取記錄項目,請參閱讀取記錄項目一節。

疑難排解

如需排解 Stackdriver Logging 代理程式在安裝或互動時的常見問題,請參閱代理程式疑難排解一文。

本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁
Stackdriver Logging
需要協助嗎?請前往我們的支援網頁