Assess a MongoDB installation and plan for migration to Azure DocumentDB

Carry out up-front planning tasks and make critical decisions before migrating your data to Azure DocumentDB. These decisions make your migration process run smoothly.

Prerequisites

• An existing MongoDB installation running MongoDB 4.4.2 or later. The assessment doesn't support earlier versions.

Assess the compatibility and readiness of your resources for migration

Before planning your migration, assess the state of your existing MongoDB resources to help plan for migration. Use the Azure DocumentDB Migration extension in VS Code to assess the compatibility and readiness of your workloads while planning the migration from MongoDB to Azure DocumentDB. The end-to-end assessment and find out the actions that you need to take to seamlessly run your workloads on Azure DocumentDB. The assessment report presents findings at the account, database, and collection levels, each marked as Critical, Warning, or Informational based on severity to aid prioritization. The report includes:

• Unsupported Features and Syntax: It flags unsupported MongoDB features, commands, query syntax, and index types, with usage frequency to prioritize fixes.

• Resource-Specific Recommendations: Each finding includes the affected resource name, actionable recommendations, and relevant technical details for remediation.

• Environment Overview: Summarizes key aspects of the source MongoDB environment—such as version, license, instance type, and stats for databases and collections.

• Compatibility and Platform Constraints: Details Azure DocumentDB-specific quotas, limits, and potential shard key incompatibilities for sharded workloads.

Run an Assessment

1. To get started, install the Azure DocumentDB Migration extension in VS Code. This will automatically install its prerequisite, the DocumentDB extension for Visual Studio Code.

2. Open DocumentDB from the Activity Bar.

3. Add the MongoDB server you want to assess for migration to the Document DB Connections list.

4. Expand the selected connection, then Right-click and choose Data Migration....

5. From the command palette, select Migration to Azure DocumentDB.

6. Then select Pre-Migration Assessment for Azure DocumentDB.

7. The assessment wizard guides you through three steps. In the Start Validation step, select Run Validation to verify credentials, prerequisites, and connectivity before proceeding.

   Important

   To perform an assessment, the connected MongoDB user must have the readAnyDatabase and clusterMonitor roles assigned on the source instance.

8. In the Fill in Assessment Details step, provide the necessary inputs:

   • Enter a title in the Assessment name field.
   • Select vCore from the Offering dropdown.
   • Provide the path to MongoDB logs.

   Tip

   While optional, specifying the logs path allows for more detailed findings at the collection level. If omitted, the tool relies on data from the serverStatus command, which only reflects feature usage since the last restart. Allow sufficient time to pass after the last server restart for an accurate workload assessment.

   • Provide the path to data assessment logs.

   Tip

   Though optional, supplying data assessment logs enhances workload insights. These logs are generated by scanning data and reading verbose logs. The data assessment runs independently as a CLI before initiating the migration assessment, and the resulting JSON is used here. Download the data assessment CLI here.

9. Select Start Assessment to begin the assessment process.

10. In the Get Your Report step, wait for the assessment to complete. The duration depends on the size of your source server.

11. Once the assessment is finished, select Download Report to retrieve the HTML report.

View Past Assessments

Reviewing previous assessments can be valuable. Use the View Past Assessments tab to access detailed historical reports. The assessment list includes all assessments initiated on the current machine for the selected connection.

FAQ

How do I proceed if the "Run Validation" step fails?

Check the error message displayed in the extension to determine the cause of the validation failure. Common issues include an inability to connect to the MongoDB endpoint or insufficient user privileges on the connected server.

To run an assessment, ensure that the connected MongoDB user has the readAnyDatabase and clusterMonitor roles assigned on the source instance.

Use grantRolesToUser to assign the necessary roles to the current user.

How can I view collection and database names in "Feature Compatibility" assessments?

The serverStatus command is used for feature compatibility assessments. However, this command doesn't provide database or collection names, which prevents the extension from reporting them.

For more detailed assessment results, rerun the assessment and specify the folder containing MongoDB logs in the Log Folder Path field.

How do I enable profiling to detect cross-collection pipeline dependencies?

Profiling is optional. You can skip this step if you already know your workload's cross-collection pipeline dependencies.

The script requires a source deployment that supports database profiling. MongoDB Atlas M0 (Free) and Flex clusters don't support setProfilingLevel. For deployments that don't support profiling, skip this optional step and identify dependencies separately by reviewing your application's aggregation pipelines. For tier-specific restrictions, see Atlas unsupported commands.

Before enabling profiling, record each database's existing settings with db.getProfilingStatus(), including the profiling level (was), slowms, sampleRate, and any filter. Check the size of each database's capped system.profile collection with db.getCollection("system.profile").stats() if it exists. Ensure it has enough capacity to retain the representative workload's pipeline entries until the assessment reads them. If you need to create or resize the collection, follow Manage the database profiler.

Profiling can affect performance and record sensitive query data. The pipeline filter also affects slow-query diagnostic logging: slowms and sampleRate are ignored while the filter is active, and operations that don't match the filter aren't logged as usual slow queries. Plan the capture period with the people responsible for monitoring your source deployment.

Before running the assessment, run the following script in mongosh on each source MongoDB shard primary, not on the mongos router. Use an account with permission to configure database profiling. The script enables profiling for commands that include an aggregation pipeline in every database except admin, local, and config.

// Run on each shard primary
const excluded = new Set(["admin", "local", "config"]);

db.adminCommand({ listDatabases: 1 }).databases
  .map(d => d.name)
  .filter(name => !excluded.has(name))
  .forEach(name => {
    db.getSiblingDB(name).setProfilingLevel(1, {
      filter: { "command.pipeline": { $exists: true } }
    });
    print(`Profiling enabled for ${name}`);
  });

Run a representative application workload with the primary read preference while profiling is enabled, and then run the assessment promptly. Profiling only shard primaries doesn't capture pipelines executed on secondary members, including reads routed there by secondary, secondaryPreferred, or nearest read preferences.

The assessment automatically detects cross-collection pipeline dependencies from entries still retained in system.profile. Pipelines that don't run during the capture period aren't captured, and the capped collection overwrites older entries when full. Verify that the capture period's entries remain available before running the assessment. You don't need to generate or provide separate data assessment logs for this detection.

After the assessment completes, restore each database's recorded profiling level and options with db.setProfilingLevel(). If the database previously had no filter, explicitly pass filter: "unset" when restoring its settings. Lowering the profiling level alone doesn't remove the filter.

How do I configure my source server firewall to prevent connectivity issues?

Ensure that the source MongoDB instance allows incoming connections from your machine.

How many assessments can I run concurrently?

There's no limit to the number of assessments you can run at the same time. However, running multiple assessments in parallel strain the compute resources on both your machine and the source server, potentially affecting performance.

What information is included in an assessment report?

The report begins with key details about the assessment, including a summary of the source MongoDB environment. This section covers the source MongoDB version, license type, and instance type. It also lists the assessed databases and collections, along with their assessment summaries and migration readiness.

Findings are categorized into Critical, Warning, and Informational, helping you prioritize them based on importance.

The assessment includes checks for:

What type of logs does the extension generate?

The extension records errors, warnings, and other diagnostic logs in the default log directory:

• Windows - C:\Users\<username>\.dmamongo\logs\
• Linux - ~/.dmamongo/logs
• macOS - /Users/<username>/.dmamongo/logs

Capacity planning

Cluster Tier

Begin with a cluster tier that aligns with your source database configurations. Conduct load and performance tests to determine the optimal balance between cost and performance.

Storage Tier

Ensure your target account is provisioned with adequate storage to meet your data requirements during and after migration. Start by migrating a small dataset to assess storage consumption, then scale the estimate based on the total data size to determine the necessary storage allocation. Reserve extra space to accommodate incoming data and future growth.

Next step