完全クエリロギング
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 内のログファイル
-
すでにロールされているログファイルのバイト数
ロギングシーケンス
ロガーは、明確に定義された一連のイベントに従います。
-
ログレコードを書き込むコンシューマースレッドが開始されます。このアクションは一度だけ実行できます。
-
コンシューマースレッドは、ログにレコードを提供します。メモリ内キューがいっぱいの場合、レコードはドロップされ、オファーは `false` 値を返します。
-
受け入れられると、レコードはログに入力されます。メモリ内キューがいっぱいの場合、書き込みスレッドはスペースができるか、中断されるまでブロックされます。
-
バッファはスレッドの終了時にクリーンアップされます。ファイナライズでは、キューにストラグラーがないことを確認するために、再度チェックが行われます。
-
コンシューマースレッドが停止します。複数回呼び出すことができます。
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` とします。
FQLの有効化
FQLは、nodetool enablefullquerylog
コマンドを使用してノードごとに有効になります。log_dir
がcassandra.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 replay
(CASSANDRA-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 compare
(CASSANDRA-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
例
-
FQLを示すために、最初にクラスター内のノードでFQLを構成して有効にします。
$ nodetool enablefullquerylog --path /tmp/cassandrafullquerylog
-
次に、
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');
-
次に、データが挿入されていることを確認します。
cqlsh:querylogkeyspace> SELECT * FROM t;
id | k | v
----+---+------
0 | 1 | val1
(1 rows)
-
ログを表示するには、
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:
-
fqltool replay
を示すために、最初にキースペースを削除します。
cqlsh:querylogkeyspace> DROP KEYSPACE querylogkeyspace;
-
次に、
--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
は、ログを再生するノードを指定します。
-
DESCRIBE KEYSPACES
コマンドを使用して、キースペースが再生され、再び存在することを確認します。
cqlsh:querylogkeyspace> DESC KEYSPACES;
system_schema system system_distributed system_virtual_schema
system_auth querylogkeyspace system_traces system_views