/ /

mongot 日志和 FTDC

mongot 暴露两个在主机诊断界面，可帮助您诊断 MongoDB Search 和 MongoDB 向量搜索的问题：

日志：mongot 活动的人可读记录，包括警告和错误。
FTDC（全时诊断数据捕获）：每秒捕获详细内部状态的二进制诊断流，用于支持交接。

使用日志调查事件，并在准备 MongoDB 支持案例时捕获两个界面。

日志

mongot 日志记录过程活动，包括警告和错误。使用日志验证启动完成、监控稳态状态健康并调查故障。

日志目标

mongot 写入日志的位置取决于您的部署类型：

部署类型	默认目的地
Linux tarball	`stdout` 和 `stderr`，或在 `mongot` YAML 配置中设置 `logging.logPath` 的文件。
容器	`stdout` 以及 `stderr`。使用 `docker logs <container>` 检索日志。
`atlas-local`	`stdout` 和容器内的 `stderr`。使用 `docker logs` 检索日志。
Kubernetes Operator	`stdout` 和 `stderr` 的舱。使用 `kubectl logs <pod>` 检索日志，并将其转发到集群日志平台。

日志详细程度

mongot 配置文件中指定的 logging.verbosity 选项接受以下级别：

等级	何时使用
`DEBUG`	当您调查特定故障时。将此级别保持几小时，而不是几天。
`ERROR`	很少适用于生产，因为会丧失 `WARN` 问题的上下文。
`INFO`	默认.适用于生产。
`TRACE`	仅限工程和支持深入探讨。非常详细。
`WARN`	当您需要减少日志量并对错误进行单独报警时。

mongot 在启动时读取详细程度。要更改它，请重启 mongot。

日志格式

mongot 发出结构化 JSON 日志，每行一个 JSON 对象。此格式将 mongot 日志与 mongod 结构化日志记录格式对齐。

每个 mongot 日志条目都包括 t、s、svc、ctx、n、msg 等字段，以及可选的 attr。示例：

{"t":"2026-06-22T14:03:41.582+0000","s":"INFO","svc":"MONGOT","ctx":"indexing-lifecycle-0","n":"com.xgen.mongot.replication.mongodb.initialsync.BufferlessInitialSyncManager","msg":"Beginning initial sync.","attr":{"startTime":"2026-06-22T14:03:41.582+0000","indexGenerationId":"6857f3b6e4b04c2a9d1f0a12-f6-u0-a0"}}

每个日志对象包含以下字段：

字段	说明
`t`	UTC 和 ISO-8601 格式的时间戳。
`s`	严重性。以下之一：`TRACE`、`DEBUG`、`INFO`、`WARN` 或 `ERROR`。
`svc`	发出条目的服务，例如 `MONGOT`。
`ctx`	执行上下文，例如线程或任务名称。
`n`	记录器名称。
`msg`	人类可读消息。
`attr`	可选的事件特定结构化属性，例如 `startTime`、`numQueued` 和 `indexGenerationId`。`mongot` 省略空值和空值。

初创企业时要注意什么

健康的 mongot 启动会在默认 INFO 详细程度下发出一系列可识别事件。查找这些事件而不是特定的字符串：

事件	消息文本
索引的初始同步开始	`Beginning initial sync.` 从 `BufferlessInitialSyncManager`，带 `attr.startTime` 和 `attr.indexGenerationId`。
初始同步队列活动	`Queued initial syncs.` 从 `InitialSyncQueue`，带 `attr.numQueued`。
启动时的基于磁盘的重启检查	`Replication URIs unavailable, skipping disk-based restart check` 来自 `DefaultConfigManager`。复制正在连接时，预计会出现短暂性问题。
shutdown	`Shutting down.` 从 `DefaultConfigManager`，在优雅关机时。

启动时存在其他信息行。上述事件是验证的承载事件。

以下指示表明启动未完成：

指示器	操作
即使集群已索引集合，也未出现 `Beginning initial sync.` 事件。`mongot` 尚未达到初始同步阶段。	查看早期日志，以查找身份验证或复制 URI 错误。
事件 `Beginning initial sync.` 之后是事件 `Exception requiring resync` 或 `InitialSyncException`。同步已启动，但失败。	要进行修复，请参阅疑难排查自管理 mongot 部署。
`Replication URIs unavailable, skipping disk-based restart check` 消息在几秒后会重复。`mongot` 正在等待 `mongod` 配置。	检查 `mongod` `mongotHost` 参数。

稳态状态下的注意事项

在稳定状态下，健康的日志大多数时候是静默的。预计会收到来自背景任务（如合并和 FTDC 跳动）的周期信息消息，以及暂时客户端行为的偶尔 WARN 条目。不要预计 ERROR 或 Exception 条目。

以下稳态日志模式值得关注：

模式	含义
`Exception requiring resync occurred during steady state replication` (`SteadyStateException`)	`mongot` 在 oplog 中失去了位置，并正在重新同步。可能是因为 `mongod` oplog 太小或 `mongot` 太慢，导致 oplog 卷回，或发生下游错误。捕获支持周围五分钟。
`CollectionScan died due to position in capped collection being deleted` (`CappedPositionLost`, error 136)	oplog 在 `mongot` 追上之前已经卷动。增加 `mongod` oplog 大小、修复上游导致 `mongot` 缓慢的原因，或两者兼而有之。
`Dropping all pooled connections to <host>:<port> due to ShutdownInProgress`	`mongod` 重启期间正常。在没有相应 `mongod` 重启的情况下频繁、重复发生表明连接池问题。
文档映射爆炸	索引遇到的文档包含的字段过多，这通常是由于开启了动态映射，导致文档具有任意密钥。索引可能会停滞，或 `mongot` 可能会出现内存不足。

要将这些模式映射到修复程序，请参阅自管理 mongot 部署的疑难排查。

搜索日志

由于 mongot 日志是 JSON，因此 jq 是搜索它们的最自然工具。以下示例显示了常见查询：

# All errors
jq 'select(.s == "ERROR")' mongot.log
# Initial sync activity
jq 'select(.msg | startswith("Beginning initial sync"))' mongot.log
# Replication or sync from specific loggers
jq 'select(.n | test("BufferlessInitialSyncManager|InitialSyncQueue|InitialSyncManager"))' mongot.log
# Resync events
jq 'select(.msg | test("requiring resync|InitialSyncException|SteadyStateException"))' mongot.log
# Connection-pool churn
jq 'select(.msg | test("Dropping all pooled connections|ShutdownInProgress"))' mongot.log
# Embedding-related entries
jq 'select(.msg | test("embedding|voyage"; "i"))' mongot.log

由于 JSON 是单行的，因此 grep 也可以使用：

grep '"s":"ERROR"' mongot.log
grep '"msg":"Beginning initial sync\.' mongot.log
grep -E '"n":"[^"]*(BufferlessInitialSyncManager|InitialSyncQueue)' mongot.log

对于 Elasticsearch、Splunk 和 DataDog 等日志平台，请对 s:ERROR、n:<logger> 或 attr.<key> 而不是文本进行过滤器。字段是稳定的，但全文模式可能会在不同版本之间移动。

对于运行多个 mongot 实例的部署，请在日志转发标签中包含实例标识符，以便您可以按实例进行过滤。

日志分析提示

分析 mongot 日志时，请记住以下几点：

日志并不总是在消息中包含索引名称。对于索引失败，相关日志行可能会在同一日志记录上下文中提前或推迟几行出现。捕获一个窗口，而不是单行。
在同一时间窗口中，将 mongot 日志与 mongod 日志交叉引用。许多 mongot 错误都是 mongod 事件的下游。
如果您打开 MongoDB 支持用例，请发送完整的日志文件或宽时间窗口，而不是过滤的 ERROR 行集。

FTDC

FTDC is a binary diagnostic stream that captures detailed internal state every second to disk. FTDC is the canonical artifact that MongoDB Technical Services teams use to diagnose mongot issues.

FTDC 包含的内容

FTDC 样本包含与 Prometheus 指标相同类别的数据，以及 mongot 不对外暴露的内部状态：

进程和 Java虚拟机（JVM）状态，包括堆、垃圾回收和线程
每个索引的索引统计信息
每个操作符的查询延迟
复制状态和 oplog 位置
执行程序池状态
Lucene 合并和缓存状态
配置和生命周期事件
连接池状态

FTDC 文件位置

默认情况下，mongot 会将 FTDC 文件写入 <storage.dataPath>/diagnostic.data/，这与 mongod 与 <storage.dbPath>/diagnostic.data/ 一起使用的规则相同。

对于 mongot 实例（其中 storage.dataPath 设置为 /var/lib/mongot），FTDC 文件位于 /var/lib/mongot/diagnostic.data/。

mongot 使用时间戳命名文件，并自动轮换这些文件。文件大小通常为：

每个文件几百 KB
负载下每小时几个文件
每个 mongot 实例每天大约 1 GB，具体取决于负载

磁盘上 FTDC 存档目录的总大小受 advancedConfigs.ftdc.directorySizeMb 限制。

重要

mongot 自动轮换 FTDC 文件。事件发生时请勿手动删除 FTDC 文件。MongoDB 支持团队在诊断问题时会请求 FTDC 文件。

配置 FTDC

FTDC 默认处于启用状态。要覆盖默认值，请在 mongot YAML 配置中 advancedConfigs.ftdc 块下设置以下选项：

选项	默认	说明
`enabled`	`true`	启用 FTDC。当 `false` 时，`mongot` 不会捕获 FTDC 数据。
`directorySizeMb`	`100`	FTDC 存档目录的最大总大小，以兆字为单位。必须大于等于 `10` 并且大于 `fileSizeMb`。
`fileSizeMb`	`10`	单个 FTDC 存档文件的最大大小（以兆字为单位）。必须至少为 `1`，且小于 `directorySizeMb`。
`collectionPeriodMillis`	`1000`	`mongot` 将指标收集到 FTDC 中的时间间隔（以毫秒为单位）。必须至少为 `100`。

对于大多数部署，默认值都适合。仅在您有特定磁盘使用要求时才覆盖它们。要了解有关这些设置的更多信息，请参阅高级 FTDC 设置。

捕获 FTDC 以便获得支持

当您向 MongoDB 支持开启案例时，请发送受影响的 mongot 实例的整个 diagnostic.data/ 目录，包括问题发生期间。将目录打包并压缩。

对于 Linux tarball 部署，请将目录打包：

tar -czf mongot-ftdc-$(hostname)-$(date -u +%Y%m%dT%H%M%S).tar.gz <dataPath>/diagnostic.data/

对于容器部署，首先将目录复制到容器外：

docker cp <container>:/<dataPath>/diagnostic.data ./mongot-ftdc
tar -czf mongot-ftdc.tar.gz ./mongot-ftdc

对于 Kubernetes 操作符部署，请先将目录从舱中复制出来：

kubectl cp <namespace>/<pod>:<dataPath>/diagnostic.data ./mongot-ftdc
tar -czf mongot-ftdc.tar.gz ./mongot-ftdc

在支持工单中包含以下内容：

FTDC 包。
覆盖相同时间窗口的 mongot 日志文件，外加一小时的前缓冲。
主节点 (primary node in the replica set) 上的 mongod 日志文件涵盖了相同的时间窗口。
mongot 版本、mongod 版本和 Kubernetes Operator 版本（如适用）。
首次观察到问题的时间戳。
对部署中在该时间左右发生的变化的说明，例如配置、流量或升级。

FTDC 中的敏感数据

FTDC 包含运行指标和内部状态，而不是原始文档数据或用户查询字符串。FTDC 通常可以安全地发送给 MongoDB 支持团队，无需清理。如果您的合规政策更为严格，请先与安全团队一起查看所捕获的字段，然后再发送。

日志不是这样。日志行可能包括查询文本、文档标识符或其他应用程序级别数据，具体取决于日志级别。在限制性合规环境下发送日志文件之前，请先查看它们。