自己管理型 mongot 配置のトラブルシューティング

始める前に

シナリオに取り組む前に、配置の現在の状態を確認してください。

• メトリクスの異常が発生しているものの、原因がまだ不明な場合は、mongot のメトリクス参照のメトリクス定義と、mongot の推奨アラートのスレッショルドから開始します。

• 配置または構成の変更を最近完了した場合は、mongot 接続を確認する。から開始してください。

症状がどのシナリオにも一致しない場合は、「サポートの診断の取得」に記述されているようにアーティファクトを取得し、サポートケースを開いてください。

mongot 開始しない

スタート後、mongot プロセスが起動しません。

記号

• プロセスはスタートアップ後数秒以内に終了します。

• コンテナ内では、プロセスがループ内で再起動します。

• "ready" ログメッセージは表示されません。

一般的な原因

優先順に、

1. 構成ファイルの形式が不正であるか、必要なフィールドが見つかりません。

2. スタートアップ時にmongodへの認証が失敗します。

3. mongot 構成済みのアドレスで mongod にアクセスできません。

4. TLS 構成エラーが発生します。

5. 構成されたポートはすでに使用されています。

6. データ パスは書き込み可能ではありません。

診断

最新のスタートアップ ログ行を確認します。エラー メッセージは、失敗しているサブシステムを識別します。

コンテナ

Linux

ログファイル

docker logs --tail 100 <container-id>

journalctl -u mongot --no-pager | tail -n 200

tail -n 200 /var/log/mongot/mongot.log

次のパターンを探してください。

• Failed to parse config file 無効な YAML を示します。

• Exactly one authentication mechanism must be used (x509 or scram) indicates that the syncSource connection is missing an authentication block or defines more than one. Nest the authentication fields under a single scramAuth or x509 block. See Configure Authentication and Authorization for mongot.

• Authentication failed または Unauthorized は、認証情報または x.509 のトラストの問題を示します。

• Connection refused または unable to connect to host はホストまたはポートが間違っていること、または mongod が実行されていないことを示します。

• SSL handshake failed CA トラストまたは証明書 SAN の不一を示します。

• Address already in use 別のプロセスが同じポートにバインドされていることを示しています。

• Cannot write to <dataPath> は、権限またはパスの問題を示しています。

解決

• Configuration: Fix the YAML. To learn about valid settings, see Configure mongot. If the error is Exactly one authentication mechanism must be used (x509 or scram), nest the syncSource authentication fields under a single scramAuth or x509 block. See Configure Authentication and Authorization for mongot.

• 認証: 必要なロールを持つユーザーが mongod 上に存在することを確認します。「 mongot の認証と承認の構成 」を参照してください。

• 到達可能性: mongot ホストから nc -zv <mongod-host> <mongod-port> を実行します。ファイアウォール、DNS、mongod bindIp 設定を確認します。

• TLS: mongot と mongod の両方が同じ認証局 (CA) を信頼していることを確認し、各側の証明書チェーンが信頼できる CA につながるようにします。また、証明書 SAN が mongot が使用するホスト名と一致していることを確認します。「 の TLS 暗号化を構成する。」を参照してください。mongot

• 使用中のポート: ss -lntp または lsof -i :<port> を使用して、衝突するプロセスを特定します。mongot ポートを変更するか、他のプロセスを停止します。

• データ パス: ディレクトリが存在し、mongotプロセス ユーザーが書き込み可能であることを確認します。必要に応じて所有権と許可を更新します。

接続エラーによるクエリの失敗

mongod が mongot にアクセスできないため、クエリが失敗します。

記号

• $search、$searchMeta、または $vectorSearch クエリは、Error connecting to <host>:<port> :: Connection refused のような接続エラーを返します。

• または、クエリは Error connecting to Search Index Management service を返します。

一般的な原因

1. mongot mongodが接続しようとしているホストで実行されていません。

2. mongot の mongod ホストまたはポート設定が間違っており、mongot リスナーと一致しません。

3. mongot 実行中であるが、クラッシュしたか、再起動しています。

4. TLS が不一しています。mongod は TLS に設定されていますが、mongot は設定されていないか、または逆です。

診断

mongod ホストから mongot への接続をテストします。

nc -zv <mongot-host> <mongot-port>

mongotホストから、プロセスが実行され、リッスンしていることを確認してください：

ps aux | grep '[m]ongot'
ss -lntp | grep <mongot-port>

一致するエラーと、構成された mongot ホストの mongod ログを調査します。

grep -E 'mongotHost|searchIndexManagementHostAndPort' \
  /var/log/mongodb/mongod.log

解決

• mongot が実行されていない場合は、再起動します。起動できない場合は、mongot が起動しません。に従ってください。

• mongotホスト設定が間違っている場合は、mongodパラメータを修正してmongodを再起動します。

• TLSが一致しない場合は、両側のTLS構成を調整します。「 のTLS暗号化の構成」を参照してください。mongot

mongot 再同期し続ける

インデックスは安定状態から繰り返し削除され、最初の同期を開始します。

記号

• ログはInitial sync startingの後に例外が繰り返されます。

• 安定状態では、ログに Exception requiring resync occurred during steady state replication が表示されます。

• インデックスマネージャーの状態は INITIAL_SYNC に戻ります。

• 再同期ウィンドウ中に、検索で古い結果が返されます。

一般的な原因

1. mongod oplog が mongot が追いつく前にロールオーバーしました。通常、mongot が速度が遅いか停止しているか、oplog が小さすぎるためです。

2. ネットワークの中断や短時間の mongod 再起動などの一時的な問題により、定常状態の例外が発生しました。1 回の発生は復旧可能ですが、繰り返し発生は復旧できません。

3. ドキュメントマッピングの爆発により mongot ヒープが繰り返し填められ、メモリー不足エラーがトリガーされて再同期が行われます。

4. インデックス データが破損しています。

5. インデックス、ダイナミックマッピング、または高価なフィールドの選択が多すぎると、レプリケーションラグが持続します。

診断

次のメトリクスを確認します。

• mongot_replication_mongodb_indexManagerState INITIAL_SYNC と STEADY_STATE の間でサイクルします。

• mongot_index_stats_numLuceneMaxDocs 循環しているか、停滞していいます。

• mongot_index_stats_indexing_replicationLagMs 上昇し続けています。

• mongot_jvm_memory_used_bytes メモリの負荷が増えると mongot_jvm_gc_pause_seconds_sum が増加します。

再同期に先立つエラーについては mongot ログを参照し、oplog window とヒープを確認します。

grep -E 'SteadyStateException|CappedPositionLost|OutOfMemoryError' \
  mongot.log

mongosh で、mongod oplog サイズを db.getReplicationInfo() で確認します。

解決

• oplog が mongot 適用レートに対して小さすぎる場合は、mongod oplog サイズを増やすか、mongot キャパシティーを増やすか、同時インデックスの数を減らすことでギャップを埋めます。

• 安定状態の例外が繰り返される場合は、FTDC をキャプチャしてサポート ケースを開いてください。

• ドキュメントマッピングの爆発の場合は、通常、任意のキーを持つドキュメントを取り込むdynamic: trueマッピングを持つインデックスである問題のあるインデックスを検出します。静的マッピングに切り替えるか、フィールドセットを制限して、mongotを再起動してヒープ状態をクリアします。

• まれであるインデックスの破損の場合は、FTDC を取得した後、影響を受けたインデックスを削除して再作成します。データ パス下のファイルを手動で削除しないでください。

OutOfMemory Error or mongot Killed by the OS

mongot メモリが不足して終了します。

記号

• mongot 予期せず終了し、コンテナ再起動回数が増加します。

• ログは OutOfMemoryError: Java heap spaceで終わります。これは JVM 側のメモリ不足エラーです。

• dmesg または journalctl のシステム ログによると、OOM キラーによってプロセスが終了されました。これはホスト側のメモリ不足エラーです。

一般的な原因

1. ヒープは、ワークロードに対して小さすぎます。特に大規模な最初の同期またはマージ中に小さすぎます。

2. ドキュメント マッピングの爆発によりヒープが消費されます。「mongot の再同期が続く。を参照してください。

3. コンテナのメモリ上限が低すぎます。ヒープのサイズが正しく設定されている場合でも、JVM の非ヒープオーバーヘッドにより上限を超える可能性があります。

4. インデックスの数が多すぎる、コストの高い定義など、インデックスの定義が不良であると、メモリの負荷が増加します。

5. メモリリークが発生します。これはプレビュービルドではまれですが、発生する可能性があります。

診断

次のメトリクスを確認します。

• mongot_jvm_memory_used_bytes メモリ集中型のクエリとインデックス定義によって増加します。

• mongot_jvm_gc_pause_seconds_sum ガーベージ コレクションの一時停止に要した累積時間を表示します。

• machine_swap_bytes 健全な配置ではほぼゼロになります。スワップ使用量は、メモリの圧力が重大であることを示します。

mongot ログでメモリー不足のスタック トレースと構成済みのヒープ サイズを確認します。

grep -E 'OutOfMemoryError|Java heap space' mongot.log
ps -ef | grep '[m]ongot' | grep -oE '\-Xmx[0-9a-zA-Z]+'

コンテナの場合は、設定されたメモリリミットを確認します。

docker inspect <container> | grep -i memory

解決

• ホストにメモリのヘッドルームがある場合は、-Xmxを増やします。

• コンテナでは、ヒープ以外のオーバーヘッドを収容するため、メモリの制限を -Xmx よりも大きく設定します。開始点として、コンテナの制限を少なくとも -Xmx の値に 30% を加えた値に設定します。

• ヒープが十分なサイズであるにもかかわらずメモリが不足する場合は、爆発の原因となるインデックスの作成パターンを探してください。mongot ログにインデックスが識別されます。

• インデックスの数を減らすか、メモリの負荷の原因となっている場合は、コストの高いインデックス定義を簡素化します。

• メモリー リークが疑われる場合は、FTDC とヒープ ダンプを取得してサポートに連絡してください。

最初の同期が遅いまたは停滞している

新しいインデックスは、最初の同期を完了するに時間がかかります。

記号

• インデックスの状態は長時間 INITIAL_SYNC のままです。

• レプリケーション マネージャーが最初の同期を再試行する前に INITIAL_SYNC_BACKOFF に入る場合があります。

• mongot_index_stats_numLuceneMaxDocs ゆっくりとしか増えません。

• 最初の同期の実行中は、インデックスはクエリできません。

一般的な原因

1. mongod ソース ホストはプロビジョニングが不足しており、最初の同期を十分な速度でフィードできません。

2. その他のディスク、CPU、またはメモリの負荷により、ビルドが低速化します。

3. 大規模な初期バックフィルは、現在のハードウェアエンベロープを超えています。

診断

ドキュメントの増加については、mongot_replication_mongodb_indexManagerStateとmongot_index_stats_numLuceneMaxDocsを監視します。

最初の同期中は mongot_index_stats_indexing_replicationLagMsを正規として扱わないでください。最初の同期中は、このメトリクスに有意なデータが入力されません。その代わりに、システムの健康状態メトリクスを確認して、システムに十分なリソースがあることを確認します。

解決

• ボトルネックである場合は、mongod ソースホストを増やします。

• システムのリソースが制約されている場合は、CPU またはメモリを追加します。

• 大規模な初期ビルドを再試行する前に、ディスクのヘッドルームを再度確認してください。

PENDING または BUILDING 状態で停滞しているインデックス

インデックスはPENDINGまたはBUILDING状態から進行しません。

記号

• インデックスは、大きくないコレクションでPENDINGまたはBUILDINGの状態で数分以上経過します。

• mongot ログには失敗は表示されていませんが、進行がないことは表示されています。

一般的な原因

1. mongot 同期の進行ができていません。「大規模なレプリケーションラグ」を参照してください。

2. 自動埋め込みインデックスの埋め込みエンドポイントとなる接続されたデバイスが失敗しています。

3. インデックスの作成エキゼキューター プールは、同時に作成される他のインデックスによって飽和しています。

4. mongot 最近再起動され、インデックスが追いついています。

5. 定義が受け入れられているにもかかわらず、ディスクの負荷により新規ビルドまたはリビルドが一時停止されました。

診断

mongot_replication_mongodb_indexManagerState と mongot_index_stats_numLuceneMaxDocs の進行状況を確認します。

mongosh で、インデックスのステータスとエラーフィールドを確認します。

db.<collection>.getSearchIndexes()

インデックスの作成スループットが増加していることを確認します。

rate(mongot_index_stats_indexing_insert_total[5m])

自動埋め込みインデックスの場合は、埋め込みの再試カウンターがゼロより大きいかどうかを確認します。

rate(mongot_indexing_steadyStateChangeStream_rescheduledEmbeddingGetMores_total[5m])
rate(mongot_initialsync_queue_requeuedEmbeddingInitialSyncs_total[5m])

解決

• インデックス作成スループットが平坦な場合は、インデックス名と例外について mongot ログを確認してください。

• 埋め込みの再試行回数が 0 より大きい場合は、埋め込みパスを修正します。MongoDB ベクトル検索 自動埋め込みの mongot の構成を参照してください。

• エグゼキュータ プールが飽和している場合は、同時インデックス構築を減らすか、mongotを増やします。

• ディスクがボトルネックとなっている場合は、ヘッドルームを追加するか、ビルドをより大きなノードに移動してください。

クエリで空の結果が返される

一致するドキュメントが存在するにもかかわらず、クエリでは結果が返されません。

記号

• 検索インデックスで見つかると予想されるドキュメントに対してfindOne()を実行できます。

• 同じフィールドに対する $search クエリは、結果を返さないか、予想より少ない結果を返します。

一般的な原因

1. インデックスは、一致すると予想されるドキュメントの構築が完了していません。

2. レプリケーションラグとは、mongot がまだドキュメントを受信していないことを意味します。

3. インデックス定義には、検索するフィールドが含まれていません。

4. クエリ式が間違っています。たとえば、string としてインデックスされたフィールドに対する数値式などがあります。

5. 特定のドキュメントでインデックスの作成に失敗しました。

診断

mongosh でインデックスの状態を確認し、インデックスがドキュメントを見ているかどうかを確認します。

db.<collection>.getSearchIndexes()

次に、mongot_index_stats_indexing_replicationLagMs を確認して、レプリケーションラグをチェックします。

解決

• インデックスが準備完了状態になるまで待機します。

• レプリケーションラグが解消するまで待ちます。

• インデックス定義またはクエリを調整します。

• 特定のドキュメントでインデックスの作成に失敗した場合、mongot ログに失敗の原因が記載されます。それらのドキュメントを修正またはフィルターします。

CPU の飽和またはスロットリング

CPU の負荷が続くと、クエリとレプリケーションのパフォーマンスが低下します。

記号

• CPUに持続的な負荷がかかると、クエリのレイテンシが上昇します。

• クエリの処理とインデックスの作成がCPUを奪い合うため、レプリケーションラグが増大します。

• 重大な場合は、ヘルスチェックが失敗し、プロセスが再起動します。

一般的な原因

1. mongot ホストは、現在のクエリとインデックスの作成作業の組み合わせに対してプロビジョニングが不足しています。

2. 同時に多くのインデックスの作成作業がクエリ実行と競合します。

3. ワークロードには、ロードシェッディングまたはキャパシティーの拡大が必要です。

診断

次のメトリクスを確認します。

• mongot_command_searchCommandTotalLatency_seconds_max

• mongot_index_stats_indexing_replicationLagMs

• ホスト CPU と負荷メトリクスは、飽和状態になると急増します。

ホストが CPU スロットルされていることを示す明示的なログ メッセージはありません。

解決

• mongot ホストの CPU を増やします。

• 利用可能な場合は、ロードシェッディングの実行によりロードを軽減します。

• レプリケーションアクティビティがクエリと競合する場合は、インデックスの作成を簡素化します。

ディスクの負荷またはデータパスがほぼ満杯

mongot データパスの空き容量が少なくなっています。

記号

• mongot データ パス上の空き容量がゼロに近づいています。

• ディスク使用量が多い場合、既存のインデックスにレプリケーションラグが蓄積されます。

• ディスクの負荷が重度な場合、新しいインデックスまたは再構築されたインデックスは INITIAL_SYNC のままになる可能性があります。

• ディスク保護のためにレプリケーションが一時停止されている間も、クエリは引き続き成功します。

一般的な原因

1. ホストには、通常のインデックス作成の増加に十分な空き容量がありません。

2. 新しいインデックスまたは再構築されたインデックスには、現在のディスクが提供できる一時的なヘッドルームよりも多くのヘッドルームが必要です。

診断

次のメトリクスを確認します。

• mongot_system_disk_space_data_path_free_bytes データディレクトリ内の空きバイトを報告します。

• mongot_system_disk_space_data_path_total_bytes データディレクトリ内の合計バイト数を報告します。

ディスクのスレッショルに関連するレプリケーションの一時停止の動作に注意してください。ディスク使用量が約 90% を超えるとレプリケーションは停止し、使用量が約 85% を下回った後に再開します。新しいインデックスまたはリビルドの場合、ディスクの負荷が保護スレッショルを既に越えている場合は、定義は受け入れられますが、ビルドは停滞したままになることが予想されます。

解決

• ホストまたはボリュームを安全に拡張できる場合は、ディスク キャパシティーを追加します。

• 操作上許容できる場合は、不要なインデックスを削除してスペースを解放します。

• 大型インデックスをビルドまたは再構築する前に、余計なヘッドルームを確保してください。再構築中は、予想される安定状態のフットプリントの約 125% を見込んでおきます。

• ローカル インスタンスストア NVMe では、インプレースでサイズ変更できるとは限りません。ローカル インスタンスストアのキャパシティを超える場合は、通常、より大きなマシン クラスと再インデックスが必要になります。

• EBS バックアップされたストレージを使用する場合、ライブリサイズはより実現的ですが、NVMe は mongot のパフォーマンスにとって推奨されるガイダンスであり続けます。mongot のストレージ クラスの推奨事項を参照してください。

16 MB BSON 制限からのレプリケーションラグ

変更ストリーム イベントが 16 MB BSON 制限を超え、レプリケーションが停滞します。

記号

• 安定状態のレプリケーションエラーの後、インデックスが古くなるか、再構築が開始されます。

• mongotログには、getMore中にchange stream payload exceeding 16MB BSON limit、BSONObjectTooLarge、またはエラーコード10334が表示されます。

• 保存されたドキュメントは 16 MB より小さく表示される場合がありますが、失敗は発生します。

一般的な原因

1. 変更ストリーム イベントにはドキュメントと追加の変更ストリーム メタデータの両方が含まれているため、16 MB を超えます。

2. 既に大きなドキュメントに大きな更新を行うと、変更ストリームのペイロードは、保存されているドキュメントのサイズだけではなく、より大きくなります。

診断

次のメトリクスを確認します。

• mongot_changestream_numSplitEvents_total 16 MB のペイロードサイズを超えるイベントをカウントします。

• mongot_index_stats_indexing_replicationLagMs 特定のインデックスのレプリケーションラグを報告します。

mongot ログで次の文字列を検索します。

• change stream payload exceeding 16MB BSON limit

• BSONObjectTooLarge

• Executor error during getMore

• code 10334

ドキュメント サイズのチェックで最大のドキュメントが16 MB 未満である場合でも、このシナリオを除外しないでください。変更イベントには、ドキュメント自体に加えてメタデータが含まれます。

解決

• ドキュメントのサイズを小さくし、可能な限り既に大きなドキュメントへの大規模な更新を避けます。

• 可能な場合は、既存の大規模なドキュメントに大規模な更新を適用するのではなく、ドキュメントを置き換えます。

• ほとんどの書き込みが更新である場合は、更新クエリを見直して、変更ストリーム イベント メタデータのサイズを小さくしてください。

• ワークロードを修正した後、再構築が完了するまで待ちます。ワークロードパスワードなしが変わらない場合、インデックスは同じ失敗に再び襲われる可能性があります。

• ワークロードを調整した後も問題が再発する場合は、ログを取得し、事故の詳細とともにエスカレートします。

大規模なレプリケーションラグ

レプリケーションラグは時間とともに着実に増加します。

記号

• レプリケーションラグは着実に増加し、何時間もしくは何日もに達する可能性があります。

• mongot メモリーの制約を受けるか、または実行を続けるためにメモリー不足が繰り返し発生します。

• ホストはクエリを引き続き実行できますが、レプリケーション作業と大規模なインデックスのフットプリントにより、クエリのパフォーマンスが低下する可能性があります。

一般的な原因

1. インデックスの数が大きいと、レプリケーションとインデックスの作成のオーバーヘッドが増加します。

2. dynamic: true を広範囲で使用すると、フィールド数とインデックスサイズが増加し、メモリーの負荷が増えます。

3. メモリー不足イベントが繰り返し発生すると、遅延が悪化し、メトリクスがぎこちになったり不完全になったりします。

4. ボトルネックはソースデータベースにあります。CPU とキャッシュの圧力が高いプロビジョニング不足のmongodセカンダリでは、変更ストリームイベントが十分な速度で発行されない可能性があります。

診断

次のメトリクスを確認します。

• mongot_index_stats_indexing_replicationLagMs 特定のインデックスのレプリケーションラグを報告します。

• mongot_indexing_steadyStateChangeStream_getMoresScheduled スケジュールされた getMore 操作を報告します。

• mongot_replication_mongodb_indexManagerState インデックスが進行していないことを特定します。

• mongot_jvm_memory_used_bytes また、ホスト CPU とロードメトリクスにリソースの負荷が表示されています。

インデックスの総数をカウントし、多くが dynamic: true に依存しているか、または不要な高カーディナリティフィールドをインデックスしているかを検討します。

解決

• ノードのメモリが不足したり、メモリに制約がある場合は、まずmongot CPUとメモリを増やします。

• インデックスの合計数を減らします。インデックスの数が非常に多い場合、変更ストリームの負荷を制御しない限り、検索ノードを追加すると負荷パターンが悪化する可能性があります。

• 必要ない場所では、ダイナミック スキーマ マッピングをオフにします。dynamic: false を使用し、クエリに必要なサブフィールのみを明示的にマップします。

• インデックス付きフィールドの数を減らします。特に、タイムスタンプやユーザーID などの高濃度フィールドです。また、ファセットに使用されていないディープファセットマッピングを削除します。

• mongod セカンダリがボトルネックである場合は、コアデータベースを増やして変更ストリームのスループットを向上させます。

TLS ハンドシェイクの失敗

mongot と mongod の間の TLS ハンドシェイクが失敗します。

記号

• mongotログには SSL handshake failed、Certificate verification failed、bad certificateが表示されます。

• mongod ログには、mongot に接続しようとすると同様のエラーが表示されます。

一般的な原因

1. CA の不一致: 両端が同じ CA を信頼していません。

2. 認証 SAN には使用中のホスト名が含まれていません。

3. 証明書の有効期限が切れています。

4. TLS モードの不一: 一方のサイドで TLS が必要であり、もう一方では無効になっています。

5. サイファー スイートまたは TLS バージョンの不一致。これはまれです。

診断

各サイドが提供する証明書を調査し、CA に対してチェーンを確認します。

openssl s_client -connect <mongot-host>:<mongot-port> -showcerts
openssl s_client -connect <mongod-host>:<mongod-port> -showcerts
openssl verify -CAfile <ca-bundle> <cert-file>
openssl x509 -in <cert-file> -text -noout

解決

• 正しい CA を両方のエンドポイントとなる接続されたデバイスに配布します。

• 正しい SAN リストで証明書を再発行します。

• 期限切れた証明書を更新します。

• 両側の TLS モードを調整します。「mongotの TLS 暗号化の構成」を参照してください。

インデックスが Lucene ドキュメント制限に達します

A single unpartitioned search index exceeds Lucene's maximum document count and can no longer index new documents.

This scenario applies to mongot deployments that you run directly on Linux or in a Docker container. If you deploy mongot with the MongoDB Controllers for Kubernetes Operator, see the MongoDB Controllers for Kubernetes Operator documentation for Kubernetes-specific troubleshooting.

Before you change the partition count, confirm the following:

• Your mongot version supports increasing numPartitions for an existing search index.

• You have enough free space to retain the existing index while the replacement index builds. Plan for temporary storage for both index generations.

• You have recorded baseline query latency and replication health for the affected index.

• You know the current index definition and the target numPartitions value.

If the index is approaching the limit but is still indexing normally, start the procedure before the index reaches the limit. If the index has already reached the limit, expect the existing index to remain stale until the replacement index finishes building.

記号

• The index stops making forward progress near the Lucene document-count limit.

• ログには java.lang.IllegalArgumentException: number of documents in the index cannot exceed 2147483519 が表示されます。

• mongot_index_stats_numLuceneMaxDocs approaches the hard limit or stops advancing after the limit is reached.

• The index manager reports a failed state.

• Search queries continue to return results, but newly inserted or updated documents are not reflected in the index.

一般的な原因

1. A single unpartitioned index exceeded Lucene's maximum document count.

2. Lucene accepts a new index and begins building, but reaches the same limit before the build completed.

3. The index was partitioned with too few partitions for the expected document volume.

4. The index reached the limit before partitioning was planned, leaving insufficient time to complete the replacement build before the existing index became stale.

診断

1. Check the index status from mongosh:

   db.<collection>.getSearchIndexes()

2. Review mongot_index_stats_numLuceneMaxDocs for the affected index.

3. Search the mongot log for the following string:

   java.lang.IllegalArgumentException: number of documents in the index cannot exceed 2147483519

4. Check the index manager state and confirm whether the index is in INITIAL_SYNC, STEADY_STATE, or a failed state.

5. Check available space on the mongot data path. A partitioning operation builds a replacement index and can temporarily require substantially more storage than the steady-state index.

6. Review query latency and replication lag before the change. Partitioned indexes can introduce query fan-out and affect search performance, particularly for workloads that use facets, sorts, or other operations that coordinate work across partitions.

解決

Partition the index so that each partition remains below Lucene's document-count limit, then rebuild the index with an appropriate numPartitions value.

重要

Increasing numPartitions starts an asynchronous index rebuild. Updating the index definition does not make the new partitioned index immediately queryable.

1. Choose a partition count. Choose a partition count that keeps the projected document count per partition comfortably below the Lucene limit. Account for future growth, deleted documents that have not yet been purged, rebuild duration, and available disk capacity.

   As a planning guideline, begin evaluating partitioning well before the index approaches the Lucene document-count limit of 2147483519 documents. Treat an index near the limit as urgent because the existing index can become stale before the replacement build completes.

   注意

   Increasing the number of partitions increases index capacity, but it can also increase query latency. Benchmark representative production queries before and after the change.

2. Update the index definition. Reissue the updateSearchIndex command with the existing index definition and a higher numPartitions value. Preserve the rest of the index definition.

   The following example increases an index from one partition to four:

   db.runCommand({
     updateSearchIndex: "myCollection",
     name: "mySearchIndex",
     definition: {
       mappings: {
         dynamic: true
       },
       numPartitions: 4
     }
   })

   The command updates the definition and starts the replacement build. The build runs asynchronously in the background.

3. Monitor the replacement build. Monitor the index until the replacement build completes:

   • Check the index state with db.<collection>.getSearchIndexes().

   • Confirm that document counts continue to increase during INITIAL_SYNC or BUILDING.

   • Monitor mongot_index_stats_numLuceneMaxDocs.

   • Monitor disk usage on the mongot data path.

   • Monitor CPU, memory, storage performance, and replication lag.

   • Monitor query latency while the existing index serves production traffic.

   A large replacement build can take a substantial amount of time. The new index is not queryable while its initial sync is in progress.

   Do not treat an accepted updateSearchIndex command as proof that the index is already partitioned. Verify the index state and wait for the replacement build to complete.

After the replacement index becomes ready, measure query latency. Partitioning might require mongot to coordinate work across multiple partitions, which can increase latency for some workloads, including facet-heavy queries, sorted queries, and queries that combine range or wildcard predicates with sorting. Do not use a single latency estimate for all workloads. Measure the queries that matter to your application, including p50, p95, and p99 latency, before and after the change.

自動埋め込みの失敗

自動埋め込みインデックスは埋め込みエンドポイントに到達できません。

記号

• Automated Embedding インデックスは PENDING または BUILDING にとどまります。

• mongot ログには、埋め込みエンドポイントとなる接続されたデバイスに対するエラーが表示されます。

• 埋め込み再試行カウンタ mongot_indexing_steadyStateChangeStream_rescheduledEmbeddingGetMores_total または mongot_initialsync_queue_requeuedEmbeddingInitialSyncs_total がゼロより大きいです。これらのカウンタを間接的な指標として使用し、埋め込みエンドポイントからの実際の HTTP エラーについてはログを確認してください。

一般的な原因

1. モデル API キーが無効です。または有効期限が切れています。

2. ネットワークが埋め込みエンドポイントに接続できません。

3. 埋め込みプロバイダーはリクエストのレート制限を行っています。

4. 埋め込みプロバイダーで停止時が発生しています。

診断

mongot ホストから埋め込みエンドポイントへの接続をテストし、ログを確認します。

grep -E 'voyage|embedding' mongot.log

解決

• モデル API キーを置き換えて mongot を再起動します。

• 埋め込みエンドポイントへのオープンネットワークイーグレス。

• プロバイダーがリクエストのレート制限を行っている場合は、制限を引き上げるか、インデックスの作成の同時実行数を減らします。

• If the provider has an outage, monitor Voyage AI status and consider switching endpoints.

全体の埋め込み構成モデルについては、MongoDB ベクトル検索の自動埋め込みの mongot を構成するを参照してください。

持続的な IOPS やページフォールトなどのストレージシグナル

持続的なストレージ IOPS またはページフォルトは、ストレージのボトルネックを示します。ローカル NVMe で実行する場合は、まずメモリヘッドルームを確認してください。SAN、クラウドの多目的 SSD、SATA SSD などのその他のストレージ クラスで実行する場合、ストレージ クラスが根本的な原因である可能性が高く、移行が必要です。詳細については、「mongot のストレージ クラスの推奨事項」を参照してください。

明確な原因なしに性能が低下します

最近の配置変更なしでパフォーマンスが劣化する。

記号

• 配置の変更が明らかでないのに、クエリのレイテンシが上昇しました。

• CPU またはメモリの使用量が増加しました。

一般的な原因

1. ワークロードが変更され、より多くまたはより大きなクエリが増えました。

2. 新しいインデックスでリソースが消費されるようになりました。

3. ドキュメント マッピングの暴発によりヒープが消費されます。

4. ストレージの劣化。たとえば、ノイジーネイバー、RAID の再構築、またはクラウドプロバイダーの問題など。

5. JVM の更新後、ガーベージ コレクションのチューニングに回帰が発生しました。

診断

クエリのレイテンシ、ヒープ、エクゼキューター キュー、ストレージ IOPS などの症状によってメトリクスをピボットします。メトリクスの定義としきい値については、mongot のメトリクス参照 および mongot の推奨アラート を参照してください。

解決

解決策は根本原因によって異なります。選択肢には、拡大、キャパシティー計画、またはインデックスの検討があります。これには、未使用インデックスの削除やマッピングの改善などが含まれます。

サポートの診断をキャプチャする

問題をローカルで解決できない場合は、サポート ケースを開く前に次の情報を取得します。

1. mongot 問題の発生時間帯とその 1 時間前を含むログ。同じウィンドウの mongod ログを転送します。

2. 影響を受ける mongot インスタンスの FTDC。「mongot ログと FTDC」を参照してください。

3. 問題の時間内のメトリクスのダッシュボード スナップショット。

4. mongot および mongod のバージョン。

5. 最近の配置、構成の変更、またはトラフィック パターンなど、変更された内容。

6. オンデマンドで再現できる場合は、問題を再現する手順。