コンテンツにスキップ

全行インデックス


全行インデックスとは

全行インデックスは、ログの全文検索方式の一つです。有効にすると、システムはログ内のすべてのビジネスフィールドを全文インデックスに含めます。クエリ時にフィールド名を事前に指定する必要はなく、任意のビジネスフィールドの値を入力するだけで、その値を含むログを検索できます。

例えば、あるログに以下のフィールドが含まれる場合:

{
  "service": "order-api",
  "trace_id": "8d4f2a",
  "order_id": "O-1001",
  "amount": 128.5
}

全行インデックスを有効にすると、8d4f2a、O-1001、128.5 のいずれを直接検索しても、このログを検索できます。

全行インデックスは以下のようなケースに適しています:

  • ログが複数の構造化フィールドとして抽出されており、もはや一連の message に依存しない。
  • trace_id、注文番号、ユーザー ID など、さまざまなビジネスフィールドから素早く検索する必要がある。
  • 同じログインデックスに複数のログ構造が含まれ、すべてのログに対して統一された検索フィールドを事前に決定できない。
  • フィールドによるクエリ機能を維持しつつ、ビジネスフィールドを横断した全文検索をサポートしたい。

message のみのインデックスとの違い

比較項目 message のみのインデックス 全行インデックス
全文検索範囲 message フィールドのみ 存在する message を含むすべてのビジネスフィールド
元ログを保持する必要があるか message を保持する必要がある 必須ではない。保持しても、フィールド抽出後に削除してもよい
適したデータ プレーンテキストログ、非構造化ログ JSON ログ、Pipeline で抽出した構造化ログ
全文インデックスフィールド message variant

全行インデックスは全文検索の範囲を変えるだけで、フィールドによる絞り込みを代替しません。抽出済みのフィールドについては、引き続き service:order-api などのフィールド条件を使用して、正確な絞り込み、集計、分析を行うことができます。

動作メカニズム

システムは variant を使用して全行インデックスのビジネスフィールドを統一的に格納し、variant に対してのみ全文インデックスを作成します。

message が存在しない場合:
ビジネスフィールド → variant → 全文インデックス

message が存在する場合:
message + その他のビジネスフィールド → variant → 全文インデックス

具体的なルールは以下のとおりです:

  • 全行インデックスにはログのビジネスフィールドが含まれ、システムフィールドは含まれません。
  • ログに message が存在しない場合でも、その他のビジネスフィールドは全文検索に参加できます。
  • ログに message が存在する場合、システムはこのフィールドを削除せず、通常のビジネスフィールドとして variant に書き込みます。
  • システムが message と variant の両方に対して全文インデックスを二重に作成することはありません。
  • 同じログインデックスに、message を含むログと含まないログを同時に保存できます。

message の有無は、ログの元の内容と、DataKit、Pipeline の実際の処理結果によって決まります。全行インデックスを有効にしても、message を削除する必要はありません。

全行インデックスの使用または切り替え

新しいログインデックスを作成する場合、システムはデフォルトで全行インデックスを使用するため、追加の設定は不要です。

元のインデックスで message フィールド内の JSON Path にクエリ高速化を設定している場合は、切り替え前に該当する設定を記録し、切り替え後に対応する JSON Path クエリ高速化を再設定してください。具体的な方法は JSON Path 埋め込みフィールドのクエリ高速化 を参照してください。

引き続き message のみのインデックスフィールドを使用している既存のログインデックスは、以下の操作を実行できます:

  1. ログ > インデックス に移動します。
  2. 対象のログインデックスを編集します。
  3. 詳細設定 を展開します。
  4. 全文インデックスフィールド で 全行インデックス を選択します。
  5. 影響範囲を確認し、設定を保存します。
注意

message のみのインデックスから全行インデックスへの切り替えは一方向の操作です。保存後は message のみのインデックスに戻すことはできません。操作前に、関連するクエリとデータの利用方法をご確認ください。

前提条件

現在のワークスペースが全行インデックスをサポートしている必要があります。ページにこのオプションが表示されない場合は、ワークスペースのバージョンと関連する機能の権限をご確認ください。

全行インデックスを使用したクエリ

設定を完了してログを書き込んだ後、ログ > エクスプローラー に移動し、対応するログインデックスを選択します。

エクスプローラーは、テキスト検索、フィールド絞り込み、組み合わせ検索、JSON 検索、DQL クエリなどの方法をサポートしています。検索構文と使用方法の詳細は、エクスプローラー検索 を参照してください。

全文検索

検索ボックスにビジネスフィールドの値を入力すると、フィールド名を指定せずにすべてのビジネスフィールドを検索できます。

前述の注文ログを例にすると:

  • O-1001 を入力すると、order_id に一致します。
  • 8d4f2a を入力すると、trace_id に一致します。
  • order-api を入力すると、service に一致します。
  • ログに message が保持されている場合、message 内のコンテンツも検索できます。

テキスト検索では、入力内容がトークン化されます。完全で連続した内容を一致させる必要がある場合は、検索内容を半角の二重引用符で囲みます。詳細はテキスト検索 を参照してください。

フィールド絞り込み

フィールド名がわかっている場合は、引き続きフィールド条件を使用してクエリ範囲を絞り込めます。例えば:

service:order-api

全文検索は「内容がどのフィールドにあるか不明」なケースに適しており、フィールド絞り込みはフィールド名がわかっていて、正確なフィルタリングや集計分析が必要なケースに適しています。両方を組み合わせて使用することもできます。フィールド絞り込みの完全な構文は絞り込み を参照してください。

クエリに関する注意事項

  • 全行インデックスの全文検索はビジネスフィールドのみに一致し、システムフィールドには一致しません。
  • ログに message がない場合、エクスプローラーは現在のログのビジネスフィールドを組み合わせてログ内容を表示します。
  • システムフィールドは全行インデックスのログ内容の一部にはなりません。
  • ビジネスフィールドが元のログからまだ抽出されていない場合、全行インデックスは現在実際に存在するフィールドのみを検索できます。そのため、JSON やプレーンテキストのログでは、後述の方法で必要なフィールドを先に抽出してください。

ログフィールドの抽出

全行インデックスはログにすでに存在するビジネスフィールドをインデックス化しますが、message 内のコンテンツを自動的に解釈して分割することはありません。元のログが JSON やプレーンテキストのままの場合は、DataKit や Pipeline を使用してコンテンツを構造化フィールドに抽出できます。

フィールド抽出後、元の message を保持するかどうかは実際の要件によって決まります:

  • 完全な原文を確認する必要がある場合や、既存の利用習慣と互換性を保つ場合は、message を保持できます。
  • 十分な構造化フィールドがあり、原文を保存する必要がなくなった場合は、message を削除できます。
  • message を保持するかどうかに関係なく、抽出済みのビジネスフィールドは全行インデックスの全文検索に参加できます。

DataKit を使用した JSON フィールドの抽出

各行が標準的な JSON オブジェクトであり、すべてのトップレベルフィールドを直接抽出したいログに適しています。DataKit 2.9.0 以降では json_as_fields を有効にできます。

有効にすると、DataKit は文字デコード、ANSI クリーンアップ、複数行の結合の後、JSON ルートオブジェクトのトップレベルプロパティをログフィールドに変換してから、Pipeline を実行します。

ホストログ収集

logging.conf を編集します:

[[inputs.logging]]
  logfiles = ["/var/log/order/*.json"]
  source = "order"
  service = "order-api"
  json_as_fields = true

設定を保存したら、DataKit を再起動します。

Kubernetes コンテナログ収集

Pod Annotation を使用して、指定したコンテナの JSON フィールドモードを有効にできます:

metadata:
  annotations:
    datakit/order-api.logs: >-
      [{"source":"order","service":"order-api","json_as_fields":true}]

ここで、order-api はコンテナ名です。コンテナの環境変数 DATAKIT_LOGS_CONFIG でも同じ JSON 設定を使用できます。

コンテナ設定の制限

json_as_fields は現在、コンテナの環境変数と Pod Annotation/Label の JSON ログ設定のみをサポートしており、ClusterLoggingConfig CRD はまだサポートされていません。

Log Streaming

logstreaming.conf で有効にします:

[inputs.logstreaming]
  json_as_fields = true

json_as_fields はコレクター設定であり、HTTP URL パラメータではありません。この設定は influxdb、firelens、firehose タイプには適用されません。

抽出結果

元のログ:

{"timestamp":"2026-08-18T10:00:00+08:00","level":"INFO","service":"order-api","trace_id":"8d4f2a","order_id":"O-1001","amount":128.5,"labels":{"channel":"web"}}

変換が成功すると:

  • timestamp、level、service、trace_id、order_id、amount が独立したフィールドになります。
  • labels オブジェクトはコンパクトな JSON 文字列として保存されます。
  • DataKit は、元の JSON 全体を保存する message を追加で生成しません。
  • 元の JSON に message が含まれている場合、そのフィールドは通常どおり保持されます。

主なフィールド変換ルールは以下のとおりです:

  • トップレベルの文字列、ブール値、整数、小数は型を維持します。オブジェクトと配列はコンパクトな JSON 文字列として保存され、null は無視されます。
  • 不正な JSON、ルートノードがオブジェクトでない場合、有効なフィールドがない場合は、元の message にフォールバックします。
  • フィールド名の . は _ に変換され、改行文字はスペースに変換されます。フィールド名の最大長は 256 バイトです。
  • 各ログにつき最大 1024 個のフィールドが保持され、タグは含まれません。
  • JSON フィールドは、コレクター内の同名のタグまたはフィールドを上書きします。
  • JSON の time、source、date、storage_index は、それぞれ json_time、json_source、json_date、json_storage_index にリネームされます。

完全なルールは JSON フィールドモード を参照してください。

Pipeline を使用したフィールド抽出

以下のようなケースに適しています:

  • 一部のフィールドだけを抽出したい。
  • フィールドのリネームや変換が必要。
  • ログが標準的な JSON ではない。
  • 既存の Pipeline 処理フローを引き続き利用したい。

すべてのトップレベルスカラーフィールドの抽出

DataKit 2.2.0 以降では json_all() を使用できます:

# 元のデータ:
# {"service":"order-api","status":"info","trace_id":"8d4f2a","order_id":"O-1001","amount":128.5}

json_all(_, key_patterns=["*"])

処理後、service、status、trace_id、order_id、amount などの独立したフィールドが得られます。

json_all() はトップレベルの文字列、数値、ブール値のみを抽出し、オブジェクトや配列を再帰的に展開せず、null も保存しません。include_keys と key_patterns の両方が設定されていない場合、フィールドは抽出されません。すべてのトップレベルスカラーフィールドを抽出する必要がある場合は、明示的に key_patterns=["*"] を設定する必要があります。

指定したフィールドのみの抽出

json(_, service)
json(_, level, status)
json(_, trace_id)
json(_, order_id)
json(_, amount)

この方法により、全行インデックスに含めるフィールドの範囲を制御したり、異なるログ間でフィールド名を統一したりできます。

オブジェクトや配列は json_all() では抽出されません。このような内容を保持する必要がある場合は、json() でフィールドを指定して抽出できます。抽出結果は JSON 文字列として保存されます。

フィールド抽出後に message を削除

Pipeline でフィールドを抽出する場合、元のログはデフォルトで引き続き message に保存されます。構造化フィールドですでに表示やクエリの要件を満たせる場合は、フィールド抽出後に drop_origin_data() を呼び出して、元の内容を保存しないようにできます。

json_all(_, key_patterns=["*"])
drop_origin_data()

指定したフィールドを抽出した後にも削除できます:

json(_, service)
json(_, level, status)
json(_, trace_id)
json(_, order_id)
json(_, amount)
drop_origin_data()

JSON 自体に message が含まれ、そのフィールドも抽出される場合、必要に応じて保持または削除できます。明確に不要な場合は、以下のようにします:

json_all(_, key_patterns=["*"])
drop_origin_data()
drop_key(message)

3 つの関数の役割は異なります:

  • drop_origin_data():初期化時に保存された元のテキストを出力しません。ログ全体は引き続きアップロードされます。
  • drop_key(message):抽出済みの message フィールドを削除します。
  • drop():ログ全体を破棄します。ログはアップロードされず、message の削除には使用できません。
drop() を使用して message を削除しないでください

drop() は現在のログを破棄対象としてマークします。Pipeline の実行後、ログ全体がアップロードされません。

その他の構文は、json()、json_all()、drop_origin_data()、drop_key() を参照してください。

Pipeline のローカル検証

Pipeline スクリプトを保存した後、DataKit が稼働しているホストで以下を実行できます:

datakit pipeline -P full_line_json.p \
  -T '{"service":"order-api","status":"info","trace_id":"8d4f2a","order_id":"O-1001","amount":128.5}'

出力が以下の期待どおりであることを確認します:

  • 検索が必要なフィールドがすべて抽出されている。
  • drop_origin_data() を設定した場合、元の message が削除されている。
  • ログが drop: true としてマークされていない。
  • status やログ時間などのフィールドが業務上の期待どおりである。

よくある質問

全行インデックスでは message を削除する必要がありますか?

いいえ、必要ありません。message が存在する場合、システムはこれを通常のビジネスフィールドとして variant に書き込み、message 用に別途全文インデックスを作成することはありません。message を削除するかどうかは、元のコンテンツの保持と表示の要件に基づいて決定してください。

全行インデックスを有効にしても、message 内の JSON フィールドが検索できないのはなぜですか?

JSON 全体が引き続き message の文字列コンテンツとしてのみ存在する場合、その中のプロパティは独立したビジネスフィールドではありません。message 内のテキストを検索することはできますが、これらのプロパティをフィールド絞り込みや集計に直接使用することはできません。DataKit や Pipeline を使用して、必要なフィールドを先に抽出することをお勧めします。

message がない場合、ログエクスプローラーはどのように内容を表示しますか?

ログに message が存在しない場合、ログエクスプローラーは現在のログのビジネスフィールドを組み合わせてログ内容を表示します。システムフィールドはログ内容の一部にはなりません。

同じインデックスに message を含むログと含まないログを同時に存在させることはできますか?

できます。どちらのタイプのログも、統一されたルールに従ってビジネスフィールドが variant に書き込まれ、variant が全文インデックスに参加します。

全行インデックスでシステムフィールドを検索できますか?

できません。全行インデックスはビジネスフィールドのみを含み、システムフィールドは含みません。システムフィールドは、フィールド絞り込みなどの方法で引き続きクエリできます。

全行インデックスに切り替えた後、message インデックスに戻せますか?

できません。message のみのインデックスから全行インデックスへの切り替えは一方向の操作であり、保存後は元に戻せません。既存の message インデックスは、切り替えを実行しない限り、引き続き従来の方法で使用できます。

フィードバック

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