ジョブファイルを使用したログ分析の構成

Related pages:

このページでは、ジョブファイルを使用してログソースを設定する方法について説明します。新しいログソースを設定する場合は、中央集中型ログ管理 UI を使用してソースルールを定義することをお勧めします。

ジョブファイルを使用してログ分析を構成するには、次の手順を実行します。

ジョブファイルでのログソースの記述
ログファイルデータの分析フィールドへのマッピング
分析エージェントのプロパティの確認

ジョブファイルでのログソースの記述

各ログソースは、ジョブファイルで示されます。ジョブファイルは、以下を指定する設定ファイルです。

ソースログファイルの場所
ログファイルからレコードをキャプチャするためのパターン
キャプチャされたログレコードからデータを構造化するためのパターン
ログソースからレコードをキャプチャするためのその他のオプション

ソースを定義するには、分析エージェントの設定ディレクトリにジョブファイルを作成します（または、いずれかのサンプルを変更します）。分析エージェントには、Glassfish、OSX ログなどのサンプルのジョブファイルが含まれています。また、分析エージェントは GZIP ファイル（末尾が .gz のログファイル）を収集して解析することもできます。

ジョブファイルは、次のディレクトリにあります。

<Analytics_Agent_Home>/conf/job/

エージェントはディレクトリ内のジョブファイルを動的に読み取ります。そのため、エージェントを再起動せずにジョブファイルをディレクトリに追加できます。

ジョブファイルを設定するには、ファイルで次の設定可能な構成を使用します。

enabled：このログソースがアクティブかどうかを決定します。このログソースから分析データをキャプチャするには、値を true に設定します。
source：ログのソースを指定します。
- type：ログソースのタイプを指定します。file と syslog の 2 つのタイプがあります。その他のパラメータは、type の値によって異なります。
  - file：ログソースとして機能するログファイルの場所と名前。場所は、analytics-agent と同じマシン上にある必要があります。ファイルには、次のパラメータがあります。
    - path：ログファイルが格納されているディレクトリへのパス。Windows では、次のように Unix 環境上のようにパスを指定する必要があります。
    - 例：demo/logs
    - 例：C:/app/logs
    - nameGlob：ログファイル名での照合に使用する文字列。ワイルドカードを使用できます。また、1 レベル深いファイルと照合するか、パスディレクトリ構造内のすべてのログファイルと照合するかどうかを指定できます。ワイルドカードが nameGlob の値で始まる場合は、値を引用符で囲む必要があります。サポートされている照合パターンは、次の場所で確認できます。http://java.boot.by/ocpjp7-upgrade/ch06s05.html（「glob」の下）
    - 複数レベルの照合の例：
      path：/var/log
      nameGlob：'**/*.log'
      これは /var/log/apache2/logs/error.log と /var/log/cassandra/system.log の両方に一致します。
    - 1 レベルの照合の例：
      path：/var/log
      nameglob：'*/*.log'
      これは、/var/log ディレクトリ内を 1 レベルの深さで .log ファイルを検索します（/var/log/cassandra/system.log と一致しますが、/var/log/apache2/logs/error.log とは一致しません）。
    - startAtEnd：true に設定すると、ファイルの末尾からの照合を許可します。
  - syslog：「Syslog メッセージからのログ分析データの収集」を参照してください。
- multiline：複数行にまたがる（複数の改行を含む）ログレコードが含まれているログファイルの場合は、multiline プロパティを設定し、ログファイル内の個々のレコードを識別する方法を指定します。複数行のログレコードの典型的な例は、Java 例外を含むレコードです。複数行のログレコードの行を識別するには、multiline プロパティで 2 つのオプションのいずれかを使用できます。
  - startsWith：複数行のログレコードの先頭に一致する単純なプレフィックス。
    例 1：次の複数行ログを 1 つのレコードとしてキャプチャする方法：
    [#|2015-09-24T06:33:31.574-0700|INFO|glassfish3.1.2|com.appdynamics.METRICS.WRITE|_ThreadID=206;_ThreadName=Thread-2;|NODE PURGER Completed in 14 ms|#]
    以下を使用できます。
    multiline: startsWith: "[#|"
    例 2：次の複数行ログを 1 つのレコードとしてキャプチャする方法：
    May 5, 2016 6:07:02 AM com.appdynamics.test.payments.plugin.testsource.testPaymentClient deposit(pluginContext, financialTransaction, retry) INFO: Source deposit requested amount:245.43000 May 5, 2016 6:07:02 AM com.appdynamics.test.payments.plugin.testsource.testPaymentClient deposit(pluginContext, financialTransaction, retry) INFO: Source deposit currency:USD May 5, 2016 6:07:02 AM com.appdynamics.test.payments.plugin.testsource.testPaymentClient deposit(pluginContext, financialTransaction, retry) INFO: Source deposit payment method:Master Card May 5, 2016 6:07:03 AM com.appdynamics.test.payments.plugin.testsource.testPaymentClient deposit(pluginContext, financialTransaction, retry) INFO: Source deposit decision:ACCEPT May 5, 2016 6:07:03 AM com.appdynamics.test.payments.plugin.testsource.testPaymentClient deposit(pluginContext, financialTransaction, retry) INFO: Source deposit reason code:200 May 5, 2016 6:07:03 AM com.appdynamics.test.payments.plugin.testsource.testPaymentClient deposit(pluginContext, financialTransaction, retry) INFO: Source deposit orderId:7654 May 5, 2016 6:07:03 AM com.appdynamics.test.payments.plugin.testsource.testPaymentClient deposit(pluginContext, financialTransaction, retry) INFO: Source deposit piId:1234B May 5, 2016 6:07:03 AM com.appdynamics.test.payments.plugin.testsource.testPaymentClient deposit(pluginContext, financialTransaction, retry) INFO: Source deposit referenceNumber:4620346703956702001 May 5, 2016 6:07:03 AM com.appdynamics.test.payments.plugin.testsource.testPaymentClient deposit(pluginContext, financialTransaction, retry) INFO: Source deposit extData requestToken:alf/7wSR9PBh3zSMQ+++IYTRlk3Ys2DOxOmM5jWLRTyFJaSggCTyFJaSgjSB1/2v0wyTWRV0ekb0X
    以下を使用できます。
    multiline: startsWith: "INFO: Source deposit requested amount"
  - regex：複数行のログレコードに一致する正規表現。
    例：この複数行ログを 1 つのレコードとしてキャプチャする方法：
    2016-06-01 16:28:21.035 WebContainer : 8 TRANSTART> ======================================= 2016-06-01 16:28:21.036 WebContainer : 8 MERCHCFG > merchantID=appD, sendToProduction=true, targetAPIVersion=1.00, keyFilename=(null), serverURL=(null), namespaceURI=(null), enableLog=true, logDirectory=logs, logFilename=(null), logMaximumSize=10, useHttpClient=false, timeout=130 2016-06-01 16:28:21.037 WebContainer : 8 REQUEST > merchantID=appD davService_run=true clientLibraryVersion=2.0.1 clientEnvironment=OS/400/V7R1M0/LINUX application_id=ff22 exportService_addressWeight=medium merchantReferenceCode=appD clientLibrary=Java Basic billTo_customer=xxxxxxxxx billTo_finance=true billTo_postalCode=94105 billTo_country=US
    次の正規表現設定を使用すると、各「レコード」の開始を識別できます。
    multiline: regex: "^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\.\d{3} WebContainer : \d+ TRANSTART\u003E =======================================$"
    この regex は、行が、4 桁（2016）、2 桁（01）、スペース、2 桁（16）、「:」2 桁（28）「:」2 桁（21）「.」3 桁（035）、スペース、「WebContainer」、スペース、数字、「TRANSTART」、「>」に一致することを記述しています。
    ログテーラーは、行の先頭で一致パターンを確認するたびに新しい照合を開始し、以前に収集されたデータを 1 つのログレコードとして渡します。それぞれの一致パターンは、一致パターンが別のレコードの先頭で再度検出されるまで、バッファ内へのログ行の累積を開始するタイミングを識別します。
  複数行のログファイルの特定の形式で、正規表現による信頼できる連続行の照合が許可されていない場合は、単一行の形式を使用することもできます。ほとんどのタイプのログでは、これによりほとんどのログレコードがキャプチャされることになります。
fields：フィールドは、アプリケーション名、ティア名などによってコントローラ UI でのログデータのコンテキストを指定するために使用されます。フィールドは、自由形式のキーと値のペアとして指定します。
grok：grok パラメータは、非構造化ログレコード内のデータが構造化分析フィールドにマッピングされるパターンを指定します。名前付き grok 式（lib/analytics-shared-pipeline-core.jar 内にバンドルされている .grok ファイルで定義されている）を、エージェントによって構造化されたデータのフィールドに関連付けます。次に例を示します。
```
grok:
  patterns: 
       - "\\[%{LOGLEVEL:logLevel}%{SPACE}\\]  \\[%{DATA:threadName}\\]  \\[%{JAVACLASS:class}\\]  %{GREEDYDATA}"
       - "pattern 2"
       ... 
```
この場合、grok-pattern 名 LOGLEVEL は、logLevel という名前の分析データフィールドと一致します。名前 LOGLEVEL で指定された正規表現は、grok ディレクトリ内のファイル grok-patterns.grok で定義されています。「Grok 式の指定」を参照してください。
以前のバージョンのログ分析では、パターンリストではなく、単一の「パターン」が使用されていました。このモードは、下位互換性を維持するためにサポートされています。
ログ分析 grok プロセッサでは、フィールド名にアンダースコアを使用できません。たとえば、フィールド名「log_fields」は機能しません。代わりに、「logfields」などを使用します。
keyValue：keyValue パラメータは、ユーザ定義の区切り文字を使用してキーと値のペアを識別し、ログを解析する方法を指定します。これにより、「Key1 = Value1 Key2 = Value 2」というタイプのメッセージの解析を設定できます。「キーと値のペアの指定」を参照してください。
transform：このパラメータは、grok または keyValue パラメータによってログから抽出されたフィールドのタイプまたはエイリアス名を変更する方法を指定します。
eventTimestamp：この設定は、キャプチャしたデータに関連付けられているタイムスタンプのパターンを定義します。

ログファイルデータの分析フィールドへのマッピング

非構造化ログレコード内のデータをログ分析のために構造化分析フィールドにマッピングする方法を指定するには、ジョブファイルで設定を指定します。非構造化ログデータは、次の方法でマッピングできます。

grok パターン
キーと値のペア
トランスフォーム

Grok 式の指定

Grok は、ネストされた複雑な正規表現を読みやすく使用しやすい形式で定義して使用する方法です。ログファイル内の個別の要素を定義する正規表現は、grok-pattern 名にマッピングされます。これを使用すると、より複雑なパターンを作成することもできます。

分析エージェントでは、ログで見つかる一般的な種類のデータの多くの Grok-pattern 名が提供されています。基本的な grok-pattern 名とその基盤となる構造のリストは、lib/analytics-shared-pipeline-core.jar 内部にバンドルされています。次のようなコマンドを使用して grok ファイルを一覧表示できます。

unzip -l ./lib/analytics-shared-pipeline-core.jar|grep "\.grok"

CODE

次のようなコマンドを使用して grok ファイルの定義を表示できます。

unzip -p ./lib/analytics-shared-pipeline-core.jar grok/grok-patterns.grok

CODE

grok ディレクトリには、さまざまな一般的なログタイプ（java.grok, mongodb.grok など）に対してカスタマイズされた複雑な定義のサンプルも含まれています。追加の grok パターンについては、https://grokdebug.herokuapp.com/patterns# を参照してください。

grok-pattern 名は、作成されると、分析キーになるフィールド識別子を持つジョブファイルに関連付けられます。

基本的な構成要素は %{grok-pattern name:identifier} です。ここで、grok-pattern name は、（正規表現の定義に基づいて）取得するログ内のデータのタイプを認識する grok パターンであり、identifier は分析キーになるデータの種類の識別子です。このため、%{IP:client} はログレコード内の IP アドレスを選択し、キー client. にマッピングします。

カスタム Grok パターン

複雑な grok パターンは、ネストされた基本パターンを使用して作成できます。mongodb.grok ファイルからの例を次に示します。

MONGO_LOG %{SYSLOGTIMESTAMP:timestamp} \[%{WORD:component}\] %{GREEDYDATA}

正規表現を使用して、まったく新しいパターンを作成することもできます。たとえば、java.grok の次の行は、JAVACLASS という名前の grok パターンを定義します。

JAVACLASS (?:[a-zA-Z$_][a-zA-Z$_0-9]*\.)*[a-zA-Z$_][a-zA-Z$_0-9]*

JAVACLASS は grok ディレクトリ内の .grok ファイルで定義されているため、基本の grok パターンであるかのように使用することができます。ジョブファイルでは、次のように JAVACLASS パターン照合を使用できます。

grok:
  pattern: ".... \[%{JAVACLASS:class}\\]

この場合、分析 UI に表示されるフィールド名は「class」になります。完全なサンプルについては、次のファイルを参照してください。

ジョブファイル：<Analytics_Agent_Home>/conf/job/sample-analytics-log.job
Grok ファイル：java.grok（lib/analytics-shared-pipeline-core.jar 内でバンドル）

バックスラッシュに関する特別な考慮事項

ジョブファイルは YAML 形式であり、バックスラッシュはエスケープ文字として扱われます。したがって、文字列パターンにバックスラッシュを含めるには、2 つ目のバックスラッシュを使用してバックスラッシュをエスケープする必要があります。次のように grok パターンを二重引用符ではなく一重引用符で囲むことにより、.job ファイルの grok パターンでバックスラッシュをエスケープする必要がないようにすることができます。

grok:
  patterns:
    - '\[%{DATESTAMP:TIME}%{SPACE}CET\]%{SPACE}%{NOTSPACE:appId}%{SPACE}%{NOTSPACE:appName}%{SPACE}%{NOTSPACE:Severity}%{SPACE}%{NOTSPACE:messageId}:%{SPACE}%{GREEDYDATA}'

数値フィールド

リリース 4.1.3 では、3 つの基本データ型をサポートするように grok 定義構文が拡張されました。.grok ファイルでパターンを定義するときは、データ型として数値、ブール値、または文字列を指定できます。Grok エイリアスが .job ファイルでその grok 定義を使用している場合、抽出されたフィールドは数値またはブール値として保存されます。デフォルトは文字列です。数値またはブール値の変換が失敗すると、エージェントのログファイルにログメッセージが表示されます。正規表現を確実にリバースエンジニアリングすることはできないため、検証は実行されません。これらは純粋なランタイム抽出および変換です。

4.1.3 以前のジョブファイルのアップグレード

4.1.2（またはそれ以前）で、NUMBER として指定されていない、または指定されているフィールドがあり、現在は「型認識」ファイルに切り替わっている使用中の .job ファイルでは、イベントサービス内のデータが破棄されます。これは、型のマッピングが原因です。これを回避するには、ジョブファイルの grok エイリアスを変更する必要があります。
例：

Was:
grok:
  patterns:
    - "%{DATE:happenedAt},%{NUMBER:quantity}

Update job to:
grok:
  patterns:
    - "%{DATE:happenedAt},%{NUMBER:quantity_new}

Was:
grok:
  patterns:
    - "%{DATE:happenedAt},%{DATA:howMany}

Update job to:
grok:
  patterns:
    - "%{DATE:happenedAt},%{POSINT:howManyInt}

4.1.3 より前のジョブファイルをアップグレード（移行）するには、次の手順を実行します。

analytics-agent を停止します。

拡張 grok パターンを使用する .job ファイルを変更します。

BOOL:boolean
INT:number
BASE10NUM:number
NUMBER:number
POSINT:number
NONNEGINT:number

古いエイリアスと競合しないように grok エイリアスを変更します。

grok:
  patterns:
(Old)  - "%{DATE:quoteDate},%{NUMBER:open},%{NUMBER:high},%{NUMBER:low},%{NUMBER:close},%{NUMBER:volume},%{NUMBER:adjClose}"

(New aliases)  - "%{DATE:quoteDate},%{NUMBER:openNum},%{NUMBER:highNum},%{NUMBER:lowNum},%{NUMBER:closeNum},%{NUMBER:volumeNum},%{NUMBER:adjCloseNum}"

analytics-agent を起動します。

キーと値のペアの指定

マッピング設定のこのセクションでは、source パラメータで指定されたフィールドからキーと値のペアをキャプチャします。source の下にリストされている値は、grok パターンによって定義およびキャプチャされたフィールドを参照します。たとえば、次のパターン「%{DATA:keyValuePairs}」を定義する grok パラメータがある場合は、source パラメータの下にあるフィールド「keyValuePairs」をリストして、「keyValuePairs」文字列に記載されているキーと値のペアをキャプチャできます。source パラメータが指定されていない場合、エージェントはログメッセージ全体からキーと値のペアの抽出を試行します。メッセージにキーと値のペアだけではなく、より多くの情報が含まれている場合、結果は予想とは異なる場合があります。

キーと値のマッピングには、次のフィールドが含まれています。

source：keyValue フィルタを適用する文字列のリスト。これはオプションのフィールドです。指定されていない場合、キーと値のペアは元のログ「message」文字列から解析されます。
split：値からキーを区切るためにユーザによって定義された区切り文字。key=value の例では、キーと値の間の分割区切り文字は等号（=）です。
separator：2 つのキーと値のペアを区切るためにユーザによって定義された区切り文字。key1=value1;key2=value2 の例では、区切り文字はセミコロン（;）です。
include：ユーザが「source」からキャプチャするキー名のリスト。「include」で何も指定されていない場合は、すべてのキーと値のペアをキャプチャします。
trim：保存される前に、ユーザにとってキーまたは値の先頭または末尾から削除する必要がある文字のリスト。

sample-glassfish-log.job ジョブファイルには、キーと値のペアの設定が含まれています。このファイルは、次の場所にあります。<analytics_agent_home>/conf/job/

キーと値のペアの例

次のエントリを含むログファイルの場合：

次の grok パターン：

grok:
  patterns:
    - "\\[\\#\\|%{DATA}\\|%{LOGLEVEL:logLevel}\\|%{DATA:serverVersion}\\|%{JAVACLASS:class}\\|%{DATA:keyValuePairs}\\|%{GREEDYDATA}"

ThreadID と ThreadName を抽出するためのキーと値のパラメータは、次のようになります。

keyValue:
  source:
	-"keyValuePairs"
  split: "="
  separator: ";"
  include:
	- "ThreadID"
	- "ThreadName"	
  trim:
	- "_"

トランスフォームパラメータの指定

マッピング設定のこのセクションでは、grok またはキー値の設定によって以前にログから抽出されたフィールドの型またはエイリアス名を変更することができます。トランスフォームは、ログメッセージからすべてのフィールドがキャプチャされた後に適用されます。フィールド名のリストを指定して、値を特定の型にキャストしたり、フィールドの名前を「alias」に変更したりすることができます。

トランスフォームマッピングには、次のフィールドが含まれています。

field：トランスフォームするフィールドの名前を指定します。空白または null にすることはできません。field が定義されている場合は、type または alias のいずれかを指定する必要があります。いずれも指定されていない場合は、analytics-agent.log ファイルにエラーが書き込まれます。
alias：フィールドの新しい名前。
type：フィールドの値の型。有効な値は次のとおりです。
- NUMBER
- BOOLEAN
- STRING：デフォルトは STRING です。

分析エージェントのプロパティの確認

ジョブファイルでログソースを設定することに加えて、conf ディレクトリ内にある analytics-agent.properties ファイルの値を確認する必要があります。次のプロパティ値を確認します。

http.event.endpoint はイベントサービスの場所である必要があります。
- SaaS コントローラの場合、URL は次のいずれかになります。
  - https://analytics.api.appdynamics.com:443（北米）
  - https://fra-ana-api.saas.appdynamics.com:443（欧州）
  - https://syd-ana-api.saas.appdynamics.com:443（アジア太平洋地域）
- オンプレミスインストールの場合、ユーザが設定したホストとポートを使用します。クラスタ環境では、多くの場合、これはロードバランサです。
http.event.accountName および http.event.accessKey 設定は、ログを関連付ける必要があるコントローラ UI 内のアカウントの名前およびキーに設定する必要があります。デフォルトでは、1 つのテナントコントローラの組み込みアカウントに設定されます。
pipeline.poll.dir 設定は、ログ設定ファイルの場所を指定します。これは通常、ファイルを別の場所に保存しない場合は変更されません。
ad.controller.url は AppDynamics コントローラの URL およびポートと一致している必要があります。

ログのトラブルシューティング

ログキャプチャが正常に動作している場合、分析 UI の [Log] タブでログの表示が開始されます。ログの蓄積が開始されるまでには時間がかかることがあります。以下のトラブルシューティングポイントに注意してください。

ログビューに何も表示されない場合は、過去 24 時間の検索を試行してください。
ログとローカルマシン間のタイムゾーンの不一致により、コントローラ UI で選択したタイムフレームに基づいてログエントリが誤って除外されることがあります。修正するには、ログファイルとシステムの時刻を UTC に設定するか、ログメッセージにタイムゾーンを記録して確認してください。
インデックスの固有の遅延により、UI の「last minute」ビューで常にログが生成されない場合があります。この問題が発生した場合は、時間範囲を増やします。

パターンのトラブルシューティング

ジョブファイルのデータ抽出パターンのトラブルシューティングに役立つように、分析エージェントでは次の 2 つのデバッグ REST エンドポイントを使用できます。

http://<Analytics_Agent_host>:<Analytics_Agent_http_port>/debug/grok：grok パターンのテスト用
http://<Analytics_Agent_host>:<Analytics_Agent_http_port>/debug/timestamp：タイムスタンプパターンのテスト用

以下の例では、Analytics エージェントのホストが localhost、Analytics エージェントのポートが 9090 であることを想定しています。エージェントのポートを設定するには、<Analytics_Agent_Home>/conf/analytics-agent.properties. のプロパティ ad.dw.http.port を使用します。

バージョン 21.7 以降の分析エージェントでは、debug/grok エンドポイントはデフォルトで無効になっています。エンドポイントを有効にするには、agent.properties ファイルの ad.debug.grok.endpoint.enabled=true プロパティを使用して分析エージェントを起動します。

Grok エンドポイント

Grok ツールは、1 行のログからの抽出と、複数行のログからの抽出の 2 つのモードで動作します。使用オプションの説明を取得するには、次のようにします。

curl -X GET http://localhost:9090/debug/grok

単一回線

このモードでは、テストするログと grok パターンのサンプル行を（POST 要求として）渡し、キーと値のペアとして編成された渡したデータを受け取ります。ここで、キーは識別子です。

curl -X POST http://localhost:9090/debug/grok --data-urlencode "logLine=LOG_LINE" --data-urlencode "pattern=PATTERN"

入力の例を次に示します。

curl -X POST http://localhost:9090/debug/grok --data-urlencode "logLine=[2014-09-04T15:22:41,594Z]  [INFO ]  [main]  [o.e.j.server.handler.ContextHandler]  Started i.d.j.MutableServletContextHandler@2b3b527{/,null,AVAILABLE}" --data-urlencode "pattern=\\[%{LOGLEVEL:logLevel}%{SPACE}\\]  \\[%{DATA:threadName}\\]  \\[%{JAVACLASS:class}\\]  %{GREEDYDATA}"

次の出力が生成されます。

{
 threadName =&gt; main
 logLevel =&gt; INFO
 class =&gt; o.e.j.server.handler.ContextHandler
}

次の入力の場合：

curl -X POST http://localhost:9090/debug/grok --data-urlencode "logLine=2010-05-05,500.98,515.72,500.47,509.76,4566900,509.76" --data-urlencode "pattern=%{DATE:quoteDate},%{DATA:open},%{DATA:high},%{DATA:low},%{DATA:close},%{DATA:volume},%{GREEDYDATA:adjClose}"