ログ Pipeline ユーザーガイド¶

Pipeline は、さまざまな形式のログデータに対してテキスト解析を実行する機能です。Pipeline スクリプトを作成することで、要件に合った構造化ログをカスタム抽出し、抽出したフィールドを属性として使用できます。属性フィールドを使用すると、関連ログの迅速なフィルタリングやデータ相関分析が可能になり、問題の特定と解決を迅速化できます。

Guance は、公式 Pipeline スクリプトライブラリを提供しており、複数のログ解析用 Pipeline が組み込まれています。また、ユーザーがカスタム Pipeline スクリプトを作成することもできます。ここでは、カスタム Pipeline 機能の使用方法を説明します。

前提条件¶

1. Guance アカウントを作成し、ホストに DataKit をインストールしてください。
2. ログ収集を有効にし、設定ファイルで Pipeline 機能を有効にします。

カスタム Pipeline スクリプトファイル¶

ステップ 1：ログ収集を有効にする（DataKit ログを例として）¶

ホストに DataKit をインストールした後、/usr/local/datakit/conf.d/log ディレクトリで logging.conf.sample をコピーして logging.conf という名前で保存し、logging.conf を編集して DataKit ログのパスとログソースを設定します。例：

• logfiles = ["/var/log/datakit/log"]
• source = "datakit"

注意：ログ収集では、Pipeline 機能はデフォルトで有効です。Pipeline = "" に具体的な Pipeline スクリプト名を指定する必要はありません。source と同じ名前のスクリプトファイルが自動的に照合されます。ログソースと Pipeline ファイル名が一致しない場合は、ログ収集の設定で Pipeline = "xxxxxx.p" を指定する必要があります。

[[inputs.logging]]
  ## required
  logfiles = [
    "/var/log/datakit/log",
  ]
  # only two protocols are supported:TCP and UDP
  # sockets = [
  #      "tcp://0.0.0.0:9530",
  #      "udp://0.0.0.0:9531",
  # ]
  ## glob filteer
  ignore = [""]

  ## your logging source, if it's empty, use 'default'
  source = "datakit"

  ## add service tag, if it's empty, use $source.
  service = ""

  ## grok pipeline script name
  ## 如果 pipeline 未指定具体，则会自动寻找跟 source 同名的脚本
  pipeline = ""

設定が完了したら、コマンド datakit --restart を使用して DataKit を再起動し、設定を反映させます。

ステップ 2：収集したログに基づいて抽出フィールドを決定する¶

ログ収集を有効にすると、Guance ワークスペースで収集した DataKit ログを表示できます。DataKit ログを観察・分析し、ログの抽出フィールド（ログ生成時刻、ログレベル、ログモジュール、モジュール内容、ログの内容など）を決定します。

ステップ 3：カスタム Pipeline を作成する¶

Guance ワークスペースで ログ > Pipelines に移動し、Pipeline を作成 をクリックして新しい Pipeline ファイルを作成します。

ログのフィルタリング¶

ログソースとして "datakit" を選択します。選択したログソースに基づいて、同名の Pipeline が自動生成されます。

解析ルールの定義¶

ログの解析ルールを定義します。複数のスクリプト関数がサポートされており、Guance が提供するスクリプト関数リストから直接構文形式を確認できます。

この例では、ログの観察結果に基づいて Pipeline スクリプトファイルを作成します。add_pattern() スクリプト関数を使用してカスタムパターンを定義し、Grok 内でそのカスタムパターンを参照してログを抽出できます。以下の例では、rename と default_time を使用して抽出したフィールドを最適化しています。

add_pattern('_dklog_date', '%{YEAR}-%{MONTHNUM}-%{MONTHDAY}T%{HOUR}:%{MINUTE}:%{SECOND}%{INT}')
add_pattern('_dklog_level', '(DEBUG|INFO|WARN|ERROR|FATAL)')
add_pattern('_dklog_mod', '%{WORD}')
add_pattern('_dklog_source_file', '(/?[\\w_%!$@:.,-]?/?)(\\S+)?')
add_pattern('_dklog_msg', '%{GREEDYDATA}')

grok(_, '%{_dklog_date:log_time}%{SPACE}%{_dklog_level:level}%{SPACE}%{_dklog_mod:module}%{SPACE}%{_dklog_source_file:code}%{SPACE}%{_dklog_msg:msg}')
rename("time", log_time) # 将 log_time 重名命名为 time
default_time(time)       # 将 time 字段作为输出数据的时间戳

詳細な Pipeline 解析ルールについては、ドキュメント テキストデータ処理（Pipeline） を参照してください。

ログサンプルテスト¶

スクリプトルールの作成が完了したら、ログサンプルデータを入力してテストし、設定した解析ルールが正しいかどうかを確認できます。

注意：

• ログサンプルテストは必須ではありません。
• カスタム Pipeline を保存すると、ログサンプルテストデータも同時に保存されます。

ステップ 4：Pipeline ファイルを保存する¶

すべての必須項目を設定したら、Pipeline ファイルを保存します。ログ Pipelines リストにカスタム Pipeline ファイルが表示されます。

Guance ワークスペースで作成した Pipeline ファイルは、/usr/local/datakit/Pipeline_remote ディレクトリに一元的に保存されます。

注意：DataKit には 2 つの Pipeline ディレクトリがあり、DataKit はこれらのディレクトリ内の Pipeline ファイルを自動的に照合します。

• Pipeline：公式ライブラリの Pipeline ファイルディレクトリ。
• Pipeline_remote：Guance ワークスペースのカスタム Pipeline ファイルディレクトリ。
• 2 つのディレクトリに同名の Pipeline ファイルが存在する場合、DataKit は Pipeline_remote の Pipeline ファイルを優先します。

ステップ 5：Guance で抽出後のフィールドを確認する¶

Guance ワークスペースのログで、datakit のログを選択します。ログ詳細ページの「属性」に表示されるフィールドとフィールド値が、ログ抽出後に表示されるフィールドとフィールド値です。例：

• code: container/input.go:167
• level: ERROR
• module: container

公式ライブラリの Pipeline スクリプトファイルのクローン¶

ステップ 1：Nginx 収集を有効にする¶

ホストに DataKit をインストールした後、/usr/local/datakit/conf.d/nginx ディレクトリで nginx.conf.sample をコピーして nginx.conf という名前で保存し、nginx.conf を編集して Nginx ログの保存場所と Pipeline を設定します。例：

• files = ["/var/log/nginx/access.log","/var/log/nginx/error.log"]
• Pipeline = "nginx.p"（"" 内に具体的な Pipeline スクリプト名を指定する必要はありません。DataKit は source と同じ名前のスクリプトファイルを自動的に照合します）

注意：Pipeline を有効にすると、DataKit はログソースに基づいて Pipeline スクリプトファイルを自動的に照合します。ログソースと Pipeline ファイル名が一致しない場合は、収集設定で指定する必要があります。例えば、ログソースが nginx、Pipeline ファイル名が nginx1.p の場合、Pipeline = "nginx1.p" と設定する必要があります。

[[inputs.nginx]]
        url = "http://localhost/server_status"
        # ##(optional) collection interval, default is 30s
        # interval = "30s"
        use_vts = false
        ## Optional TLS Config
        # tls_ca = "/xxx/ca.pem"
        # tls_cert = "/xxx/cert.cer"
        # tls_key = "/xxx/key.key"
        ## Use TLS but skip chain & host verification
        insecure_skip_verify = false
        # HTTP response timeout (default: 5s)
        response_timeout = "20s"

        [inputs.nginx.log]
                files = ["/var/log/nginx/access.log","/var/log/nginx/error.log"]
        #       # grok pipeline script path
                pipeline = "nginx.p"
        [inputs.nginx.tags]
        # some_tag = "some_value"
        # more_tag = "some_other_value"
        # ...

設定が完了したら、コマンド datakit --restart を使用して DataKit を再起動し、設定を反映させます。

Nginx 収集の詳細な設定については、Nginx を参照してください。

ステップ 2：収集したログに基づいて抽出フィールドを決定する¶

Nginx 収集を有効にし、ログファイルのパスを設定して Pipeline を有効にすると、Guance ワークスペースで収集した Nginx ログを表示できます。ログ詳細では、Pipeline ファイルに従って抽出されたフィールド属性を確認できます。ログを観察・分析し、抽出フィールドを最適化する必要があるかどうかを判断します。

ステップ 3：公式ライブラリの Pipeline をクローンしてカスタマイズする¶

Guance ワークスペースで ログ > Pipelines に移動し、Pipeline 公式ライブラリ をクリックして、nginx.p の Pipeline ファイルを表示してクローンします。

• ログのフィルタリング で "nginx" を選択します。
• 解析ルールの定義 で解析ルールを最適化します。
• ログサンプルテスト に nginx ログデータを入力し、設定した解析ルールに従ってテストします。

注意：

• Pipeline 公式ライブラリには複数のログサンプルテストデータが含まれています。「クローン」前に、自身のニーズに合ったログサンプルテストデータを選択できます。
• クローンした Pipeline を変更して保存すると、ログサンプルテストデータも同時に保存されます。

2022/02/23 14:26:19 [error] 632#632: *62 connect() failed (111: Connection refused) while connecting to upstream, client: ::1, server: _, request: "GET /server_status HTTP/1.1", upstream: "http://127.0.0.1:5000/server_status", host: "localhost"

ステップ 4：Pipeline ファイルを保存する¶

すべての必須項目を設定したら、Pipeline ファイルを保存します。ログ Pipelines リストにカスタム Pipeline ファイルが表示されます。

Guance ワークスペースで作成した Pipeline ファイルは、/usr/local/datakit/Pipeline_remote ディレクトリに一元的に保存されます。

注意：DataKit には 2 つの Pipeline ディレクトリがあり、DataKit はこれらのディレクトリ内の Pipeline ファイルを自動的に照合します。

• Pipeline：公式ライブラリの Pipeline ファイルディレクトリ。
• Pipeline_remote：Guance ワークスペースのカスタム Pipeline ファイルディレクトリ。
• 2 つのディレクトリに同名の Pipeline ファイルが存在する場合、DataKit は Pipeline_remote の Pipeline ファイルを優先します。

ステップ 5：Guance で抽出後のフィールドを確認する¶

Guance ワークスペースのログで、nginx のログを選択します。ログ詳細ページの「属性」に表示されるフィールドとフィールド値が、ログ抽出後に表示されるフィールドとフィールド値です。例：

• http_method: GET
• http_url: /server_status
• http_version: 1.1

参考情報¶

以上、Guance ワークスペースのログ Pipeline ユーザーガイドでした。Pipeline とログ収集抽出の詳細については、以下のドキュメントを参照してください。