リポジトリ分析API

リポジトリを分析し、そのパフォーマンス特性と発見された不正な動作を報告します。

Python

  1. resp = client.perform_request(
  2.    "POST",
  3.    "/_snapshot/my_repository/_analyze",
  4.    params={
  5.    "blob_count": "10",
  6.    "max_blob_size": "1mb",
  7.    "timeout": "120s"
  8.    },
  9. )
  10. print(resp)

Ruby

  1. response = client.snapshot.repository_analyze(
  2.   repository: 'my_repository',
  3.   blob_count: 10,
  4.   max_blob_size: '1mb',
  5.   timeout: '120s'
  6. )
  7. puts response

Js

  1. const response = await client.transport.request({
  2.   method: "POST",
  3.   path: "/_snapshot/my_repository/_analyze",
  4.   querystring: {
  5.    blob_count: "10",
  6.    max_blob_size: "1mb",
  7.    timeout: "120s",
  8.   },
  9. });
  10. console.log(response);

コンソール

  1. POST /_snapshot/my_repository/_analyze?blob_count=10&max_blob_size=1mb&timeout=120s

リクエスト

POST /_snapshot/<repository>/_analyze

前提条件

  • Elasticsearchのセキュリティ機能が有効になっている場合、このAPIを使用するには、manage クラスター権限を持っている必要があります。詳細については、セキュリティ権限を参照してください。

説明

利用可能なサードパーティのストレージシステムは多数ありますが、すべてがElasticsearchによるスナップショットリポジトリとして使用するのに適しているわけではありません。一部のストレージシステムは不正に動作したり、特にElasticsearchクラスターのノードが同時にアクセスする場合にパフォーマンスが悪化したりします。

リポジトリ分析APIは、リポジトリに対して一連の読み取りおよび書き込み操作を実行し、不正な動作を検出し、ストレージシステムのパフォーマンス特性を測定するように設計されています。

このAPIのパラメータのデフォルト値は、分析を誤って実行した場合の影響を軽減し、調査のための合理的な出発点を提供するために意図的に低く設定されています。最初の分析はデフォルトのパラメータ値で実行し、単純な問題を確認してください。成功した場合は、失敗に遭遇するか、blob_countが少なくとも2000、max_blob_sizeが少なくとも2gb、max_total_data_sizeが少なくとも1tb、register_operation_countが少なくとも100に達するまで、徐々に大きな分析を実行してください。各分析が完了するまでの時間を確保するために、1hまたはそれ以上の寛大なタイムアウトを常に指定してください。リポジトリに同時に多くのノードがアクセスする場合にのみ発生する問題を検出できるように、プロダクションクラスターと同様のサイズのマルチノードクラスターを使用して分析を実行してください。

分析が失敗した場合、Elasticsearchはリポジトリが予期しない動作をしたことを検出しました。これは通常、サードパーティのストレージシステムがサポートを主張するAPIの不正または非互換な実装を使用していることを意味します。その場合、このストレージシステムはスナップショットリポジトリとして使用するのに適していません。Elasticsearchが検出した非互換性に対処するために、ストレージシステムのサプライヤーと協力する必要があります。詳細については、自己管理型リポジトリタイプを参照してください。

分析が成功した場合、このAPIはテストプロセスの詳細を返し、オプションで各操作にかかった時間を含めることができます。この情報を使用して、ストレージシステムのパフォーマンスを判断できます。操作が失敗したり不正な結果を返したりした場合、このAPIはエラーを返します。APIがエラーを返す場合、リポジトリに書き込んだすべてのデータを削除できなかった可能性があります。エラーは残っているデータの場所を示し、このパスはElasticsearchのログにも記録されます。この場所が正しくクリーンアップされたことを自分で確認する必要があります。指定された場所にまだ残っているデータがある場合は、手動で削除する必要があります。

クライアントからElasticsearchへの接続が、クライアントが分析の結果を待っている間に閉じられた場合、テストはキャンセルされます。一部のクライアントは、一定のタイムアウト内に応答が受信されない場合に接続を閉じるように構成されています。分析には長い時間がかかるため、そのようなクライアント側のタイムアウトを緩和する必要があるかもしれません。キャンセル時、分析は書き込んでいたデータのクリーンアップを試みますが、すべてを削除できない場合があります。残っているデータのパスはElasticsearchのログに記録されます。この場所が正しくクリーンアップされたことを自分で確認する必要があります。指定された場所にまだ残っているデータがある場合は、手動で削除する必要があります。

分析が成功した場合、不正な動作は検出されませんでしたが、正しい動作が保証されるわけではありません。分析は一般的なバグを検出しようとしますが、100%のカバレッジを提供するわけではありません。さらに、次のことはテストしません：

  • リポジトリは耐久性のある書き込みを行う必要があります。ブロブが書き込まれた後は、削除されるまでそのまま残っている必要があります。電源喪失や類似の災害が発生した後でも。
  • リポジトリはサイレントデータの破損を受けてはなりません。ブロブが書き込まれた後、その内容は意図的に変更または削除されるまで変更されてはなりません。
  • クラスターからの接続が中断されても、リポジトリは正しく動作する必要があります。この場合、読み取りおよび書き込みが失敗する可能性がありますが、不正な結果を返してはなりません。

分析は、リポジトリにかなりの量のデータを書き込み、その後再度読み取ります。これにより、クラスターとリポジトリ間のネットワークの帯域幅、リポジトリ自体のストレージスペースおよびIO帯域幅が消費されます。この負荷がこれらのシステムの他のユーザーに影響を与えないことを確認する必要があります。分析は、利用可能な場合、リポジトリ設定max_snapshot_bytes_per_secおよびmax_restore_bytes_per_secを尊重し、消費する帯域幅を制限するために使用できるクラスター設定indices.recovery.max_bytes_per_secを尊重します。

このAPIは、人間による探索的な使用を目的としています。リクエストパラメータとレスポンス形式は、将来のバージョンで変わることが予想されます。

Elasticsearchの異なるバージョンは、リポジトリの互換性に対して異なるチェックを実行する場合があり、新しいバージョンは通常、古いバージョンよりも厳格です。あるバージョンのElasticsearchでリポジトリ分析に合格したストレージシステムは、別のバージョンでは失敗する可能性があります。これは、前のバージョンが検出しなかった方法で不正に動作していることを示しています。ストレージシステムのサプライヤーと協力して、Elasticsearchの任意のバージョンでリポジトリ分析APIによって検出された非互換性に対処する必要があります。

このAPIは、混合バージョンクラスターでは正しく動作しない可能性があります。

実装の詳細

このドキュメントのセクションでは、このバージョンのElasticsearchにおけるリポジトリ分析APIの動作について説明しますが、バージョン間で実装が異なることを期待してください。リクエストパラメータとレスポンス形式は、実装の詳細に依存するため、新しいバージョンでは異なる場合があります。

分析は、blob_countパラメータで設定された数のブロブレベルのタスクと、register_operation_countパラメータで設定された数の比較および交換操作から構成されます。これらのタスクは、クラスター内のデータおよびマスターノードに分散されて実行されます。

ほとんどのブロブレベルのタスクでは、実行ノードは最初にリポジトリにブロブを書き込み、その後、クラスター内の他のノードに対して、直前に書き込んだデータを読み取るように指示します。ブロブのサイズは、max_blob_sizeおよびmax_total_data_sizeパラメータに従ってランダムに選択されます。これらの読み取りのいずれかが失敗した場合、リポジトリはElasticsearchが要求する必要な書き込み後の読み取りセマンティクスを実装していません。

一部のブロブレベルのタスクでは、実行ノードが書き込みプロセスが完了する前にデータを読み取るようにいくつかのピアに指示します。これらの読み取りは失敗することが許可されていますが、部分的なデータを返してはなりません。いずれかの読み取りが部分的なデータを返す場合、リポジトリはElasticsearchが要求する必要な原子性セマンティクスを実装していません。

一部のブロブレベルのタスクでは、実行ノードがピアがそれを読み取っている間にブロブを上書きします。この場合、読み取られたデータは元のブロブまたは上書きされたブロブのいずれかから来る可能性がありますが、読み取り操作は部分的なデータまたは2つのブロブのデータの混合を返してはなりません。これらの読み取りのいずれかが部分的なデータまたは2つのブロブの混合を返す場合、リポジトリは上書きに対してElasticsearchが要求する必要な原子性セマンティクスを実装していません。

実行ノードは、ブロブを書き込むためにさまざまな方法を使用します。たとえば、適用可能な場合、単一パートおよびマルチパートのアップロードの両方を使用します。同様に、読み取りノードはデータを再度読み取るためにさまざまな方法を使用します。たとえば、ブロブ全体を最初から最後まで読み取るか、データのサブセットのみを読み取ることがあります。

一部のブロブレベルのタスクでは、実行ノードが書き込みが完了する前に書き込みを中止します。この場合、他のノードにブロブを読み取るように指示しますが、これらの読み取りはすべてブロブを見つけることに失敗しなければなりません。

線形化可能なレジスタは、Elasticsearchが原子比較および交換操作を使用して操作する特別なブロブです。この操作は、ブロブが複数のノードによって同時にアクセスされる場合でも、正しいかつ強く一貫した動作を保証します。線形化可能なレジスタに対する比較および交換操作の詳細な実装は、リポジトリの種類によって異なります。リポジトリ分析は、線形化可能なレジスタブロブに対する競合のない比較および交換操作が常に成功することを検証します。リポジトリ分析はまた、競合操作が成功するか、競合を報告するが不正な結果を返さないことを検証します。操作が競合のために失敗した場合、Elasticsearchは成功するまで操作を再試行します。リポジトリ分析によって実行される比較および交換操作のほとんどは、8バイトのブロブとして表されるカウンターを原子的にインクリメントします。一部の操作は、8バイト以外のサイズの小さなブロブでの動作も検証します。

パスパラメータ

  • <repository>
  • (必須、文字列) テストするスナップショットリポジトリの名前。

クエリパラメータ

  • blob_count
  • (オプション、整数) テスト中にリポジトリに書き込むブロブの総数。デフォルトは100です。現実的な実験のためには、これを少なくとも2000に設定する必要があります。
  • max_blob_size
  • (オプション、サイズ単位) テスト中に書き込まれるブロブの最大サイズ。デフォルトは10mbです。現実的な実験のためには、これを少なくとも2gbに設定する必要があります。
  • max_total_data_size
  • (オプション、サイズ単位) テスト中に書き込まれるすべてのブロブの合計サイズの上限。デフォルトは1gbです。現実的な実験のためには、これを少なくとも1tbに設定する必要があります。
  • register_operation_count
  • (オプション、整数) 総数の線形化可能なレジスタ操作を実行するための最小数。デフォルトは10です。現実的な実験のためには、これを少なくとも100に設定する必要があります。
  • timeout
  • (オプション、時間単位) テストが完了するまでの待機時間を指定します。タイムアウトが期限切れになる前に応答が受信されない場合、テストはキャンセルされ、エラーが返されます。デフォルトは30sです。

高度なクエリパラメータ

以下のパラメータは分析に対する追加の制御を可能にしますが、通常は調整する必要はありません。

  • concurrency
  • (オプション、整数) 同時に実行する書き込み操作の数。デフォルトは10です。
  • read_node_count
  • (オプション、整数) 各ブロブを書き込んだ後に読み取り操作を実行するノードの数。デフォルトは10です。
  • early_read_node_count
  • (オプション、整数) 各ブロブを書き込んでいる間に早期読み取り操作を実行するノードの数。デフォルトは2です。早期読み取り操作は非常にまれに実行されます。
  • rare_action_probability
  • (オプション、倍精度) 各ブロブに対してまれなアクション（早期読み取り、上書き、または中止された書き込み）を実行する確率。デフォルトは0.02です。
  • seed
  • (オプション、整数) テスト中に実行される操作のリストを生成するために使用される擬似乱数生成器のシード。複数の実験で同じ操作セットを繰り返すには、各実験で同じシードを使用します。操作は同時に実行されるため、各実行で常に同じ順序で発生するわけではありません。
  • detailed
  • (オプション、ブール値) 分析中に実行されたすべての操作のタイミング情報を含む詳細な結果を返すかどうか。デフォルトはfalseで、分析の概要のみを返すことを意味します。
  • rarely_abort_writes
  • (オプション、ブール値) 一部の書き込みリクエストをまれに中止するかどうか。デフォルトはtrueです。

レスポンスボディ

レスポンスは、バージョンごとに変更される可能性のある分析の実装の詳細を公開します。したがって、レスポンスボディの形式は安定しているとは見なされず、新しいバージョンでは異なる場合があります。

  • coordinating_node
  • (オブジェクト) 分析を調整し、最終的なクリーンアップを実行したノードを識別します。 
    1. -   `````id
    • (文字列) 調整ノードのID。
    • name
    • (文字列) 調整ノードの名前
  • repository
  • (文字列) 分析の対象となったリポジトリの名前。
  • blob_count
  • (整数) テスト中にリポジトリに書き込まれたブロブの数、?blob_countリクエストパラメータに等しい。
  • concurrency
  • (整数) テスト中に同時に実行された書き込み操作の数、?concurrencyリクエストパラメータに等しい。
  • read_node_count
  • (整数) 各ブロブを書き込んだ後に読み取り操作が実行されたノードの数の上限、?read_node_countリクエストパラメータに等しい。
  • early_read_node_count
  • (整数) 各ブロブを書き込んだ後に早期読み取り操作が実行されたノードの数の上限、?early_read_node_countリクエストパラメータに等しい。
  • max_blob_size
  • (文字列) テスト中に書き込まれたブロブのサイズの上限、?max_blob_sizeパラメータに等しい。
  • max_blob_size_bytes
  • (長整数) テスト中に書き込まれたブロブのサイズの上限（バイト単位）、?max_blob_sizeパラメータに等しい。
  • max_total_data_size
  • (文字列) テスト中に書き込まれたすべてのブロブの合計サイズの上限、?max_total_data_sizeパラメータに等しい。
  • max_total_data_size_bytes
  • (長整数) テスト中に書き込まれたすべてのブロブの合計サイズの上限（バイト単位）、?max_total_data_sizeパラメータに等しい。
  • seed
  • (長整数) テスト中に実行された操作の擬似乱数生成器のシード。設定されている場合、?seedリクエストパラメータに等しい。
  • rare_action_probability
  • (倍精度) テスト中にまれなアクションを実行する確率。?rare_action_probabilityリクエストパラメータに等しい。
  • blob_path
  • (文字列) テスト中にすべてのブロブが書き込まれたリポジトリ内のパス。
  • issues_detected
  • (リスト) 検出された正確性の問題のリスト。APIが成功した場合は空になります。成功したレスポンスが将来の正しい動作を保証しないことを強調するために含まれています。
  • summary
  • (オブジェクト) テストの結果を要約する統計のコレクション。 
    1. -   `````write
    • (オブジェクト) テスト中の書き込み操作の結果を要約する統計のコレクション。 
      1. -   `````count
      • (整数) テスト中に実行された書き込み操作の数。
      • total_size
      • (文字列) テスト中に書き込まれたすべてのブロブの合計サイズ。
      • total_size_bytes
      • (長整数) テスト中に書き込まれたすべてのブロブの合計サイズ（バイト単位）。
      • total_throttled
      • (文字列) max_snapshot_bytes_per_secスロットルによる待機に費やされた合計時間。
      • total_throttled_nanos
      • (長整数) max_snapshot_bytes_per_secスロットルによる待機に費やされた合計時間（ナノ秒単位）。
      • total_elapsed
      • (文字列) テスト中にブロブを書き込むのにかかった合計経過時間。
      • total_elapsed_nanos
      • (長整数) テスト中にブロブを書き込むのにかかった合計経過時間（ナノ秒単位）。
    • read
    • (オブジェクト) テスト中の読み取り操作の結果を要約する統計のコレクション。 
      1. -   `````count
      • (整数) テスト中に実行された読み取り操作の数。
      • total_size
      • (文字列) テスト中に読み取られたすべてのブロブまたは部分的なブロブの合計サイズ。
      • total_size_bytes
      • (長整数) テスト中に読み取られたすべてのブロブまたは部分的なブロブの合計サイズ（バイト単位）。
      • total_wait
      • (文字列) 各読み取りリクエストの最初のバイトを受信するまでに待機した合計時間。
      • total_wait_nanos
      • (長整数) 各読み取りリクエストの最初のバイトを受信するまでに待機した合計時間（ナノ秒単位）。
      • max_wait
      • (文字列) いずれかの読み取りリクエストの最初のバイトを受信するまでに待機した最大時間。
      • max_wait_nanos
      • (長整数) いずれかの読み取りリクエストの最初のバイトを受信するまでに待機した最大時間（ナノ秒単位）。
      • total_throttled
      • (文字列) このブロブの読み取り中にmax_restore_bytes_per_secまたはindices.recovery.max_bytes_per_secスロットルによる待機に費やされた合計時間。
      • total_throttled_nanos
      • (長整数) このブロブの読み取り中にmax_restore_bytes_per_secまたはindices.recovery.max_bytes_per_secスロットルによる待機に費やされた合計時間（ナノ秒単位）。
      • total_elapsed
      • (文字列) テスト中にブロブを読み取るのにかかった合計経過時間。
      • total_elapsed_nanos
      • (長整数) テスト中にブロブを読み取るのにかかった合計経過時間（ナノ秒単位）。
  • details
  • (配列) テスト中に実行されたすべての読み取りおよび書き込み操作の説明。これは、?detailedリクエストパラメータがtrueに設定されている場合にのみ返されます。 
    1. -   `````blob
    • (オブジェクト) 書き込まれたおよび読み取られたブロブの説明。 
      1. -   `````name
      • (文字列) ブロブの名前。
      • size
      • (文字列) ブロブのサイズ。
      • size_bytes
      • (長整数) ブロブのサイズ（バイト単位）。
      • read_start
      • (長整数) 読み取り操作が開始された位置（バイト単位）。
      • read_end
      • (長整数) 読み取り操作が完了した位置（バイト単位）。
      • read_early
      • (ブール値) 書き込み操作が完了する前に読み取り操作が開始されたかどうか。
      • overwritten
      • (ブール値) 読み取り操作が進行中の間にブロブが上書きされたかどうか。
    • writer_node
    • (オブジェクト) このブロブを書き込み、読み取り操作を調整したノードを識別します。 
      1. -   `````id
      • (文字列) 書き込みノードのID。
      • name
      • (文字列) 書き込みノードの名前
    • write_elapsed
    • (文字列) このブロブを書き込むのにかかった経過時間。
    • write_elapsed_nanos
    • (長整数) このブロブを書き込むのにかかった経過時間（ナノ秒単位）。
    • overwrite_elapsed
    • (文字列) このブロブを上書きするのにかかった経過時間。上書きされなかった場合は省略されます。
    • overwrite_elapsed_nanos
    • (長整数) このブロブを上書きするのにかかった経過時間（ナノ秒単位）。上書きされなかった場合は省略されます。
    • write_throttled
    • (文字列) このブロブを書き込む際にmax_snapshot_bytes_per_sec（または管理サービスの回復設定が設定されている場合はindices.recovery.max_bytes_per_sec）スロットルによる待機に費やされた時間。
    • write_throttled_nanos
    • (長整数) このブロブを書き込む際にmax_snapshot_bytes_per_sec（または管理サービスの回復設定が設定されている場合はindices.recovery.max_bytes_per_sec）スロットルによる待機に費やされた時間（ナノ秒単位）。
    • reads
    • (配列) このブロブに対して実行されたすべての読み取り操作の説明。 
      1. -   `````node
      • (オブジェクト) 読み取り操作を実行したノードを識別します。
        nodeのプロパティ
      • id
      • (文字列) 読み取りノードのID。
      • name
      • (文字列) 読み取りノードの名前
      • before_write_complete
      • (ブール値) 読み取り操作が書き込み操作が完了する前に開始された可能性があるかどうか。falseの場合は省略されます。
      • found
      • (ブール値) この読み取り操作でブロブが見つかったかどうか。書き込みが完了する前に読み取りが開始された場合や、書き込みが完了する前に中止された場合はfalseになる可能性があります。
      • first_byte_time
      • (文字列) 読み取り操作の最初のバイトを受信するまでに待機した時間。ブロブが見つからなかった場合は省略されます。
      • first_byte_time_nanos
      • (長整数) 読み取り操作の最初のバイトを受信するまでに待機した時間（ナノ秒単位）。ブロブが見つからなかった場合は省略されます。
      • elapsed
      • (文字列) このブロブを読み取るのにかかった時間。ブロブが見つからなかった場合は省略されます。
      • elapsed_nanos
      • (長整数) このブロブを読み取るのにかかった時間（ナノ秒単位）。ブロブが見つからなかった場合は省略されます。
      • throttled
      • (文字列) このブロブの読み取り中にmax_restore_bytes_per_secまたはindices.recovery.max_bytes_per_secスロットルによる待機に費やされた時間。ブロブが見つからなかった場合は省略されます。
      • throttled_nanos
      • (長整数) このブロブの読み取り中にmax_restore_bytes_per_secまたはindices.recovery.max_bytes_per_secスロットルによる待機に費やされた時間（ナノ秒単位）。ブロブが見つからなかった場合は省略されます。
  • listing_elapsed
  • (文字列) コンテナ内のすべてのブロブのリストを取得するのにかかった時間。
  • listing_elapsed_nanos
  • (長整数) コンテナ内のすべてのブロブのリストを取得するのにかかった時間（ナノ秒単位）。
  • delete_elapsed
  • (文字列) コンテナ内のすべてのブロブを削除するのにかかった時間。
  • delete_elapsed_nanos
  • (長整数) コンテナ内のすべてのブロブを削除するのにかかった時間（ナノ秒単位）。