JSON を使用した Source の設定
Source は、UTF-8 でエンコードされた JSON ファイルを使用して設定できます。Installed Collector でローカル設定ファイル管理を使用する場合は、JSON ファイルを使用して Source を設定できます。また、Hosted Collector と Installed Collector の Source は、Collector 管理 API を使用して設定することもできます。
詳細については以下のトピックを参照してください。
- Collector 管理 API
- Hosted Collector 用の JSON Source パラメータ
- Installed Collector 用の JSON Source パラメータ
- Collector または Source JSON 設定の表示またはダウンロード
Source JSON ファイルの定義
Collector を登録する際に、user.properties または sumo.conf 設定ファイルで sources
または syncSources
パラメータを使用して Source JSON ファイルを指定できます。これらのパラメータは、Collector を最初にセットアップする際に使用します。
パラメータ | タイプ | 説明 |
sources | 文字列 | 登録時に設定する Source を記述した JSON ファイルを設定します。Collector の設定後に Source を変更したい場合は、Collector 管理 API または Sumo Web アプリケーションを使用します。 |
syncSources | 文字列 | 登録時に設定する Source を記述した JSON ファイルの場所を設定します。このパラメータで指定したファイルは継続してモニタリングされ、Collector の設定と同期されます。 |
syncSources
パラメータの設定の詳細については、「ローカル設定ファイル管理」を参照してください。
JSON を使用した複数 Source の設定
JSON を使用して複数の Source を設定するには、以下の方法があります。
- 1 つの JSON ファイルにすべての Source の設定情報を記述する (sources.json)
- Source ごとに個別の JSON ファイルを作成して 1 つのフォルダに配置する。その後、個別の Source ではなく Source フォルダを設定できます。
詳細については「ローカル設定ファイルでの Source の指定オプション」を参照してください。
Source の種類
各 Source には、上記の表にある汎用フィールドに加えて、固有のフィールドを定義できます。有効なフィールド タイプを下表に示します。以下のセクションに、各 Source に固有のパラメータと関連する JSON ファイルの例を示します。
Installed Collector のログ Source
Source Type | タイプ値 |
ローカル ファイル Source | LocalFile |
リモート ファイル Source | RemoteFileV2 |
ローカル Windows イベント ログ Source | LocalWindowsEventLog |
リモート Windows イベント ログ Source | RemoteWindowsEventLog |
ローカル Windows パフォーマンス Source | LocalWindowsPerfMon |
リモート Windows パフォーマンス Source | RemoteWindowsPerfMon |
Syslog Source | syslog |
スクリプト Source | Script |
Docker ログ Source | DockerLog |
Docker 統計情報 Source | DockerStats |
Installed Collector のメトリクス Source
フィールド タイプ | タイプ値 |
ホスト メトリクス Source | SystemStats |
ストリーミング メトリクス Source | StreamingMetrics |
Hosted Collector のログ Source
フィールド タイプ | タイプ値 |
HTTP Source | HTTP |
クラウド Syslog Source | Cloudsyslog |
Amazon S3 Source | ポーリング |
AWS Elastic Load Balancing Source | ポーリング |
AWS CloudFront Source | ポーリング |
AWS CloudTrail Source | ポーリング |
AWS S3 Audit Source | ポーリング |
Hosted Collector のメトリクス Source
フィールド タイプ | タイプ値 |
AWS CloudWatch Source | ポーリング |
ログ Source タイプに共通のパラメータ
以下のパラメータは、syslog 以外のログ Source で使用されます。syslog Source は複数行検出はサポートしていないため、共通パラメータの multilineProcessingEnabled
、useAutolineMatching
、および manualPrefixRegexp
は使用できません。これらのパラメータを設定ファイルで指定しても無視されます。
パラメータ | タイプ | 必須 | デフォルト | 説明 | アクセス |
sourceType | 文字列 | はい | 正しい Source タイプを入力します (詳細については各 Source タイプを参照してください)。 | 変更不可 | |
name | 文字列 | はい | Source の名前を入力します。名前は Collector ごとに一意でなければなりません。この値はメタデータの _source フィールドに割り当てられます。 |
変更可 | |
description | 文字列 | 不可 | null | Source の説明を入力します。 | 変更可 |
フィールド | JSON オブジェクト | 不可 | null | Collector または Source に適用するキーと値のフィールド (メタデータ) の JSON マップ。 | 変更可 |
hostName | 文字列 | 不可 | null | Source のホスト名を入力します。この値はメタデータの _sourceHost フィールドに割り当てられます。ホスト名は最大 128 文字です。Windows ローカル イベント Source および Windows ローカル パフォーマンス Source ではサポートされません。 |
変更可 |
カテゴリ | 文字列 | 不可 | null | Source のカテゴリを入力します。この値はメタデータの _sourceCategory フィールドに割り当てられます。詳細については、「ベスト プラクティス」を参照してください。 |
変更可 |
タイプスタンプの処理 | |||||
automaticDateParsing | ブール | 不可 | true | タイムスタンプを parse するかどうかを指定します。true を指定すると、日付の自動 parse が有効になります (デフォルト設定)。false を指定すると無効になります。無効にすると、タイムスタンプ情報は parse されません。 |
変更可 |
timeZone | 文字列 | 不可 | null | Source が使用するタイム ゾーンを TZ データベース形式で入力します。例: "America/Los_Angeles" .詳細については「タイム ゾーンの形式」を参照してください。 |
変更可 |
forceTimeZone | ブール | 不可 | false | true を指定すると、Source は特定のタイム ゾーンを使用します。false を指定すると、Source はログで見つかったタイム ゾーンを使用します。デフォルト設定は false です。 |
変更可 |
defaultDateFormat | 文字列 | 不可 | null | (廃止予定) ログで使用されるデフォルトの日付形式。タイムスタンプ オプションの詳細は、「タイムスタンプ、タイム ゾーン、時間範囲、および日付フォーマット」を参照してください。 下記の置換オブジェクト defaultDateFormats を参照してください。 |
変更可 |
defaultDateFormats | オブジェクト配列 | 不可 | null | ログ メッセージ中の日付フォーマットを定義します。ロケーター正規表現を使用することで、ログ行中でのタイムスタンプの表示場所を指定できます。 defaultDateFormats オブジェクトには 2 つの要素があります。format (必須) — 日付形式を指定します。locator (省略可能) — ログ行中でのタイムスタンプの表示場所を指定する正規表現です。例を次に示します。\[time=(.*)\] 例については、下記の「タイムスタンプの例」を参照してください。 タイムスタンプ オプションの詳細は、「タイムスタンプ、タイム ゾーン、時間範囲、および日付フォーマット」を参照してください |
変更可 |
複数行の処理 | |||||
multilineProcessingEnabled | ブール | 不可 | true | true を指定すると有効、false を指定すると無効になります。デフォルト設定はtrue です。1 行に 1 つのメッセージが格納されているファイル (例: Linux の system.log) を収集する場合には false に設定しても構いません。複数行メッセージ (log4J や例外スタック トレースなど) を使用する場合は、有効のままにしておきます。 |
変更可 |
useAutolineMatching | ブール | 不可 | true | true を指定するとメッセージの境界が自動的に推定され、false を指定するとメッセージの境界が自動的に推定されなくなります (UI の Infer Boundaries オプションに相当します)。デフォルト設定は true です。 |
変更可 |
manualPrefixRegexp | 文字列 | 不可 | null | useAutolineMatching=false を指定する場合は、メッセージの最初の行と一致する正規表現を入力することで、境界を手動で定義してください。正規表現に特殊文字 (バックスラッシュや二重引用符など) が含まれる場合は、エスケープする必要があります。たとえば、次の式は ^\[\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2}:\d{2}\.\d{3}\].* 次のようにエスケープする必要があります。 ^\\[\\d{4}-\\d{2}-\\d{2}\\s+\\d{2}:\\d{2}:\\d{2}\\.\\d{3}\\].* |
変更可 |
処理ルール | |||||
filters | 文字列配列 | 不可 | [ ] | Source にフィルタを追加する場合は、フィルタの名前 (Exclude、Include、Hash、Mask、または Forward) を指定します。フィルタのルールと制限を確認し、「JSON を使用した処理ルールの作成」を参照してください。 | 変更可 |
コレクションの開始タイミング | |||||
cutoffTimestamp | Long | 不可 | 0 (すべてのデータを収集) |
cutoffRelativeTime の代わりに指定して、このタイムスタンプより新しいデータのみを収集できます。これは、エポック時刻からのミリ秒数 (13 桁) で指定します。エポック時刻への変換には次のサイトを利用できます。http://www.epochconverter.com/将来の時刻がサポートされています。 ローカル ファイル Source の場合、このカットオフは個別のログ行の時刻ではなく「修正後」の時刻に適用されます。たとえば、ファイル内のログのタイムスタンプが 1 週間にわたっている場合、cutoffTimestamp を 2 日前に設定しても、1 週間分のすべてのログが取り込まれます。これは、ファイル自体の変更時刻が cutoffTimestamp より後であるためです。処理ルールを使用すると、不要なログ メッセージに一致するログを絞り込むことができます。 Sumo がタイムスタンプを解釈し、処理する方法については、タイムスタンプの考慮事項を参照してください。 |
変更可 |
cutoffRelativeTime | 文字列 | 不可 | cutoffTimestamp の代わりに指定することで、現在時刻に対する相対オフセットを指定できます。time には、月 (M )、週 (w )、日 (d )、時 (h )、または分 (m ) を指定できます。現在の時刻を指定するには、0m を使用します。将来の時刻はサポートされません。 例: -1h 、-1d 、-1w で、それぞれ 1 時間、1 日、1 週間前の時刻を指定します。ローカル ファイル Source の場合、このカットオフは個別のログ行の時刻ではなく「修正後」の時刻に適用されます。たとえば、ファイル内のログのタイムスタンプが 1 週間にわたっている場合、cutoffRelativeTime を 2 日前に設定しても、1 週間分のすべてのログが取り込まれます。これは、ファイル自体の変更時刻が cutoffRelativeTime より後であるためです。処理ルールを使用すると、不要なログ メッセージに一致するログを絞り込むことができます。 Sumo がタイムスタンプを解釈し、処理する方法については、タイムスタンプの考慮事項を参照してください。 |
変更不可 |
設定できないパラメータ
以下のパラメータは Sumo Logic サービスによって自動的に設定されます。API リクエストを生成する場合を除いて、これらのパラメータは Source JSON ファイルには指定しないでください。API リクエストでは、JSON ファイルに id
パラメータを指定する必要があります。
- id
- alive - このパラメータは、Sumo がハートビート メッセージを 15 秒おきに受信するたびに更新されます。ハートビートによって接続が確立されていることが確認されます。ハートビート メッセージが 30 分間受信できないと、このパラメータは false になります。
- status
タイム ゾーンの形式
JSON Source の設定において、timeZone
設定の文字列は、Sumo Logic Web アプリケーションで表示されるタイム ゾーン設定と同じ形式には準拠しません。JSON timeZone
プロパティは、(GMT+11:00) スタイルの値ではなく、基礎となる TZ データベースのタイム ゾーン形式を使用します。
例:
"timeZone": "America/Los_Angeles",
タイム ゾーン環境変数のリストは、この Wikipedia 記事に掲載されています。
タイムスタンプの例
JSON の 2 つのデフォルト日付フォーマットである yyyy-MM-dd HH:mm:ss
と yyMMdd HH:mm:s
でのタイムスタンプの例を示します。
{ "source": { "name": "test", "defaultDateFormats": [{ "format": "yyyy-MM-dd HH:mm:ss", "locator": "time=(.*)," }, { "format": "yyMMdd HH:mm:ss" }] } }
JSON を使用した処理ルールの作成
JSON を使用して Source を設定する際には、処理 (フィルタリング) ルールを定義することができます。フィルタは、Sumo Logic に送信するメッセージを選別するためのルールを指定します。フィルタには 4 つのタイプがあります。
- Exclude (除外) — Sumo Logic に取り込む前にメッセージを削除します。Exclude は「ブラックリスト」フィルタだと考えてください。詳細については、「包含ルールと除外ルール」を参照してください。
- Include (包含) — 定義したデータのみを Sumo Logic に送信します。Include は「ホワイトリスト」フィルタだと考えてください。詳細については、「包含ルールと除外ルール」を参照してください。
- Hash (ハッシュ) — ランダムに生成される一意のコードでメッセージを置き換えることで、クレジット カード番号やユーザ名などの機密情報を保護します。このタイプのデータをハッシュ変換することで、データが完全に非表示の場合でもトラッキングすることができます。詳細については、「ハッシュ ルール」を参照してください。
- Mask (マスク) — 式をカスタマイズ可能なマスク文字列に置換します。特に、通常はトラッキングの対象とはならないパスワードなどのデータを保護するのに便利です。詳細については、「マスク ルール」を参照してください。
- Forward (転送) — 一致したログ メッセージを Data Forwarding の宛先に送信します。詳細については、下記の「例: Data Forwarding ルール」を参照してください。
パラメータ | タイプ | 必須 | 説明 | アクセス |
name | 文字列 | はい | ルールの名前。 | 変更可 |
filterType | はい | フィルタ タイプ。Exclude、Include、Hash、Mask、または Forward のいずれかを指定します。 | 変更可 | |
regexp | 文字列 | はい | フィルタを定義するための正規表現。filterType = Mask または Hash の場合、この正規表現では、マスクまたはハッシュで置き換える領域を指定する最低 1 つのグループが一致する必要があります。 複数行メッセージの場合は、文字列がメッセージ内のどこにあっても一致するように、単一行モディファイア (?s) を式の先頭と末尾に付加してください。例:(?s).*secur.*(?s) syslog UDP メッセージの最後には改行文字が含まれる場合があるため、文字列と正しく一致させるためには上記の正規表現が必要になります。 |
変更可 |
mask | 文字列 | 敗 (filterType = Mask の場合) | 一致したログ テキストをマスクするための文字列。 | 変更可 |
transparentForwarding | ブール | 不可 | syslog 転送では、RFC 3164 に準拠するためにデフォルトでメッセージの先頭にタイムスタンプとホスト名が追加されます。syslog メッセージがすでに準拠している場合は、このパラメータを false に設定してこの機能を無効にできます。 |
変更可 |
例: 除外フィルタ
指定したキーワードを含むメッセージを除外するフィルタの例を以下に示します。
"filters":[{ "filterType":"Exclude", "name":"filter_auditd", "regexp":".*exe=\"\\/usr\\/sbin\\/crond\".*terminal=cron\\sres=success.*" }],
*("test")*,
など、特殊文字を使用した文字列を含むメッセージを除外する場合は、JSON で正しく解釈されるように、特殊文字を二重エスケープする必要があります。
フィルタするメッセージの例:
*("test")*
標準正規表現 (UI を使用してフィルタを作成する場合の構文):
\*\("test"\)\*
JSON のフィルタ構文:
\\*\\(\"test\"\\)\\*
特殊文字を二重エスケープした JSON のフィルタ例:
{ "source": { "name": "test", "filters": [{ "filterType": "Exclude", "name": "Filter keyword", "regexp": "\\*\\(\"test\"\\)\\*" }] } }
例: マスク フィルタ
承認トークンを含むメッセージをマスクするフィルタの例を以下に示します。
フィルタするメッセージの例:
auth":"Basic cABC123vZDAwfvDldmlfZ568dWQ6vvhjER4dgyR33lP"
標準正規表現 (UI を使用してフィルタを作成する場合の構文):
auth"\s*:\s*"Basic\s*([^"]+)"
JSON のフィルタ構文:
auth\"\\s*:\\s*\"Basic\\s*([^\"]+)\"
特殊文字を二重エスケープした JSON のフィルタ例:
"filters":[{ "filterType":"Mask", "name":"masktoken", "regexp":"auth\"\\s*:\\s*\"Basic\\s*([^\"]+)\"", "mask":"##TOKEN##" },
例: Data Forwarding ルール
以下の JSON Source 設定では、フィルタ配列によって Data Forwarding ルールを指定しています。JSON で Data Forwarding ルールを設定するためには、Data Forwarding 先の sinkId を取得する必要があります。詳細については、下記の「Data Forwarding 先の sinkId の取得」を参照してください。
{ "api.version": "v1", "sources": [{ "sourceType": "Syslog", "name": "example", "port": 514, "protocol": "TCP", "encoding": "UTF-8", "category": "example", "useAutolineMatching": false, "multilineProcessingEnabled": false, "timeZone": "UTC", "automaticDateParsing": true, "forceTimeZone": false, "defaultDateFormat": "dd/MMM/yyyy HH:mm:ss", "filters": [{ "filterType": "Forward", "name": "example", "regexp": "(?s).*(?s)", "sinkId": 22, "transparentForwarding": false }] }] }
Data Forwarding 先の sinkId の取得
Data Forwarding 先の sinkId を取得するには、Sumo Web アプリケーションで試験的な Data Forwarding ルールを作成します。Sumo は、選択した転送先の sinkId で Source の JSON 設定を更新します。その後、Source の JSON 設定を表示して、sinkId をメモしてから、試験的な Data Forwarding ルールを削除します。
これらの手順では、Data Forwarding 先はすでに作成されていることを前提としています。
- Installed Collector の Source に Data Forwarding ルールを追加する方法については、「Data Forwarding の処理ルールの設定」を参照してください。このプロセスでは、Data Forwarding の宛先を選択します。
- 上の手順で更新した Source の JSON 設定を表示するには:
- [Manage Data (データの管理)] > [Collection (コレクション)] > [Collection (コレクション)] を選択します。
- Source の右側にあるアイコンをクリックします。[API usage information (API 利用情報)] パネルが表示されます。JSON のフィルタ セクションにある sinkId をメモします。
- Source の右側にあるアイコンをクリックします。JSON のフィルタ セクションにある sinkId をメモします。
- [API usage information (API 利用情報)] パネルで [Done (終了)] をクリックします。
- Data Forwarding 先の sinkId が判別しましたので、試験的なルールを削除します。
- [Manage Data (データの管理)] > [Collection (コレクション)] > [Collection (コレクション)] を選択します。
- 試験的なルールに追加した Source に移動します。
- ページの [Processing Rules (処理ルール)] セクションで、試験的なルールの右側にある削除アイコンをクリックします。
Data Forwarding 先の sinkId を取得しましたので、上記の「例: Data Forwarding ルール」の例に従って Source の JSON 設定でフィルタ配列を定義できます。