x-ray

This project aims to create tools for MongoDB analysis and diagnosis. So far 3 modules are being built:

• Health check module.
• Log analysis module.
• getMongoData visualization module (Under construction).

1 Compatibility Matrix

1.1 Health Check

Older versions are not tested.

1.2 Log Analysis

Log analysis requires JSON format logs, which is supported since 4.4.

1.3 getMongoData Analysis

Analyze & visualize the getMongoData.js output.

1.4 FTDC Analysis

Run a basic FTDC analysis.

2 How to Install

2.1 PyPi

2.1.1 Install with Pip

The easiest and recommended way to install x-ray is to use pip:

pip install mongo-x-ray

2.1.2 Build from Source

git clone https://github.com/mongodb-ps/ce-mongo-x-ray
cd x-ray
pip install .

2.2 PyInstaller

2.2.1 Prebuilt Binaries

Currently the prebuilt binaries are available on 3 platforms:

• Ubuntu 22.04 (AMD64)
• MacOS 14 (ARM64)
• Windows 2022 (AMD64)

Download them from Releases.

2.2.2 Build from Source

x-ray is tested on Python 3.9.22. On MacOS or Linux distributions, you can use the make command to build the binary:

git clone https://github.com/mongodb-ps/ce-mongo-x-ray
cd x-ray
make deps # if it's the first time you build the project
make # equal to `make build`

There are other make targets. Use make help to find out.

For Windows users, if make command is not available. You can use Python commands to build the binary:

python.exe -m venv .venv
.venv\Scripts\python.exe -m pip install --upgrade pip
.venv\Scripts\python.exe -m pip install -e ".[dev]"
.venv\Scripts\python.exe -m PyInstaller --onefile `
  --name x-ray `
  --add-data="templates;templates" `
  --add-data="libs;libs" `
  --icon="misc/x-ray.ico" `
  --hidden-import=openai `
  x-ray

2.3 For Developers

For developers, use make deps to prepare venv and dependencies

make deps

Or

python3 -m venv .venv
python3 -m pip install --upgrade pip
python3 -m pip install -e ".[dev]"

3 Using the Tool

x-ray [-h] [-q] [-c CONFIG] {healthcheck,hc,log,gmd,ftdc}

Besides, you can use environment variables to control some behaviors:

• ENV=development For developing. It will change the following behaviors:
  • Formatted the output JSON for for easier reading.
  • The output will not create a new folder for each run but overwrite the same files.
• LOG_LEVEL: Can be DEBUG, ERROR or INFO (default).

3.1 Health Check Component

3.1.1 Examples

./x-ray healthcheck localhost:27017 # Scan the cluster with default settings.
./x-ray hc localhost:27017 --output ./output/ # Specify output folder.
./x-ray hc localhost:27017 --config ./config.json # Use your own configuration.

3.1.2 Full Arguments

x-ray healthcheck [-h] [-s CHECKSET] [-o OUTPUT] [-f {markdown,html,pdf}] [uri]

For security reasons you may not want to include credentials in the command. There are 2 options:

• If the URI is not provided, user will be asked to input one.
• If URI is provided but not username/password, user will also be asked to input them.

3.1.3 More Info

Refer to the wiki for more details.

• Customize the thresholds
• Database permissions
• Output
• Customize the output

3.2 Log Analysis Component

3.2.1 Examples

# Full analysis
./x-ray log mongodb.log
# Time range filter
./x-ray log /var/log/mongodb/ 2026-07-20T08:00:00Z 2026-07-20T10:00:00Z
# For large logs, analyze a random 10% logs
./x-ray log -r 0.1 mongodb.log
# Discover log folders recursively
./x-ray log --discover /var/log/

3.2.2 Full Arguments

x-ray log [-h] [-s CHECKSET] [-o OUTPUT] [-f {markdown,html,pdf}] [-r RATE] [--top TOP] [--discover] log_file [start_time] [end_time]

3.3 getMongoData Analysis Component

3.3.1 Examples

# getMongoData output for a sharded cluster
x-ray gmd misc/getMongoData-sh.json
# getMongoData output for a replica set
x-ray gmd misc/getMongoData-rs.json

3.3.2 Full Arguments

x-ray gmd [-h] [-s CHECKSET] [-o OUTPUT] [-f {markdown,html,pdf}] gmd_file

3.4 FTDC Analysis Component

The FTDC baseline analysis reports its capture timespan and effective sample rate, then groups metrics into Workload, Read/Write Operations and Latencies, and Performance sections. It includes operation rates and latencies, host memory and CPU utilization, WiredTiger cache utilization, queue depth for each block device, and free-space and utilization charts for every reported mount point. Each metric shows its peak, average, unit, and a chart saved under the report output's charts directory. Start and end are inclusive UTC ISO-8601 timestamps. When omitted, the first and last data points in the archive are used.

x-ray ftdc /var/lib/mongo/diagnostic.data
x-ray ftdc /var/lib/mongo/diagnostic.data 2026-06-17T08:00:00Z 2026-06-17T10:00:00Z
# Discover FTDC folders recursively
x-ray ftdc --discover /data/

x-ray ftdc [-h] [-s CHECKSET] [-o OUTPUT] [-f {markdown,html,pdf}] [-r RATE] [--svg] [--discover] ftdc_path [start_time] [end_time]

"BaselineAnalysisItem": {
  "chart_width": 450,
  "chart_height": 150
}

The fallback dimensions are defined in ftdc_analysis/charts.py. Vertical grid lines are spaced every 100 pixels and horizontal grid lines every 50 pixels. Workload and operation/latency charts use lines. Performance charts use bars. Member-state charts are always 450×50 pixel bars.

3.4.1 AI Analysis (Optional)

FTDC reports can include AI-generated summaries for each section (Workload, Ops and Latencies, Performance). The analysis appears as a brief 2-3 sentence assessment at the end of each section, flagging potential issues or confirming normal operation.

Configuration — set the following environment variables:

If OPENAI_API_KEY is not set, AI analysis is silently skipped.

Example .env file:

OPENAI_API_KEY="sk-..."
OPENAI_BASE_URL="https://api.deepseek.com"
AI_MODEL="deepseek-v4-pro"

Or export directly in the shell:

export OPENAI_API_KEY="sk-..."
x-ray ftdc /var/lib/mongo/diagnostic.data