Cassandra ドキュメント

バージョン

プレリリース版のドキュメントを表示しています。

完全クエリロギング

Apache Cassandra 4.0 では、ライブクエリロギングをサポートする新しい高性能機能が追加されました(CASSANDRA-13983)。 FQL は、本番環境での使用に安全であり、ヒープメモリとディスク容量に設定可能な制限があり、メモリ不足エラーを防ぎます。この機能は、ライブトラフィックのキャプチャとトラフィックの再生に役立ちます。提供されているツールは、クエリトラフィックのデバッグと移行の両方に使用できます。 FQL を有効化、無効化、またはリセットするための新しい nodetool オプションと、バイナリログを読み取って再生するための新しいツールも追加されました。完全クエリロギング (FQL) 機能は、Chronicle-Queue を使用してクエリのログをローテーションします。完全クエリログは、このページの残りの部分では**ログ**と呼ばれます。

FQL の機能の一部を以下に示します。

  • ディスクへの非同期シングルスレッドログエントリ書き込みにより、クエリレイテンシへの影響が軽減されます。

  • ヒープメモリ使用量は、重み付きキューによって制限され、設定可能な最大重みがロギングスレッドの前に配置されます。

  • 重み付きキューがいっぱいの場合、プロデューサーをブロックするか、サンプルをドロップすることができます。

  • ディスク使用量は設定可能なサイズによって制限され、制限に達すると古いログセグメントが削除されます。

  • 認識されないフィールドをスキップし、新しいフィールドを追加し、古いフィールドを省略できる、ディスク上でのシリアル化のための柔軟なスキーマバイナリ形式、Chronicle-Wire

  • JMX ツール nodetool を使用して、有効化、無効化、またはリセット(ディスク上のデータを削除するため)できます。

  • cassandra.yaml ファイルまたは nodetool を使用して設定を設定できます。

  • 現在、バイナリログを読み取り可能な形式にダンプできる新しい fqltool が導入されています。その他のオプションは、再生比較です。

FQL は、データを変更するイベントとクエリするイベントの両方、成功したすべての Cassandra クエリ言語 (CQL) 要求をログに記録します。監査ログにも CQL 要求が含まれていますが、FQL は CQL 要求のみをログに記録します。この違いにより、FQL はログの再生または比較に使用できますが、監査ロギングは使用できません。 FQL は、デバッグ、パフォーマンスベンチマーク、テスト、CQL クエリの監査に役立ちますが、監査ログはコンプライアンスに役立ちます。

パフォーマンステストでは、FQL は `WRITE`のみのワークロードではオーバーヘッドがほとんどまたはまったくないように見え、`MIXED`ワークロードではわずかなオーバーヘッドがあります。

ログに記録されたクエリ情報

クエリログには以下が含まれています。

  • 呼び出されたすべてのクエリ

  • 呼び出されたおおよその時間

  • ワイルドカード値をバインドするために必要なパラメータ

  • すべてのクエリオプション

ロガーは、完了後に単一またはバッチの CQL クエリを書き込むため、正常に完了したクエリのみがログに記録されます。失敗したクエリまたはタイムアウトしたクエリはログに記録されません。クエリのタイプに応じて、異なるデータがログに記録されます。

単一の CQL クエリログエントリには以下が含まれています。

  • query - CQL クエリテキスト

  • queryOptions - クエリ呼び出しに関連付けられたオプション

  • queryState - クエリ呼び出しに関連付けられたタイムスタンプ状態

  • queryTimeMillis - クエリが呼び出されてからのエポックからの経過時間(ミリ秒)のおおよその値

バッチ CQL クエリログエントリには以下が含まれています。

  • queries - クエリの CQL テキスト

  • queryOptions - クエリ呼び出しに関連付けられたオプション

  • queryState - クエリ呼び出しに関連付けられたタイムスタンプ状態

  • batchTimeMillis - バッチが呼び出されてからのエポックからの経過時間(ミリ秒)のおおよその値

  • type - バッチのタイプ

  • values - クエリのパラメータとしてバインドする値

FQL は `Binlog` によってサポートされているため、パフォーマンスとフットプリントは予測可能であり、ログレコードプロデューサーへの影響は最小限です。パフォーマンスの安全性により、プロデューサーがログをオーバーロードすることを防ぎ、ロギングが遅れた場合にレコードをドロップするための重み付きキューを使用します。シングルスレッドの非同期書き込みによってログが生成されます。 Chronicle-Queue は、ログをロールする簡単な方法を提供します。

ログに記録されたロギング情報

FQL は、保存されたログファイルに関する情報も追跡します。

  • 追加された保存済みログファイルとそのストレージへの影響。ストレージ制限を超えた場合は削除します。

  • すでにロールされている Chronicle-Queue 内のログファイル

  • すでにロールされているログファイルのバイト数

ロギングシーケンス

ロガーは、明確に定義された一連のイベントに従います。

  1. ログレコードを書き込むコンシューマースレッドが開始されます。このアクションは一度だけ実行できます。

  2. コンシューマースレッドは、ログにレコードを提供します。メモリ内キューがいっぱいの場合、レコードはドロップされ、オファーは `false` 値を返します。

  3. 受け入れられると、レコードはログに入力されます。メモリ内キューがいっぱいの場合、書き込みスレッドはスペースができるか、中断されるまでブロックされます。

  4. バッファはスレッドの終了時にクリーンアップされます。ファイナライズでは、キューにストラグラーがないことを確認するために、再度チェックが行われます。

  5. コンシューマースレッドが停止します。複数回呼び出すことができます。

FQL の使用

FQL を使用するには、2つのアクションを実行する必要があります。 `cassandra.yaml` ファイルまたは `nodetool` を使用して FQL を設定し、`nodetool enablefullquerylog` を使用してロギングを有効にする必要があります。どちらの方法でも、少なくともログディレクトリへのパスを指定する必要があります。両方のアクションはノードごとに完了します。完全クエリログは、有効になっている各ノードで生成されるため、各ノードのログにはそのノードのクエリが含まれます。

cassandra.yaml での FQL の設定

`cassandra.yaml` ファイルを使用して、`nodetool` で機能を有効にする前に FQL を設定できます。

ファイルには、使用のためにコメントを外すことができる次のオプションが含まれています。

# default options for full query logging - these can be overridden from command line
# when executing nodetool enablefullquerylog
#full_query_logging_options:
   # log_dir:
   # roll_cycle: HOURLY
   # block: true
   # max_queue_weight: 268435456 # 256 MiB
   # max_log_size: 17179869184 # 16 GiB
   # archive command is "/path/to/script.sh %path" where %path is replaced with the file being rolled:
   # archive_command:
   # max_archive_retries: 10

log_dir

ログを書き込むには、既存のディレクトリを `log_dir` に設定する必要があります。

ディレクトリには、読み取り、書き込み、および実行を許可する適切な権限が設定されている必要があります。ロギングは、必要に応じてディレクトリの内容を再帰的に削除します。このディレクトリにファイルシステムの他のセクションへのリンクを配置しないでください。たとえば、`log_dir: /tmp/cassandrafullquerylog` です。

roll_cycle

`roll_cycle` は、ログセグメントがロールされる頻度を定義します。サポートされている値は、`HOURLY`(デフォルト)、`MINUTELY`、および `DAILY` です。たとえば、`roll_cycle: DAILY` です。

block

`block` オプションは、FQL が遅れた場合に FQL が書き込みをブロックするか、ログレコードをドロップするかを指定します。サポートされているブール値は、`true`(デフォルト)または `false` です。たとえば、レコードをドロップするには `block: false` とします。

max_queue_weight

`max_queue_weight` オプションは、ブロッキングまたはドロップする前にファイルへの書き込みを待機しているレコードのメモリ内キューの最大重みを設定します。オプションは正の値に設定する必要があります。デフォルト値は 268435456、つまり 256 MiB です。たとえば、デフォルトを変更するには、`max_queue_weight: 134217728 # 128 MiB` とします。

max_log_size

`max_log_size` オプションは、最も古いファイルを削除する前にディスクに保持するロールされたファイルの最大サイズを設定します。オプションは正の値に設定する必要があります。デフォルトは 17179869184、つまり 16 GiB です。たとえば、デフォルトを変更するには、`max_log_size: 34359738368 # 32 GiB` とします。

archive_command

archive_commandオプションは、ロールされたログファイルに対して実行されるユーザー定義のアーカイブスクリプトを設定します。定義されていない場合、ファイルは削除され、デフォルトの""org.apache.cassandra.utils.binlog.DeletingArchiverにマップされます。例:archive_command: /usr/local/bin/archiveit.sh %path # %path はロールされているファイルです

max_archive_retries

max_archive_retriesオプションは、失敗したアーカイブコマンドの最大再試行回数を設定します。デフォルトは10です。例:max_archive_retries: 10

FQLは、次のセクションで説明するように、機能を有効にする際にnodetoolを使用して設定することもでき、cassandra.yamlファイルで設定された値をオーバーライドします。

FQLの有効化

FQLは、nodetool enablefullquerylogコマンドを使用してノードごとに有効になります。log_dircassandra.yamlファイルに設定されていない場合、少なくともロギングディレクトリへのパスを定義する必要があります。

nodetool enablefullquerylogコマンドの構文には、cassandra.yamlファイルで設定できるのと同じオプションがすべてあります。さらに、nodetoolには、コマンドを実行するホストとポート、およびコマンドで認証が必要な場合はユーザー名とパスワードを設定するオプションがあります。

  nodetool [(-h <host> | --host <host>)] [(-p <port> | --port <port>)]
 [(-pp | --print-port)] [(-pw <password> | --password <password>)]
 [(-pwf <passwordFilePath> | --password-file <passwordFilePath>)]
 [(-u <username> | --username <username>)] enablefullquerylog
 [--archive-command <archive_command>] [--blocking]
 [--max-archive-retries <archive_retries>]
 [--max-log-size <max_log_size>] [--max-queue-weight <max_queue_weight>]
 [--path <path>] [--roll-cycle <roll_cycle>]

 OPTIONS
   --archive-command <archive_command>
  Command that will handle archiving rolled full query log files.
  Format is "/path/to/script.sh %path" where %path will be replaced
  with the file to archive

   --blocking
  If the queue is full whether to block producers or drop samples.

   -h <host>, --host <host>
  Node hostname or ip address

   --max-archive-retries <archive_retries>
  Max number of archive retries.

   --max-log-size <max_log_size>
  How many bytes of log data to store before dropping segments. Might
  not be respected if a log file hasn't rolled so it can be deleted.

   --max-queue-weight <max_queue_weight>
  Maximum number of bytes of query data to queue to disk before
  blocking or dropping samples.

   -p <port>, --port <port>
  Remote jmx agent port number

   --path <path>
  Path to store the full query log at. Will have it's contents
  recursively deleted.

   -pp, --print-port
  Operate in 4.0 mode with hosts disambiguated by port number

   -pw <password>, --password <password>
  Remote jmx agent password

   -pwf <passwordFilePath>, --password-file <passwordFilePath>
  Path to the JMX password file

   --roll-cycle <roll_cycle>
  How often to roll the log file (MINUTELY, HOURLY, DAILY).

   -u <username>, --username <username>
  Remote jmx agent username

FQLを有効にするには、ロギングを有効にするクラスター内の各ノードで次のコマンドを実行します。

$ nodetool enablefullquerylog --path /tmp/cassandrafullquerylog

FQLの無効化またはリセット

ロギングを無効にするには、nodetool disablefullquerylogを使用します。FQLを停止し、設定されたディレクトリ内のログファイルをクリアするには、nodetool resetfullquerylogを使用します。**重要:** nodetool resetfullquerylogを使用すると、ログファイルが削除されます! すべてのログファイルを削除する必要がある場合を除き、このコマンドを使用しないでください。

fqltool

fqltoolコマンドは、ログの表示(ダンプ)、再生、または比較に使用されます。fqltool dumpは、バイナリログファイルを人間が読める形式に変換します。コマンドラインオプションとしてログディレクトリのみを指定する必要があります。

fqltool replayCASSANDRA-14618)はログの再生を有効にします。このコマンドは、テスト、デバッグ、またはパフォーマンスベンチマークのために、異なるマシンまたはクラスターから実行できます。このコマンドは、削除されたデータベースオブジェクトを再作成するためにも使用できます。fqltool replayを使用して、Cassandraの異なるバージョン/構成または異なるクラスターに対して、本番トラフィックの異なる実行を記録および比較します。別の用途は、複数のマシンからログを収集し、記録されたタイムスタンプによって「順序どおり」に再生することです。

fqltool replayの構文は次のとおりです。

  fqltool replay [--keyspace <keyspace>] [--results <results>]
 [--store-queries <store_queries>] --target <target>... [--] <path1>
 [<path2>...<pathN>]

 OPTIONS
   --keyspace <keyspace>
  Only replay queries against this keyspace and queries without
  keyspace set.

   --results <results>
  Where to store the results of the queries, this should be a
  directory. Leave this option out to avoid storing results.

   --store-queries <store_queries>
  Path to store the queries executed. Stores queries in the same order
  as the result sets are in the result files. Requires --results

   --target <target>
  Hosts to replay the logs to, can be repeated to replay to more
  hosts.

   --
  This option can be used to separate command-line options from the
  list of argument, (useful when arguments might be mistaken for
  command-line options

   <path1> [<path2>...<pathN>]
  Paths containing the FQ logs to replay.

fqltool compareCASSANDRA-14619)は、fqltool replayによって生成された結果ファイルを比較します。このコマンドは、fqltool replayからの記録された実行を使用し、ログを比較して、違い(潜在的にすべてのクエリ)を出力します。また、比較時にメモリ内から結果全体を読み取らないように、各行を個別のクロニクルドキュメントとして保存します。

fqltool compareの構文は次のとおりです。

   fqltool compare --queries <queries> [--] <path1> [<path2>...<pathN>]

 OPTIONS
   --queries <queries>
  Directory to read the queries from. It is produced by the fqltool
  replay --store-queries option.

   --
  This option can be used to separate command-line options from the
  list of argument, (useful when arguments might be mistaken for
  command-line options

   <path1> [<path2>...<pathN>]
  Directories containing result files to compare.

比較は、以下のマークを設定します。

  • クエリセットの先頭をマークします。

  version: int16
  type: column_definitions
  column_count: int32;
  column_definition: text, text
  column_definition: text, text
  ....
  • 失敗したクエリセットをマークします。

  version: int16
  type: query_failed
  message: text
  • 行セットをマークします。

  version: int16
  type: row
  row_column_count: int32
  column: bytes
  • 結果セットの終わりをマークします。

  version: int16
  type: end_resultset

  1. FQLを示すために、最初にクラスター内のノードでFQLを構成して有効にします。

$ nodetool enablefullquerylog --path /tmp/cassandrafullquerylog
  1. 次に、cqlshを使用してデモキースペースとテーブルを作成し、いくつかのデータを挿入します。

 cqlsh> CREATE KEYSPACE querylogkeyspace
   ... WITH replication = {'class': 'SimpleStrategy', 'replication_factor' : 1};
 cqlsh> USE querylogkeyspace;
 cqlsh:querylogkeyspace> CREATE TABLE t (
 ...id int,
 ...k int,
 ...v text,
 ...PRIMARY KEY (id)
 ... );
 cqlsh:querylogkeyspace> INSERT INTO t (id, k, v) VALUES (0, 0, 'val0');
 cqlsh:querylogkeyspace> INSERT INTO t (id, k, v) VALUES (0, 1, 'val1');
  1. 次に、データが挿入されていることを確認します。

 cqlsh:querylogkeyspace> SELECT * FROM t;

 id | k | v
 ----+---+------
  0 | 1 | val1

 (1 rows)
  1. ログを表示するには、fqltool dumpコマンドを使用します。

$ fqltool dump /tmp/cassandrafullquerylog

このコマンドは、ログの読み取り可能なバージョンを返します。このデモのコマンドのログの部分的なサンプルを次に示します。

WARN  [main] 2019-08-02 03:07:53,635 Slf4jExceptionHandler.java:42 - Using Pauser.sleepy() as not enough processors, have 2, needs 8+
      Type: single-query
      Query start time: 1564708322030
      Protocol version: 4
      Generated timestamp:-9223372036854775808
      Generated nowInSeconds:1564708322
      Query: SELECT * FROM system.peers
      Values:

      Type: single-query
      Query start time: 1564708322054
      Protocol version: 4
      Generated timestamp:-9223372036854775808
      Generated nowInSeconds:1564708322
      Query: SELECT * FROM system.local WHERE key='local'
      Values:

      Type: single-query
      Query start time: 1564708322109
      Protocol version: 4
      Generated timestamp:-9223372036854775808
      Generated nowInSeconds:1564708322
      Query: SELECT * FROM system_schema.keyspaces
      Values:

      Type: single-query
      Query start time: 1564708322116
      Protocol version: 4
      Generated timestamp:-9223372036854775808
      Generated nowInSeconds:1564708322
      Query: SELECT * FROM system_schema.tables
      Values:

      Type: single-query
      Query start time: 1564708322139
      Protocol version: 4
      Generated timestamp:-9223372036854775808
      Generated nowInSeconds:1564708322
      Query: SELECT * FROM system_schema.columns
      Values:

      Type: single-query
      Query start time: 1564708322142
      Protocol version: 4
      Generated timestamp:-9223372036854775808
      Generated nowInSeconds:1564708322
      Query: SELECT * FROM system_schema.functions
      Values:

      Type: single-query
      Query start time: 1564708322141
      Protocol version: 4
      Generated timestamp:-9223372036854775808
      Generated nowInSeconds:1564708322
      Query: SELECT * FROM system_schema.aggregates
      Values:

      Type: single-query
      Query start time: 1564708322143
      Protocol version: 4
      Generated timestamp:-9223372036854775808
      Generated nowInSeconds:1564708322
      Query: SELECT * FROM system_schema.types
      Values:

      Type: single-query
      Query start time: 1564708322144
      Protocol version: 4
      Generated timestamp:-9223372036854775808
      Generated nowInSeconds:1564708322
      Query: SELECT * FROM system_schema.indexes
      Values:

      Type: single-query
      Query start time: 1564708322145
      Protocol version: 4
      Generated timestamp:-9223372036854775808
      Generated nowInSeconds:1564708322
      Query: SELECT * FROM system_schema.views
      Values:

      Type: single-query
      Query start time: 1564708345408
      Protocol version: 4
      Generated timestamp:-9223372036854775808
      Generated nowInSeconds:-2147483648
      Query: CREATE KEYSPACE querylogkeyspace
      WITH replication = {'class': 'SimpleStrategy', 'replication_factor' : 1};
      Values:

      Type: single-query
      Query start time: 1564708360873
      Protocol version: 4
      Generated timestamp:-9223372036854775808
      Generated nowInSeconds:-2147483648
      Query: USE querylogkeyspace;
      Values:

      Type: single-query
      Query start time: 1564708360874
      Protocol version: 4
      Generated timestamp:-9223372036854775808
      Generated nowInSeconds:-2147483648
      Query: USE "querylogkeyspace"
      Values:

      Type: single-query
      Query start time: 1564708378837
      Protocol version: 4
      Generated timestamp:-9223372036854775808
      Generated nowInSeconds:-2147483648
      Query: CREATE TABLE t (
          id int,
          k int,
          v text,
          PRIMARY KEY (id)
      );
      Values:

      Type: single-query
      Query start time: 1564708379247
      Protocol version: 4
      Generated timestamp:-9223372036854775808
      Generated nowInSeconds:1564708379
      Query: SELECT * FROM system_schema.tables WHERE keyspace_name = 'querylogkeyspace' AND table_name = 't'
      Values:

      Type: single-query
      Query start time: 1564708397144
      Protocol version: 4
      Generated timestamp:-9223372036854775808
      Generated nowInSeconds:1564708397
      Query: INSERT INTO t (id, k, v) VALUES (0, 0, 'val0');
      Values:

      Type: single-query
      Query start time: 1564708434782
      Protocol version: 4
      Generated timestamp:-9223372036854775808
      Generated nowInSeconds:1564708434
      Query: SELECT * FROM t;
      Values:
  1. fqltool replayを示すために、最初にキースペースを削除します。

cqlsh:querylogkeyspace> DROP KEYSPACE querylogkeyspace;
  1. 次に、--results--store-queriesにそれぞれ、クエリの結果を格納するディレクトリと実行されたクエリのリストを指定して、fqltool replayを実行します。

$ fqltool replay \
--keyspace querylogkeyspace --results /cassandra/fql/logs/results/replay \
--store-queries /cassandra/fql/logs/queries/replay \
-- target 3.91.56.164 \
/tmp/cassandrafullquerylog

--resultsおよび--store-queriesディレクトリはオプションですが、--store-queriesが設定されている場合は、--resultsも設定する必要があります。 --targetは、ログを再生するノードを指定します。

  1. DESCRIBE KEYSPACESコマンドを使用して、キースペースが再生され、再び存在することを確認します。

 cqlsh:querylogkeyspace> DESC KEYSPACES;

 system_schema  system  system_distributed  system_virtual_schema
 system_auth    querylogkeyspace  system_traces  system_views