Atlas Diagnostics Expert

Parent: MongoDB Expert Knowledge · researched 2026-05-25· 24 sources · 10 concepts · skill atlas-diagnostics-expert

- SKIP (description-overflow seed, Glean 1000-char cap): WiredTiger storage-engine root-cause internals — cache-fill/eviction/checkpoint/MVCC mechanics behind a live perf symptom → mongodb-expert (ref

Routing detail

SKIP (description-overflow seed, Glean 1000-char cap): WiredTiger storage-engine root-cause internals - cache-fill/eviction/checkpoint/MVCC mechanics behind a live perf symptom → mongodb-expert (references/mongodb-wiredtiger-internals.md) [source]

When to use this skill

Atlas diagnostics and triage workflows [source]
ts-diag usage and adjacent internal support tools [source]
FTDC, log, metrics, alert, and explain-plan investigation choices [source]
KB-backed Atlas troubleshooting guidance [source]
Designing or reviewing new Atlas diagnostic tooling [source]

When NOT to use this skill

Data-plane query/index/schema design not live perf troubleshooting - use mongodb-expert [source]
Atlas platform config/architecture (control plane, tiers, networking, security posture) - use mongodb-atlas-expert [source]
Backups, DR, migration, or security architecture - use mongodb-operations-expert [source]
KB article lookup - use misc-catch-all (references/mongodb-kb.md) [source]
Cloning/installing/running 10gen repos - use misc-catch-all (references/10gen.md) [source]

Skill guidance

Prefer documented Atlas diagnostic workflow before improvising. [source]
Call out what directly documented vs inferred when evidence thin. [source]
Use misc-catch-all (references/mongodb-kb.md) alongside when need article-level troubleshooting playbooks or customer-shareable links. [source]

Sub-skill routing table

Consolidates 8 diagnostics/performance sub-skills as on-demand references - Read listed references/…md file before answering deep questions. [source]

Public Atlas docs

Atlas metrics: <https://www.mongodb.com/docs/atlas/review-available-metrics/> [source]
Atlas alerts: <https://www.mongodb.com/docs/atlas/configure-alerts/> [source]
Performance Advisor: <https://www.mongodb.com/docs/atlas/performance-advisor/> [source]

Core principle

Move from curated summary to raw evidence: [source]
Start with fastest curated view (ts-diag, Atlas UI summaries, Performance Advisor, alerts, metrics) [source]
Gather focused artifacts (logs, FTDC, explain plans, profiler samples) [source]
Use specialized analyzers (alexandria, t2, SearchPlanIQ, mtools, Mongolyser) when first-pass insufficient [source]
Package findings into repeatable escalation record using Atlas Diagnostic Checklist and Template [source]

What the internal docs establish directly

ts-diag is single-pane-of-glass first stop for Atlas project and cluster triage. [source]
Atlas UI investigation still required for disk usage, IOPS, node state, query targeting, scan-and-order, oplog window, upgrade/election context. [source]
Logs and FTDC are core raw artifacts behind deeper troubleshooting. [source]

ts-diag

Purpose: Internal Atlas Diagnostic Snapshot service for Atlas project and cluster triage. Presents curated project/cluster summaries and Quick and Easy Diagnostics. [source]
Access/install/run: [source]
Web: <https://ts-diag.cloud-ops.prod.corp.mongodb.com/> or go/tsdiag [source]
CLI: ts-diag (requires Atlas CLI profiles and employee Okta auth; VPN / Cloudflare WARP for CLI auth) [source]
Dev: Go 1.24.2+ and GOPRIVATE=github.com/10gen/* [source]
CLI subcommands: snapshot, api, atlasinfo, dbaccess, downloadlogs, event, instancehardware, lastping, logcollection, maint, metrics, networkinfo, plans, searchnodes, web, whoami [source]
Inputs: Atlas case number, Atlas CLI profile, org/project/cluster identifiers, Atlas Admin API paths [source]
Outputs: Project snapshot, cluster snapshot, quick diagnostics, links to logs/FTDC/Atlas UI [source]
Quick diagnostics are triage accelerator, not replacement for logs, FTDC, or Atlas UI validation [source]
Access is RBAC-gated internally [source]

Atlas UI + Atlas Diagnostic Checklist

Purpose: Structured manual validation before escalation. [source]
Inputs: Project ID, node URI, cluster/node pages, logs/FTDC download links, observed symptoms and timestamps [source]
Outputs: Escalation-ready summary with cluster size, node status, storage, IOPS, CPU, oplog, query-targeting, restart attempts [source]
Disk usage and write-blocking risk [source]
Disk IOPS saturation [source]
Connection pressure [source]
Whether writes still accepted [source]
Node down / recovering / upgrade state [source]
Query targeting and scan-and-order behavior [source]
Oplog window / fall-off risk [source]
CPU pressure and OOM indicators [source]
Thresholds: Query targeting >100 red flag; >1000 urgent. Scan-and-order stay near 0; >25 warrants investigation. [source]
Cautions: Some node downtime during upgrades expected. Sanitize customer data before sharing log excerpts. [source]

Alexandria

Purpose: Fast FTDC analysis on Prometheus-style query model; known-issue detection via rules plus ad hoc FTDC querying. [source]
GitHub releases for binaries, or Kanopy-hosted web app [source]
Build: go build ./... or make [source]
CLI: alexandria diagnostic.data/ or alexandria -query '...' diagnostic.data/ [source]
Inputs: FTDC directories, FTDC tar archives, Prometheus-like query expressions, optional tags/rules [source]
Outputs: Markdown findings, JSON output, CSV-style query output, rule hits and summaries [source]
What it checks: Memory issues, storage/disk bottlenecks, replication lag/flow control/majority issues, network stall patterns, stuck transactions, WiredTiger contention/dirty rollback patterns [source]
Cautions: Some rules are MongoDB-version-specific and pass if metrics absent. Strongest for FTDC-driven diagnosis. [source]

t2

Purpose: FTDC and metric time-series inspection at lower level than first-pass summary tools. [source]
Access: Desktop application from GitHub (TSE Toolbelt) [source]
What it checks: Trending and timing relationships in FTDC data; follow-up after ts-diag or checklist-based suspicion [source]
Evidence note: Corpus docs light - use as specialized FTDC lens. [source]

mtools

Purpose: Log analysis and local repro helpers. [source]
Install: pip3 install --user 'mtools[all]'; workaround: pip install mtools[all] --user --ignore-installed six [source]
Inputs: mongod / mongos logs, local repro scenarios for mlaunch [source]
Outputs: Log summaries, filtered log views, query plots and log visualizations [source]

SearchPlanIQ (ts-search-explain-helper)

Purpose: Atlas Search and Vector Search explain-plan analysis with visualization and AI-assisted interpretation. [source]
uv pip install -e . [source]
uv run python -m searchplaniq.app [source]
Open http://localhost:5001 [source]
Inputs: $search, $vectorSearch, and hybrid explain plans [source]
Outputs: Flame graphs, treemaps, Sankey diagrams, execution summaries, markdown reports, extracted JSON [source]
What it checks: Search-stage bottlenecks, segment timing and selectivity, explain-plan shape and probable hot spots [source]
Cautions: Includes LLM-assisted analysis - validate hypotheses against underlying explain data. README calls out security and PII handling guidance as required reading. [source]

Mongolyser

Purpose: General MongoDB performance and health analysis desktop app. [source]
Install/run: Download executables from GitHub releases, or npm i && npm run electron:start [source]
Inputs: Profiler data, logs, oplog/write-load patterns, index and sharding state [source]
What it checks: Query profiling, performance assessment, log analysis, query pattern analysis, write-load/oplog behavior, connection analysis, index analysis, sharding and chunk analysis, cache visualization [source]
Evidence note: README-level docs - prefer more specialized tools when narrower workflow already established. [source]

ts-ftdc-requestor

Purpose: FTDC retrieval and storage service for Atlas-to-S3 workflows. Primarily artifact-acquisition, not analyzer. [source]
Evidence note: Lightly documented - treat as infrastructure around FTDC workflows. [source]

devprod-mcp-router

Purpose: Unified MCP gateway/entrypoint to internal debugging backends (Evergreen, Git, Jira, Confluence, Backstage, Build Baron). [source]
Install/run: Install devprod-mcp-proxy from gateway download page or via go install; connect AI clients over stdio to gateway URL [source]
Note: Not Atlas diagnostic engine - makes adjacent CI, repo, wiki, and infra debugging surfaces easier from AI tooling. [source]

Cluster health / outage / node-down

Start in ts-diag for project and cluster snapshot. [source]
Validate node state, activity feed, and metrics in Atlas UI. [source]
Use Atlas Diagnostic Checklist to confirm storage, IOPS, oplog, CPU, and whether writes still accepted. [source]
Pull logs and FTDC if symptom not immediately explained. [source]
Escalate with checklist/template if HELP engagement criteria met. [source]

Query / index / slow-operation issues

Start with Performance Advisor and Namespace / profiler views. [source]
Check query targeting, docs scanned, docs returned, sample query shapes. [source]
For Atlas Search / Vector Search explains, use SearchPlanIQ. [source]
Use KB references for recurrent patterns and customer-shareable guidance. [source]

Memory / storage / cache / replication issues

Review Atlas metrics for memory, cache, disk usage, latency, and queue depth. [source]
Use ts-diag QED output as hinting layer. [source]
Pull FTDC and analyze with Alexandria and/or t2. [source]
Use oplog and storage KB articles when symptoms match those playbooks. [source]

Log-heavy incidents

Acquire logs from Atlas / ts-diag. [source]
Use mtools for structured filtering and visualization. [source]
Use Mongolyser when broader multi-signal interactive workflow helpful. [source]

Atlas metrics quick reference

High cache usage → working set or write pressure [source]
High disk latency / queue depth → storage bottleneck [source]
High connections → tier limits or pooling problem [source]
High execution time → query/index investigation [source]
Atlas alerting RBAC-gated at org/project scope; severity levels: Critical, Error, Warning, Info. Alert state is diagnostic evidence, not just notification plumbing. [source]
Performance Advisor works from slow-query evidence and suggests indexes based on query shape. Index recommendations still need read-vs-write tradeoff review before applying. [source]

KB-guided troubleshooting posture

Use KB for repeatable symptom-to-playbook mapping, especially when need customer-safe article or want to confirm known Atlas issue shape. Check visibility before sharing links externally. [source]
Useful KB categories for Atlas diagnostics: [source]
Connection and TLS issues [source]
Oplog sizing / falling off the oplog [source]
Disk-usage interpretation [source]
Search/vector alert interpretation [source]
Network latency investigations [source]

Standards for building new Atlas diagnostic tooling

Prefer public Atlas Admin APIs first; use private/internal only when capability not exposed publicly. [source]
Decide consumer model up front: internal UI, CLI/programmatic tool, or agent-facing system. One API shape not fit every consumer. [source]
Use supported auth patterns: service accounts / OAuth, Digest for legacy Admin APIs, or approved internal auth flows. [source]
Make RBAC explicit - role annotations required, not implied. [source]
Add intentional rate limiting for fan-out or expensive diagnostic endpoints. [source]
Keep telemetry privacy-safe - avoid logging request/response bodies due to PII risk. [source]
Favor versioned and better-governed public APIs when long-term tool stability matters. [source]
Treat logs, FTDC, sample queries, and explains as potentially sensitive customer data; minimize storage and exposure. [source]
Preserve TS operational pattern: summary surface first, raw artifacts second, specialized analyzers third. [source]

Directly documented

ts-diag purpose, access paths, and CLI/API orientation [source]
Atlas Diagnostic Checklist thresholds and escalation posture [source]
Alexandria FTDC workflow and rule-driven analysis [source]
mtools install guidance [source]
SearchPlanIQ startup flow and explain-analysis focus [source]
Mongolyser feature list and Electron startup flow [source]
Atlas metrics / alerts / Performance Advisor high-level behavior [source]
Internal API/auth/RBAC/privacy constraints from MMS API Landscape [source]

Lightly documented or partly inferred

Exact t2 operating details [source]
atlas-tools script-by-script behavior [source]
ts-ftdc-requestor runtime usage details [source]
Whether given internal tool currently recommended, maintained, or only historically available [source]
When extending this context, read tool's current README or operator guide before making prescriptive claims. [source]
[source]

Cross-hub map — where every MongoDB topic lives

All MongoDB knowledge split across four hubs (plus misc-catch-all for KB-article lookups via references/mongodb-kb.md and repo install/run via references/10gen.md). If task's deep material not in this hub's Sub-skill routing table, it is reference file under sibling hub - activate that hub or Read its references/<name>.md directly. [source]
High-overlap routing notes: [source]
Performance symptom triage (high CPU, cache pressure, slow queries, latency spikes) starts at atlas-diagnostics-expert, but storage-engine root-cause internals (WiredTiger cache fill / dirty trigger / eviction threads / reconciliation / checkpoints) owned by mongodb-expert - cross-load mongodb-expert/references/mongodb-wiredtiger-internals.md (and mongodb-wiredtiger.md) for depth. [source]
Migration symptoms vs migration execution: live-cluster diagnosis → atlas-diagnostics-expert; migration/mongosync runbook → mongodb-operations-expert. [source]
Atlas Search/Vector query syntax & index design → mongodb-atlas-expert; slowness triage of running search → atlas-diagnostics-expert. [source]
Host-OS memory tuning for self-managed mongod host (transparent hugepages disable - THP/defrag=never, vm.swappiness=1, swap sizing, kernel OOM killer and oom_score_adj, NUMA placement / interleave for WiredTiger cache, vm.max_map_count) lives under the devops-infra router's devops-linux-internals sub-hub → cross-load devops-linux-internals/references/linux-memory-numa.md. This skill owns MongoDB-side cache-pressure symptom triage; that reference owns Linux memory/NUMA mechanisms and sysctls beneath it. [source]

Children

ts-diag and Diagnostic Workflows (frontier)
FTDC and Log Tooling (frontier)
KB-Backed Troubleshooting (frontier)
Diagnostic Tool Design (frontier)
Atlas Triage Workflows (frontier)

Frontier under this node: Atlas Triage Workflows, Diagnostic Tool Design, FTDC and Log Tooling, KB-Backed Troubleshooting, ts-diag and Diagnostic Workflows

← the whole tree · 3D view· how to read this page