ログ検索クエリ構文

Auth0のログ検索を絞り込むために、Luceneクエリ構文の一部を使った検索クエリ構文について説明します。

ログを検索する際は、Lucene query syntax の一部を使用してクエリを作成し、検索条件を絞り込むことができます。

クエリ文字列は、一連のタームと演算子として解析されます。

• タームは、jane や smith のような単一の語の場合があります。
• タームは、二重引用符で囲まれたフレーズ ("customer log") の場合もあり、その場合はフレーズ内のすべての語が同じ順序で一致します。
• フィールド名のないタームは、これらの選択されたフィールドにのみ一致します。
• 複数のタームは、かっこでグループ化してサブクエリを作成できます。
• すべての検索フィールドでは、大文字と小文字が区別されます。
• 演算子 (AND、OR、NOT) は、検索可能なすべてのフィールドで機能します。

​

検索可能なフィールド

以下のフィールドは検索可能であり、大文字と小文字は区別されます。

Field	Description
client_id	イベントに関連する Client ID。
client_name	イベントに関連するクライアント名。
connection	イベントに関連する接続名。
connection_id	イベントに関連する接続 ID。
description	イベントの説明。
date	イベントが発生した日付 (YYYY-MM-DD 形式) 。
hostname	認証フローで使用されるホスト名。
ip	ログエントリの原因となったリクエストの送信元 IP アドレス。
log_id	イベントのログ ID。
organization_id	イベントに関連する組織 ID。
user_id	イベントに関連するユーザー ID。
user_name	イベントに関連するユーザー名。
user_agent	イベントに関連するユーザーエージェント。
strategy	イベントに関連する接続戦略。
strategy_type	イベントに関連する接続戦略の種類。
type	イベントの種類。

​

単独の検索語で検索できるフィールド

検索語をフィールド名なしで入力した場合、検索対象となるのは次のフィールドのみです。

• client_name
• connection
• description
• ip
• log_id
• type
• user_name

​

完全一致

完全一致で検索するには、二重引用符を使用します: description:"Username invalid"。

たとえば、description が Username invalid のログを検索するには、q=description:"Username invalid" を使用します。

​

ワイルドカード

ワイルドカード検索では、アスタリスク文字 (*) を使って、ターム内の 0 文字以上を置き換えられます (例: user_name:john*) 。これは、たとえば user_name:j* のような前方一致に使用できます。ワイルドカードのその他の用途 (たとえば後方一致) では、リテラルは 3 文字以上である必要があります。たとえば、name:*usa は許可されますが、name:*sa は許可されません。

疑問符文字 (?) はサポートされていません。

たとえば、ユーザー名が john で始まるユーザーのすべてのログを検索するには、q=user_name:john* を使用します。

​

範囲

ログ検索クエリでは、範囲指定を使用できます。範囲の両端を含める場合は角括弧 [min TO max] を、含めない場合は波括弧 {min TO max} を使用します。

同じ範囲式内で、角括弧と波括弧を組み合わせることもできます。範囲内でワイルドカードを使用することも可能です。

たとえば、2018年12月18日から現在までのすべてのログを検索するには、q=date:[2018-12-18 TO *] を使用します。

保持期間の開始時点から2018年12月19日まで (ただし、2018年12月19日は含まない) のログを検索するには、q=date:[* TO 2018-12-19} を使用します。

​

クエリの例

以下に、Management API で実行できるクエリの例をいくつか示します。

ユースケース	クエリ
”Pass” を含む接続があるすべてのログを検索	connection:*pass*
ユーザー名に “fred” を含むユーザーのすべてのログを検索	user_name:*fred*
ユーザー ID が “123” と完全に一致するすべてのログを検索	user_id:"123"
type が “s” で始まるすべてのログを検索	type:s*
”jane” で始まり “smith” で終わるユーザー名を検索	user_name:jane*smith
2018 年 12 月のすべてのログを検索	date:[2018-12 TO 2019-01-01}
2018 年 12 月 10 日以降のすべてのログを検索	date:[2018-12-10 TO *]
2019 年 1 月 1 日午前 1 時から、2019 年 1 月 1 日 12:23:45 まで (この時刻は含まない) のすべてのログを検索	date:[2019-01-01T01:00:00 TO 2019-01-01T12:23:45}

​

制限事項

• 414 Request-URI Too Large エラーが表示される場合は、クエリ文字列がサポートされている長さを超えていることを意味します。この場合は、検索条件を絞り込んでください。
• ログフィールドはトークン化されないため、description:rule は値が Create a rule や Update a rule である description には一致しません。代わりに、description:*rule を使用してください。ワイルドカードと完全一致を参照してください。
• .raw フィールド拡張子はサポートされていません。フィールドは、指定された値全体に対して一致し、トークン化はされません。

​

ページネーション

include_totals パラメーターを使用して GET /api/v2/logs または GET /api/v2/users/{user_id}/logs エンドポイントを呼び出すと、結果の概要と指定したログを含む JSON オブジェクトが返されます。JSON オブジェクトは次のようになります。

{
  "length": 5,
  "limit": 5,
  "logs": [...],
  "start": 0,
  "total": 5
}

ログを検索する際、totals フィールドには、そのページで返されたログの件数が表示されます (length フィールドと同様です) 。

​

詳細はこちら

• ログを表示する
• ログの種類コード
• ログイベントを絞り込む
• Tenant Log Search v3 へ移行する