For AI agents: a documentation index is available at https://www.mongodb.com/docs/llms.txt — markdown versions of all pages are available by appending .md to any URL path.
Docs Menu

Integrate with Prometheus

Prometheus collects metrics from configured targets at given intervals, evaluates rule expressions, displays the results, and can trigger alerts when it observes specific conditions.

Our integration allows you to configure Atlas to send metric data about your deployment to your Prometheus instance.

Atlas for Government does not support the Prometheus integration.

  • Prometheus integration is available only on M10+ clusters.

  • Have a working Prometheus instance. To set up a working instance, see their Installation Guide.

  • Add the IP of the device hosting your Prometheus instance to the IP Access List.

    Note

    If you add to the IP Access List any IPv4 /0 CIDR, such as 0.0.0.0/0 which allows cluster access from anywhere on the public Internet, Atlas disables the Prometheus integration.

    If a /0 CIDR is already on the IP Access List, Atlas stops you from configuring the Prometheus integration.

    If you add to a project access list any IPv4 /0 CIDR, such as 0.0.0.0/0 or 10.0.0.0/0, Atlas sends an alert email to all users directly granted a role to the project, or indirectly granted a role through team membership (if the team is granted a role to the project).

  • (Optional) Use Grafana to visualize your Prometheus metrics.

To configure an Atlas integration with Prometheus:

1
  1. If it's not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.

  2. If it's not already displayed, select your desired project from the Projects menu in the navigation bar.

  3. In the sidebar, click the icon next to Project Overview.

The Project Settings page displays.

2

Click the Integrations tab.

The Project Integrations page displays.

3
4

Prometheus authentication credentials are specifically designed for use with the Prometheus integration in MongoDB Atlas. Atlas uses these credentials to only access the Prometheus discovery endpoint and scrape Prometheus metrics from Atlas nodes. They are strictly limited to these functions and do not have any additional permissions or capabilities beyond accessing and collecting monitoring data.

Important

Copy your username and password in a secure location. You can't access the password after you leave this screen.

5
Discovery Method
Description

This method requires Prometheus v2.28 and later. It automatically generates the scrape_config part of your configuration file to discover targets over an HTTP endpoint.

  1. Add the IP of the device hosting your Prometheus instance to the IP Access List. This grants Prometheus the network access to scrape metrics from your Atlas clusters. Ensure that 0.0.0.0/0 isn't on the list. Having this entry disables the integration.

  2. In the Choose Discovery API Target Type step in the Atlas UI, do one of the following tasks:

    • Select Public Internet.

    • Select Private IP for Peering.

    • Select Private Endpoint, and then select or create the endpoints.

  3. (Optional) To enable sending custom resource tags to Prometheus, toggle Send Resource Tags to On.

    You must opt-in to this feature to send custom resource tags to Prometheus metrics. When you enable this feature, Atlas sends the resource tags as labels on Prometheus metrics. This allows you to filter, organize, and define monitoring logic based on your custom tags. To learn more about resource tags, see Resource Tags.

  4. Insert the following snippet into the scrape_configs section of your Prometheus.yml file and update it with values for your Prometheus integration.

    For private endpoints, the configuration is autogenerated based on the selected endpoints.

    - job_name: "<insert-job-name>"
    scrape_interval: 10s
    metrics_path: /metrics
    scheme: https
    basic_auth:
    username: <insert-prometheus-user-id>
    password: <insert-password>
    http_sd_configs:
    - url: <url-of-the-service-discovery-configuration>
    refresh_interval: 60s
    basic_auth:
    username: <insert-prometheus-user-id>
    password: <insert-password>

This method allows Prometheus to read YAML or JSON documents to configure the targets to scrape from. You are responsible for providing the targets by making a request to the Discovery API and storing its results in a targets.json file.

To make the request, substitute the placeholder text in one of the following tabs or create your own script in another language.

curl --header 'Accept: application/json'
# Sets the `Authorization` header on every scrape request with the
# username and password from the previous step.
--user <username>:<password>
# The URL that Prometheus fetches the targets from.
# Replace the <group-id> with the project ID of your Atlas instance.
--request GET "https://cloud.mongodb.com/prometheus/v1.0/groups/<group_id>/discovery"

To learn more about the Discovery API, see Return the Latest Targets for Prometheus.

If you add to a project access list any IPv4 /0 CIDR, such as 0.0.0.0/0 or 10.0.0.0/0, Atlas sends an alert email to all users directly granted a role to the project, or indirectly granted a role through team membership (if the team is granted a role to the project).

Warning

Adding the /0 CIDR, such as 0.0.0.0/0, allows access from anywhere. This configuration can expose your deployment to unauthorized access, data exfiltration, and other malicious activity. Restrict access to trusted IP addresses or CIDR ranges whenever possible, and use strong credentials for all database users when allowing access from the public Internet.

6
7
  1. Copy the generated snippet into the scrape_configs section of your configuration file and substitute the placeholder text.

    For an example of the configuration file in either method, see Example Configurations.

  2. Restart your Prometheus instance.

  3. In your Prometheus instance, click Status in the top navigation bar, and click Targets to see the metrics of your deployment.

The following shows examples of the configuration file when you use the HTTP SD or File Service Discovery method.

The configuration file in both methods contains the following fields:

Field
Description

scrape_interval

Time that indicates how frequently to scrape targets. This setting supports a minimum time of 10s.

job_name

Human-readable label assigned to scraped metrics.

metrics_path

HTTP resource path that indicates where to fetch metrics from targets.

scheme

Protocol scheme that you want to configure for requests.

basic_auth

Authorization header to use on every scrape request.

The HTTP Service Discovery method also contains the http_sd_configs field with the following sub-fields:

Field
Description

url

URL from which Prometheus fetches the targets.

refresh_interval

Time that indicates when to re-query the endpoint.

basic_auth

Credentials to use for authenticating to the API server.

global:
scrape_interval: 15s
scrape_configs:
- job_name: "Cloud-Testing-mongo-metrics"
scrape_interval: 10s
metrics_path: /metrics
scheme : https
basic_auth:
username: prom_user_618d48e05277a606ed2496fe
password: fSIMUngfTmOTVEB4
http_sd_configs:
- url: https://cloud.mongodb.com/prometheus/v1.0/groups/618d48e05277a606ed2496fe/discovery
refresh_interval: 60s
basic_auth:
username: prom_user_618d48e05277a606ed2496fe
password: fSIMUngfTmOTVEB4

The HTTP Service Discovery method for AWS PrivateLink also contains the url field with the following variables that you should define with your values:

Note

Each private endpoint handles metric scraping for a single region. For multi-region clusters, you must specify different scrape configurations for the Prometheus instances in each regions.

Field
Description

group_id

Unique string that identifies the Atlas project. For example, 5f4a8b9c1d2e3f4a5b6c7d8e.

endpoint_id

AWS PrivateLink Endpoint ID (format: vpce-xxxxxxxxxxxxx). For example, vpce-0a1b2c3d4e5f6g7h8. To find your endpoint ID, do one of the following steps:

  • In the Atlas UI, go to the Network Access tab, Private Endpoint section, and copy the Endpoint ID value.

  • In the AWS Console, go to the VPC service, Endpoints section, and copy the VPC Endpoint ID value for your Atlas endpoint.

global:
scrape_interval: 10s
evaluation_interval: 10s
scrape_configs:
- job_name: "Cloud-Testing-mongo-metrics"
scrape_interval: 10s
scrape_timeout: 10s
metrics_path: /metrics
scheme : https
basic_auth:
username: prom_user_618d48e05277a606ed2496fe
password: fSIMUngfTmOTVEB4
http_sd_configs:
- url: https://cloud.mongodb.com/prometheus/v1.0/groups/{group_id}/discovery?targetScheme=PRIVATE_ENDPOINT&endpointId={endpoint_id}
refresh_interval: 60s
basic_auth:
username: prom_user_618d48e05277a606ed2496fe
password: fSIMUngfTmOTVEB4
relabel_configs:
- source_labels: [__metrics_path__]
target_label: __metrics_path__
- source_labels: [__instance__]
target_label: instance

The File Service Discovery method also contains the file_sd_configs field with the following sub-field:

Field
Description

files

List that contains the files from which to extract the metrics scraping targets.

global:
scrape_interval: 15s
scrape_configs:
- job_name: "Cloud-Testing-mongo-metrics"
scrape_interval: 10s
metrics_path: /metrics
scheme : https
basic_auth:
username: prom_user_618d48e05277a606ed2496fe
password: fSIMUngfTmOTVEB4
file_sd_configs:
- files:
- /usr/local/etc/targets.json

To import a sample Grafana dashboard:

1

In the Grafana UI, click the button, and then click Import.

2
3

To learn more about importing Grafana dashboards, see the Grafana documentation.

Warning

The supplied Grafana dashboards use the PromQL rate() function for some panels. You should have at least 4 data points for the lowest granularity you want to achieve. For example, if you want to visualize metrics at 1-minute granularity, set your Prometheus scrape interval to 15 seconds or less for safe implementation.

For more information, see the Prometheus rate() function documentation and the Prometheus documentation on histograms.

Alternatively, you can replace the $interval variable in the dashboard templates with $__rate_interval. This automatically resolves to an appropriate interval based on your scrape interval. For example, on a dashboard with a 1-minute step and a 10-second scrape interval, $__rate_interval resolves to 1 minute and 10 seconds. To learn more, see the Grafana blog post on rate intervals.

Note

For Managed Grafana Users

The Atlas Prometheus integration provides over 3,000 metrics available to scrape. If you have spend requirements and the supplied dashboards satisfy your monitoring needs, you can filter to scrape only the specific metrics used by these dashboards.

The dashboards use the following distinct metrics:

  • hardware_disk_metrics_disk_space_free_bytes

  • hardware_disk_metrics_disk_space_used_bytes

  • hardware_disk_metrics_read_count

  • hardware_disk_metrics_read_throughput_bytes_per_second

  • hardware_disk_metrics_read_time_milliseconds

  • hardware_disk_metrics_total_time_milliseconds

  • hardware_disk_metrics_weighted_time_io_milliseconds

  • hardware_disk_metrics_write_count

  • hardware_disk_metrics_write_time_milliseconds

  • hardware_platform_num_logical_cpus

  • hardware_process_cpu_children_kernel_milliseconds

  • hardware_process_cpu_children_user_milliseconds

  • hardware_process_cpu_kernel_milliseconds

  • hardware_process_cpu_user_milliseconds

  • hardware_system_cpu_guest_milliseconds

  • hardware_system_cpu_io_wait_milliseconds

  • hardware_system_cpu_irq_milliseconds

  • hardware_system_cpu_kernel_milliseconds

  • hardware_system_cpu_nice_milliseconds

  • hardware_system_cpu_soft_irq_milliseconds

  • hardware_system_cpu_steal_milliseconds

  • hardware_system_cpu_user_milliseconds

  • hardware_system_memory_buffers_kilobytes

  • hardware_system_memory_cached_kilobytes

  • hardware_system_memory_mem_available_kilobytes

  • hardware_system_memory_mem_free_kilobytes

  • hardware_system_memory_mem_total_kilobytes

  • hardware_system_memory_shared_mem_kilobytes

  • hardware_system_memory_swap_free_kilobytes

  • hardware_system_memory_swap_total_kilobytes

  • hardware_system_network_eth0_bytes_in_bytes

  • hardware_system_network_eth0_bytes_out_bytes

  • hardware_system_vm_page_swap_in

  • hardware_system_vm_page_swap_out

  • mongodb_asserts_msg

  • mongodb_asserts_regular

  • mongodb_asserts_user

  • mongodb_asserts_warning

  • mongodb_catalogStats_collections

  • mongodb_catalogStats_views

  • mongodb_connections_current

  • mongodb_extra_info_page_faults

  • mongodb_globalLock_currentQueue_readers

  • mongodb_globalLock_currentQueue_total

  • mongodb_globalLock_currentQueue_writers

  • mongodb_indexStats_count

  • mongodb_info

  • mongodb_mem_resident

  • mongodb_mem_virtual

  • mongodb_metrics_cursor_open_total

  • mongodb_metrics_cursor_timedOut

  • mongodb_metrics_document_deleted

  • mongodb_metrics_document_inserted

  • mongodb_metrics_document_returned

  • mongodb_metrics_document_updated

  • mongodb_metrics_operation_scanAndOrder

  • mongodb_metrics_queryExecutor_scanned

  • mongodb_metrics_queryExecutor_scannedObjects

  • mongodb_metrics_query_sort_spillToDisk

  • mongodb_metrics_ttl_deletedDocuments

  • mongodb_network_bytesIn

  • mongodb_network_bytesOut

  • mongodb_network_numRequests

  • mongodb_opLatencies_commands_latency

  • mongodb_opLatencies_commands_ops

  • mongodb_opLatencies_reads_latency

  • mongodb_opLatencies_reads_ops

  • mongodb_opLatencies_writes_latency

  • mongodb_opLatencies_writes_ops

  • mongodb_opcounters_command

  • mongodb_opcounters_delete

  • mongodb_opcounters_getmore

  • mongodb_opcounters_insert

  • mongodb_opcounters_query

  • mongodb_opcounters_update

  • mongodb_oplog_earliestOptime

  • mongodb_oplog_latestOptime

  • mongodb_queues_execution_read_available

  • mongodb_queues_execution_write_available

  • mongodb_repl_secondary

  • mongodb_up

  • mongodb_uptime

  • mongodb_wiredTiger_cache_bytes_currently_in_the_cache

  • mongodb_wiredTiger_cache_bytes_read_into_cache

  • mongodb_wiredTiger_cache_bytes_written_from_cache

  • mongodb_wiredTiger_cache_maximum_bytes_configured

  • mongodb_wiredTiger_cache_tracked_dirty_bytes_in_the_cache

The following metrics are available when you use the Prometheus integration with your Atlas cluster:

Note

On an Atlas Infinite cluster, the available metrics describe the cluster's compute nodes rather than the storage layer, and some listed metrics aren't available. For the metrics available on Atlas Infinite, see Review Available Metrics.

Each MongoDB metric contains the following labels:

Note

In addition to the labels listed below, Atlas sends user-defined resource tags to Prometheus as labels. This is an opt-in feature that you enable through the UI or the API. See the Procedure section in this document to learn more about each procedure.

Label
Description

availability_zone

AWS availability zone ID, Google Cloud fully-qualified name for a zone, or Azure zone number.

Azure supports availability zones only in a subset of regions. Atlas provides pre-defined availability zone tags for Azure only for regions that support availability zones. To learn more, see Microsoft Azure.

For more information about the possible availabilityZone values for each cloud provider, see the AWS, GCP, or Azure documentation.

cl_name

Human-readable label that identifies the cluster.

cl_role

Human readable label that defines the cluster role.

group_id

Unique hexadecimal digit string that identifies the project.

group_name

Label that uniquely identifies the project.

org_id

Unique hexadecimal digit string that identifies the organization.

node_type

Node type.

Possible values are ELECTABLE, READ_ONLY, and ANALYTICS.

For more information, see Node Types.

process_port

Port on which the process runs.

provider

Cloud provider on which the node is provisioned.

Possible values are AWS, GCP, and AZURE.

region

Cloud region in which the node resides.

For a complete list of possible region values, see the AWS, GCP, or Azure reference page.

rs_nm

Human-readable label that identifies the replica set.

rs_state

Number that indicates the replica set state.

mongodb_info is a gauge that always has the value of 1. This metric contains all the MongoDB Metric Labels and also the following labels:

Label
Description

mongodb_version

String that represents the major, minor, and patch versions.

replica_state_name

String that indicates the replica set member status.

process_type

String that indicates the process running. Its values can be mongod, mongos, or config.

Note

You can also view descriptions of each hardware metric in the Prometheus expression browser.

Name
Type
Description

hardware_disk_metrics_disk_space_free_bytes

Gauge

Disk space available in the mounted file system.

hardware_disk_metrics_disk_space_used_bytes

Gauge

Disk space used in the mounted file system.

hardware_disk_metrics_read_count

Counter

Number of read I/O's processed.

hardware_disk_metrics_read_time_milliseconds

Counter

Total wait time for read requests.

hardware_disk_metrics_sectors_read

Counter

Number of sectors read.

hardware_disk_metrics_sectors_written

Counter

Number of sectors written.

hardware_disk_metrics_total_time_milliseconds

Counter

Total time this block device is active.

hardware_disk_metrics_weighted_time_io_milliseconds

Counter

Weighted time spent doing I/O's.

hardware_disk_metrics_write_count

Counter

Number of write I/O's processed.

hardware_disk_metrics_write_time_milliseconds

Counter

Total wait time for write requests.

hardware_platform_num_logical_cpus

Gauge

Number of logical CPUs usable by the current process.

hardware_process_cpu_children_kernel_milliseconds

Counter

Amount of time scheduled in kernel mode for this process to wait for children.

hardware_process_cpu_children_user_milliseconds

Counter

Amount of time scheduled in user mode for this process to wait for children.

hardware_process_cpu_kernel_milliseconds

Counter

Amount of time scheduled in kernel mode for this process.

hardware_process_cpu_user_milliseconds

Counter

Amount of time scheduled in user mode for this process.

hardware_system_cpu_guest_milliseconds

Counter

Time spent running a virtual CPU for the guest operating systems under the control of the Linux kernel.

hardware_system_cpu_guest_nice_milliseconds

Counter

Time spent running a guest with an adjusted niceness.

hardware_system_cpu_idle_milliseconds

Counter

Time spent in the idle task.

hardware_system_cpu_io_wait_milliseconds

Counter

Time waiting for I/O to complete.

hardware_system_cpu_irq_milliseconds

Counter

Time spent servicing interrupts.

hardware_system_cpu_kernel_milliseconds

Counter

Time spent in system mode.

hardware_system_cpu_nice_milliseconds

Counter

Time spent in user mode with low priority (nice).

hardware_system_cpu_soft_irq_milliseconds

Counter

Time spent servicing softirqs.

hardware_system_cpu_steal_milliseconds

Counter

Time spent in other operating systems when running in a virtual environment.

hardware_system_cpu_user_milliseconds

Counter

Time spent in user mode.

hardware_system_memory_buffers_kilobytes

Gauge

Temporary storage for raw disk blocks that shouldn't get tremendously large.

hardware_system_memory_cached_kilobytes

Gauge

In-memory cache for files read from the disk. This doesn't include SwapCached.

hardware_system_memory_mem_available_kilobytes

Gauge

An estimate of how much memory is available for starting new applications, without swapping.

hardware_system_memory_mem_free_kilobytes

Gauge

Sum of LowFree + HighFree.

hardware_system_memory_mem_total_kilobytes

Gauge

Total usable RAM (physical RAM minus a few reserved bits and the kernel binary code).

hardware_system_memory_shared_mem_kilobytes

Gauge

Amount of memory consumed in file systems whose contents reside in virtual memory.

hardware_system_memory_swap_free_kilobytes

Gauge

Total amount of swap space unused.

hardware_system_memory_swap_total_kilobytes

Gauge

Total amount of swap space available.

hardware_system_network_eth0_bytes_in_bytes

Counter

Number of bytes of data received by the interface.

hardware_system_network_eth0_bytes_out_bytes

Counter

Number of bytes of data transmitted by the interface.

hardware_system_network_lo_bytes_in_bytes

Counter

Number of bytes of data received by the interface.

hardware_system_network_lo_bytes_out_bytes

Counter

Number of bytes of data transmitted by the interface.

hardware_system_vm_page_swap_in

Counter

Number of pages the system has swapped in from disk.

hardware_system_vm_page_swap_out

Counter

Number of pages the system has swapped out to disk.

Each hardware metric contains the following labels:

Note

In addition to the labels listed below, Atlas sends user-defined resource tags to Prometheus as labels. This is an opt-in feature that you enable through the UI or the API. See the Procedure section in this document to learn more about each procedure.

Label
Description

availability_zone

AWS availability zone ID, Google Cloud fully-qualified name for a zone, or Azure zone number.

Azure supports availability zones only in a subset of regions. Atlas provides pre-defined availability zone tags for Azure only for regions that support availability zones. To learn more, see Microsoft Azure.

For more information about the possible availabilityZone values for each cloud provider, see the AWS, GCP, or Azure documentation.

cl_name

Label that uniquely identifies the cluster.

disk_name

Human-readable label that identifies the disk.

group_id

Unique hexadecimal digit string that identifies the project.

group_name

Label that uniquely identifies the project.

org_id

Unique hexadecimal digit string that identifies the organization.

node_type

Node type.

Possible values are ELECTABLE, READ_ONLY, and ANALYTICS.

For more information, see Node Types.

process_port

Port on which the process runs.

provider

Cloud provider on which the node is provisioned.

Possible values are AWS, GCP, and AZURE.

region

Cloud region in which the node resides.

For a complete list of possible region values, see the AWS, GCP, or Azure reference page.

replica_set_name

Label that uniquely identifies the replica set.