コンテンツにスキップ

ログ 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 が自動的に生成されます。

解析ルールの定義

ログの解析ルールを定義します。複数のスクリプト関数に対応しています。編集エリアにはデフォルトでソースコードが表示され、フローチャートに切り替えると分岐やループの処理関係を確認でき、ステップモードに切り替えるとスクリプトを項目ごとに確認できます。3つのモードは同じスクリプトを共有し、関数ライブラリをクリックすると関数の説明と構文形式を確認できます。

フローチャートまたはステップモードでノードをクリックすると、パラメータやノードのソースコードを変更でき、適用をクリックすると完全なスクリプトに同期されます。また、挿入、削除、上下の移動、同一コードブロック内でのドラッグによる並べ替えも可能です。具体的な操作と使用上の制限については、解析ルールの編集 を参照してください。

この例では、ログの観察結果に基づいて 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) を参照してください。

ログサンプルのテスト

スクリプトのルールを作成したら、テストサンプルにログを手動で入力するか、サンプルをワンクリック取得をクリックします。ログサンプルは、「Message のみ」「全フィールド(JSON)」「全フィールド(ラインプロトコル)」の3つの形式に対応しています。

サンプルを追加をクリックするとサンプルを追加できます(最大3件)。タブを切り替えて編集します。テストを開始をクリックすると、空でないすべてのサンプルが実行され、結果は編集エリア右側の独立したオーバーレイにサンプルごとに表示されます。閉じた後は結果を表示から再度開くことができ、拡大、コピー、または固定してドラッグすることもできます。

スクリプトまたはサンプルを変更した後、以前の結果は再テスト待ちとマークされます。現在の解析結果を確認するには、再実行してください。詳細な操作については、テストサンプル と テスト結果の表示 を参照してください。

注意:

  • ログサンプルのテストは任意項目です。
  • カスタム Pipeline を保存すると、ログサンプルのテストデータも同時に保存されます。
  • JSON サンプルは有効なオブジェクトである必要があります。テストと保存の前に、現在選択されていないタブを含むすべてのサンプルが検証されます。

ステップ 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 とログ収集・パースの詳細については、次のドキュメントを参照してください。

フィードバック

このページは役に立ちましたか?