master
yaml 813 lines 31.7 KB
Raw
1 plugin_name: go.d.plugin
2 modules:
3 - meta:
4 id: collector-go.d.plugin-mongodb
5 plugin_name: go.d.plugin
6 module_name: mongodb
7 monitored_instance:
8 name: MongoDB
9 link: https://www.mongodb.com/
10 icon_filename: mongodb.svg
11 categories:
12 - data-collection.databases
13 keywords:
14 - mongodb
15 - databases
16 related_resources:
17 integrations:
18 list: []
19 info_provided_to_referring_integrations:
20 description: ""
21 overview:
22 data_collection:
23 metrics_description: |
24 This collector monitors MongoDB servers.
25
26 Executed queries:
27
28 - [serverStatus](https://docs.mongodb.com/manual/reference/command/serverStatus/)
29 - [dbStats](https://docs.mongodb.com/manual/reference/command/dbStats/)
30 - [replSetGetStatus](https://www.mongodb.com/docs/manual/reference/command/replSetGetStatus/)
31 method_description: ""
32 supported_platforms:
33 include: []
34 exclude: []
35 multi_instance: true
36 additional_permissions:
37 description: ""
38 default_behavior:
39 auto_detection:
40 description: ""
41 limits:
42 description: ""
43 performance_impact:
44 description: ""
45 setup:
46 prerequisites:
47 list:
48 - title: Create a read-only user
49 description: |
50 Create a read-only user for Netdata in the admin database.
51
52 - Authenticate as the admin user:
53
54 ```bash
55 use admin
56 db.auth("admin", "<MONGODB_ADMIN_PASSWORD>")
57 ```
58
59 - Create a user:
60
61 ```bash
62 db.createUser({
63 "user":"netdata",
64 "pwd": "<UNIQUE_PASSWORD>",
65 "roles" : [
66 {role: 'read', db: 'admin' },
67 {role: 'clusterMonitor', db: 'admin'},
68 {role: 'read', db: 'local' }
69 ]
70 })
71 ```
72 configuration:
73 file:
74 name: go.d/mongodb.conf
75 options:
76 description: |
77 The following options can be defined globally: update_every, autodetection_retry.
78 folding:
79 title: Config options
80 enabled: true
81 list:
82 - name: update_every
83 description: Data collection interval (seconds).
84 default_value: 5
85 required: false
86 group: Collection
87 - name: autodetection_retry
88 description: Autodetection retry interval (seconds). Set 0 to disable.
89 default_value: 0
90 required: false
91 group: Collection
92
93 - name: uri
94 description: "MongoDB connection string. See [URI syntax](https://www.mongodb.com/docs/manual/reference/connection-string/)."
95 default_value: mongodb://localhost:27017
96 required: true
97 group: Target
98 - name: timeout
99 description: Query timeout (seconds).
100 default_value: 1
101 required: false
102 group: Target
103
104 - name: databases
105 description: Database selector. Defines which databases to collect metrics from.
106 default_value: ""
107 required: false
108 group: Filters
109 details: |
110 Metrics of databases matching the selector will be collected.
111
112 - Logic: (pattern1 OR pattern2) AND !(pattern3 OR pattern4)
113 - Pattern syntax: [matcher](https://github.com/netdata/netdata/tree/master/src/go/pkg/matcher#supported-format).
114 - Syntax:
115
116 ```yaml
117 databases:
118 includes:
119 - pattern1
120 - pattern2
121 excludes:
122 - pattern3
123 - pattern4
124 ```
125
126 - name: functions.top_queries.disabled
127 description: Disable the [top-queries](#top-queries) function.
128 default_value: false
129 required: false
130 group: Functions
131 - name: functions.top_queries.timeout
132 description: Query timeout (seconds). Uses collector timeout if not set.
133 default_value: ""
134 required: false
135 group: Functions
136 - name: functions.top_queries.limit
137 description: Maximum number of queries to return.
138 default_value: 500
139 required: false
140 group: Functions
141
142 - name: vnode
143 description: Associates this data collection job with a [Virtual Node](https://learn.netdata.cloud/docs/netdata-agent/configuration/organize-systems-metrics-and-alerts#virtual-nodes).
144 default_value: ""
145 required: false
146 group: Virtual Node
147 examples:
148 folding:
149 title: Config
150 enabled: true
151 list:
152 - name: TCP socket
153 description: An example configuration.
154 config: |
155 jobs:
156 - name: local
157 uri: mongodb://netdata:password@localhost:27017
158 - name: With databases metrics
159 description: An example configuration.
160 config: |
161 jobs:
162 - name: local
163 uri: mongodb://netdata:password@localhost:27017
164 databases:
165 includes:
166 - "* *"
167 - name: Multi-instance
168 description: |
169 > **Note**: When you define multiple jobs, their names must be unique.
170
171 Local and remote instances.
172 config: |
173 jobs:
174 - name: local
175 uri: mongodb://netdata:password@localhost:27017
176
177 - name: remote
178 uri: mongodb://netdata:password@203.0.113.0:27017
179 troubleshooting:
180 problems:
181 list: []
182 alerts: []
183 functions:
184 description: |
185 This collector exposes real-time functions for interactive troubleshooting in the Live tab.
186 list:
187 - id: top-queries
188 name: Top Queries
189 description: |
190 Retrieves profiled query statistics from MongoDB [system.profile](https://www.mongodb.com/docs/manual/reference/database-profiler/) collection.
191
192 This function queries the `system.profile` collection across all user databases (excluding admin, local, config) to retrieve slow or sampled queries captured by the MongoDB profiler. It provides detailed execution metrics including timing, document counts, and execution plan information.
193
194 Use cases:
195 - Identify slow queries that exceed the profiling threshold
196 - Analyze query patterns by examining docs examined vs docs returned ratios
197 - Detect collection scans (COLLSCAN) that may need index optimization
198
199 Query text is truncated at 4096 characters for display purposes.
200 parameters:
201 - id: __sort
202 name: Filter By
203 description: Select the primary sort column. Options include execution time, docs examined, keys examined, and more. Defaults to execution time to focus on slowest queries.
204 type: select
205 required: true
206 default: execution_time
207 options: []
208 returns:
209 description: Profiled query statistics from `system.profile`. Each row represents a single profiled operation with execution metrics and plan details.
210 columns:
211 - name: Timestamp
212 type: timestamp
213 unit: ""
214 description: "When the operation was profiled. Useful for correlating slow queries with application events."
215 - name: Namespace
216 type: string
217 unit: ""
218 description: "Database and collection name in format `database.collection`. Identifies which collection the operation targeted."
219 - name: Operation
220 type: string
221 unit: ""
222 description: "Type of operation: query, insert, update, remove, command, getmore. Helps categorize workload patterns."
223 - name: Query
224 type: string
225 unit: ""
226 description: "The command document as JSON showing the query filter, projection, and options. Truncated to 4096 characters."
227 - name: Execution Time
228 type: duration
229 unit: "seconds"
230 description: "Total execution time of the operation. High values indicate slow queries that may need optimization."
231 - name: Docs Examined
232 type: integer
233 unit: ""
234 description: "Number of documents scanned during execution. A high ratio of docs examined to docs returned suggests missing or inefficient indexes."
235 - name: Keys Examined
236 type: integer
237 unit: ""
238 description: "Number of index keys scanned. Compare with docs examined to assess index efficiency."
239 - name: Docs Returned
240 type: integer
241 unit: ""
242 description: "Number of documents returned to the client. Compare with docs examined to identify inefficient queries."
243 - name: Plan Summary
244 type: string
245 unit: ""
246 description: "Execution plan summary (e.g., IXSCAN, COLLSCAN, SORT). COLLSCAN indicates a full collection scan that may need an index."
247 - name: Client
248 type: string
249 unit: ""
250 description: "Client IP address or hostname that executed the operation. Useful for identifying query sources."
251 - name: User
252 type: string
253 unit: ""
254 description: "Authenticated user who executed the operation. Empty for unauthenticated connections."
255 - name: Docs Deleted
256 type: integer
257 unit: ""
258 visibility: hidden
259 description: "Number of documents deleted by the operation. Relevant for remove operations."
260 - name: Docs Inserted
261 type: integer
262 unit: ""
263 visibility: hidden
264 description: "Number of documents inserted by the operation. Relevant for insert operations."
265 - name: Docs Modified
266 type: integer
267 unit: ""
268 visibility: hidden
269 description: "Number of documents modified by the operation. Relevant for update operations."
270 - name: Response Length
271 type: integer
272 unit: ""
273 visibility: hidden
274 description: "Size of the response in bytes. Large responses may indicate queries returning excessive data."
275 - name: Num Yield
276 type: integer
277 unit: ""
278 visibility: hidden
279 description: "Number of times the operation yielded to allow other operations to proceed. High yields may indicate lock contention."
280 - name: App Name
281 type: string
282 unit: ""
283 description: "Application name from the client connection string. Useful for identifying which application generated the query."
284 - name: Cursor Exhausted
285 type: string
286 unit: ""
287 visibility: hidden
288 description: "Whether the cursor was fully exhausted (Yes/No)."
289 - name: Has Sort Stage
290 type: string
291 unit: ""
292 visibility: hidden
293 description: "Whether the query required an in-memory sort stage (Yes/No). In-memory sorts are slower than index-based sorts."
294 - name: Uses Disk
295 type: string
296 unit: ""
297 visibility: hidden
298 description: "Whether the operation used disk for sorting or aggregation (Yes/No). Indicates memory pressure."
299 - name: From Multi Planner
300 type: string
301 unit: ""
302 visibility: hidden
303 description: "Whether multiple query plans were evaluated (Yes/No)."
304 - name: Replanned
305 type: string
306 unit: ""
307 visibility: hidden
308 description: "Whether the query was replanned due to plan cache eviction (Yes/No)."
309 - name: Query Hash
310 type: string
311 unit: ""
312 visibility: hidden
313 description: "Hash of the query shape for identifying similar queries. Available in MongoDB 4.2+."
314 - name: Plan Cache Key
315 type: string
316 unit: ""
317 visibility: hidden
318 description: "Key used for plan cache lookup. Available in MongoDB 4.2+."
319 - name: Planning Time
320 type: duration
321 unit: "seconds"
322 visibility: hidden
323 description: "Time spent planning the query execution. Available in MongoDB 6.2+."
324 - name: CPU Time
325 type: duration
326 unit: "seconds"
327 visibility: hidden
328 description: "CPU time consumed by the operation. Available in MongoDB 6.3+ on Linux only."
329 - name: Query Framework
330 type: string
331 unit: ""
332 visibility: hidden
333 description: "Query execution framework used (classic or SBE). Available in MongoDB 7.0+."
334 - name: Query Shape Hash
335 type: string
336 unit: ""
337 visibility: hidden
338 description: "Hash representing the query shape for grouping similar queries. Available in MongoDB 8.0+."
339 performance: |
340 Reads from `system.profile` collection across all user databases:<br/>• Profiling itself adds overhead to MongoDB operations (typically 1-5%)<br/>• Default limit of 500 rows balances usefulness with performance
341 security: |
342 Query text may contain unmasked literal values including potentially sensitive data:<br/>• Document field values in query filters<br/>• Personal information in inserted/updated documents<br/>• Access should be restricted to authorized personnel only
343 prerequisites:
344 list:
345 - title: Enable MongoDB profiling
346 description: |
347 Database profiling must be enabled on each database you want to monitor, and the function must be enabled in the collector configuration.
348
349 1. Enable profiling on a database (profile slow queries > 100ms):
350
351 ```javascript
352 use myDatabase
353 db.setProfilingLevel(1, { slowms: 100 })
354 ```
355
356 2. Or profile all operations (level 2, use with caution):
357
358 ```javascript
359 db.setProfilingLevel(2)
360 ```
361
362 3. Verify profiling status:
363
364 ```javascript
365 db.getProfilingStatus()
366 ```
367
368 4. Enable the function in Netdata collector config:
369
370 ```yaml
371 jobs:
372 - name: local
373 uri: mongodb://localhost:27017
374 top_queries_function_enabled: true
375 ```
376
377 :::info
378
379 - Profiling level 0 = off, 1 = slow operations only, 2 = all operations
380 - The `slowms` threshold determines which queries are captured at level 1
381 - `system.profile` is a capped collection; old entries are automatically removed
382 - System databases (admin, local, config) are excluded from profiling queries
383
384 :::
385 availability: |
386 Available when:<br/>• The collector has successfully connected to MongoDB<br/>• Profiling is enabled on at least one user database<br/>• Returns HTTP 503 if collector is still initializing or profiling is disabled on all databases<br/>• Returns HTTP 500 if the query fails<br/>• Returns HTTP 504 if the query times out
387 require_cloud: true
388 metrics:
389 folding:
390 title: Metrics
391 enabled: false
392 availability: []
393 description: |
394 - WireTiger metrics are available only if [WiredTiger](https://docs.mongodb.com/v6.0/core/wiredtiger/) is used as the
395 storage engine.
396 - Sharding metrics are available on shards only
397 for [mongos](https://www.mongodb.com/docs/manual/reference/program/mongos/).
398 scopes:
399 - name: global
400 description: These metrics refer to the entire monitored application.
401 labels: []
402 metrics:
403 - name: mongodb.operations_rate
404 description: Operations rate
405 unit: operations/s
406 chart_type: line
407 dimensions:
408 - name: reads
409 - name: writes
410 - name: commands
411 - name: mongodb.operations_latency_time
412 description: Operations Latency
413 unit: milliseconds
414 chart_type: line
415 dimensions:
416 - name: reads
417 - name: writes
418 - name: commands
419 - name: mongodb.operations_by_type_rate
420 description: Operations by type
421 unit: operations/s
422 chart_type: line
423 dimensions:
424 - name: insert
425 - name: query
426 - name: update
427 - name: delete
428 - name: getmore
429 - name: command
430 - name: mongodb.document_operations_rate
431 description: Document operations
432 unit: operations/s
433 chart_type: stacked
434 dimensions:
435 - name: inserted
436 - name: deleted
437 - name: returned
438 - name: updated
439 - name: mongodb.scanned_indexes_rate
440 description: Scanned indexes
441 unit: indexes/s
442 chart_type: line
443 dimensions:
444 - name: scanned
445 - name: mongodb.scanned_documents_rate
446 description: Scanned documents
447 unit: documents/s
448 chart_type: line
449 dimensions:
450 - name: scanned
451 - name: mongodb.active_clients_count
452 description: Connected clients
453 unit: clients
454 chart_type: line
455 dimensions:
456 - name: readers
457 - name: writers
458 - name: mongodb.queued_operations_count
459 description: Queued operations because of a lock
460 unit: operations
461 chart_type: line
462 dimensions:
463 - name: reads
464 - name: writes
465 - name: mongodb.cursors_open_count
466 description: Open cursors
467 unit: cursors
468 chart_type: line
469 dimensions:
470 - name: open
471 - name: mongodb.cursors_open_no_timeout_count
472 description: Open cursors with disabled timeout
473 unit: cursors
474 chart_type: line
475 dimensions:
476 - name: open_no_timeout
477 - name: mongodb.cursors_opened_rate
478 description: Opened cursors rate
479 unit: cursors/s
480 chart_type: line
481 dimensions:
482 - name: opened
483 - name: mongodb.cursors_timed_out_rate
484 description: Timed-out cursors
485 unit: cursors/s
486 chart_type: line
487 dimensions:
488 - name: timed_out
489 - name: mongodb.cursors_by_lifespan_count
490 description: Cursors lifespan
491 unit: cursors
492 chart_type: stacked
493 dimensions:
494 - name: le_1s
495 - name: 1s_5s
496 - name: 5s_15s
497 - name: 15s_30s
498 - name: 30s_1m
499 - name: 1m_10m
500 - name: ge_10m
501 - name: mongodb.transactions_count
502 description: Current transactions
503 unit: transactions
504 chart_type: line
505 dimensions:
506 - name: active
507 - name: inactive
508 - name: open
509 - name: prepared
510 - name: mongodb.transactions_rate
511 description: Transactions rate
512 unit: transactions/s
513 chart_type: line
514 dimensions:
515 - name: started
516 - name: aborted
517 - name: committed
518 - name: prepared
519 - name: mongodb.connections_usage
520 description: Connections usage
521 unit: connections
522 chart_type: stacked
523 dimensions:
524 - name: available
525 - name: used
526 - name: mongodb.connections_by_state_count
527 description: Connections By State
528 unit: connections
529 chart_type: line
530 dimensions:
531 - name: active
532 - name: threaded
533 - name: exhaust_is_master
534 - name: exhaust_hello
535 - name: awaiting_topology_changes
536 - name: mongodb.connections_rate
537 description: Connections Rate
538 unit: connections/s
539 chart_type: line
540 dimensions:
541 - name: created
542 - name: mongodb.asserts_rate
543 description: Raised assertions
544 unit: asserts/s
545 chart_type: stacked
546 dimensions:
547 - name: regular
548 - name: warning
549 - name: msg
550 - name: user
551 - name: tripwire
552 - name: rollovers
553 - name: mongodb.network_traffic_rate
554 description: Network traffic
555 unit: bytes/s
556 chart_type: stacked
557 dimensions:
558 - name: in
559 - name: out
560 - name: mongodb.network_requests_rate
561 description: Network Requests
562 unit: requests/s
563 chart_type: line
564 dimensions:
565 - name: requests
566 - name: mongodb.network_slow_dns_resolutions_rate
567 description: Slow DNS resolution operations
568 unit: resolutions/s
569 chart_type: line
570 dimensions:
571 - name: slow_dns
572 - name: mongodb.network_slow_ssl_handshakes_rate
573 description: Slow SSL handshake operations
574 unit: handshakes/s
575 chart_type: line
576 dimensions:
577 - name: slow_ssl
578 - name: mongodb.memory_resident_size
579 description: Used resident memory
580 unit: bytes
581 chart_type: line
582 dimensions:
583 - name: used
584 - name: mongodb.memory_virtual_size
585 description: Used virtual memory
586 unit: bytes
587 chart_type: line
588 dimensions:
589 - name: used
590 - name: mongodb.memory_page_faults_rate
591 description: Memory page faults
592 unit: pgfaults/s
593 chart_type: line
594 dimensions:
595 - name: pgfaults
596 - name: mongodb.memory_tcmalloc_stats
597 description: TCMalloc statistics
598 unit: bytes
599 chart_type: line
600 dimensions:
601 - name: allocated
602 - name: central_cache_freelist
603 - name: transfer_cache_freelist
604 - name: thread_cache_freelists
605 - name: pageheap_freelist
606 - name: pageheap_unmapped
607 - name: mongodb.wiredtiger_concurrent_read_transactions_usage
608 description: Wired Tiger concurrent read transactions usage
609 unit: transactions
610 chart_type: stacked
611 dimensions:
612 - name: available
613 - name: used
614 - name: mongodb.wiredtiger_concurrent_write_transactions_usage
615 description: Wired Tiger concurrent write transactions usage
616 unit: transactions
617 chart_type: stacked
618 dimensions:
619 - name: available
620 - name: used
621 - name: mongodb.wiredtiger_cache_usage
622 description: Wired Tiger cache usage
623 unit: bytes
624 chart_type: line
625 dimensions:
626 - name: used
627 - name: mongodb.wiredtiger_cache_dirty_space_size
628 description: Wired Tiger cache dirty space size
629 unit: bytes
630 chart_type: line
631 dimensions:
632 - name: dirty
633 - name: mongodb.wiredtiger_cache_io_rate
634 description: Wired Tiger IO activity
635 unit: pages/s
636 chart_type: line
637 dimensions:
638 - name: read
639 - name: written
640 - name: mongodb.wiredtiger_cache_evictions_rate
641 description: Wired Tiger cache evictions
642 unit: pages/s
643 chart_type: stacked
644 dimensions:
645 - name: unmodified
646 - name: modified
647 - name: mongodb.sharding_nodes_count
648 description: Sharding Nodes
649 unit: nodes
650 chart_type: stacked
651 dimensions:
652 - name: shard_aware
653 - name: shard_unaware
654 - name: mongodb.sharding_sharded_databases_count
655 description: Sharded databases
656 unit: databases
657 chart_type: stacked
658 dimensions:
659 - name: partitioned
660 - name: unpartitioned
661 - name: mongodb.sharding_sharded_collections_count
662 description: Sharded collections
663 unit: collections
664 chart_type: stacked
665 dimensions:
666 - name: partitioned
667 - name: unpartitioned
668 - name: lock type
669 description: These metrics refer to the lock type.
670 labels:
671 - name: lock_type
672 description: lock type (e.g. global, database, collection, mutex)
673 metrics:
674 - name: mongodb.lock_acquisitions_rate
675 description: Lock acquisitions
676 unit: acquisitions/s
677 chart_type: line
678 dimensions:
679 - name: shared
680 - name: exclusive
681 - name: intent_shared
682 - name: intent_exclusive
683 - name: commit type
684 description: These metrics refer to the commit type.
685 labels:
686 - name: commit_type
687 description: commit type (e.g. noShards, singleShard, singleWriteShard)
688 metrics:
689 - name: mongodb.transactions_commits_rate
690 description: Transactions commits
691 unit: commits/s
692 chart_type: line
693 dimensions:
694 - name: success
695 - name: fail
696 - name: mongodb.transactions_commits_duration_time
697 description: Transactions successful commits duration
698 unit: milliseconds
699 chart_type: line
700 dimensions:
701 - name: commits
702 - name: database
703 description: These metrics refer to the database.
704 labels:
705 - name: database
706 description: database name
707 metrics:
708 - name: mongodb.database_collection_count
709 description: Database collections
710 unit: collections
711 chart_type: line
712 dimensions:
713 - name: collections
714 - name: mongodb.database_indexes_count
715 description: Database indexes
716 unit: indexes
717 chart_type: line
718 dimensions:
719 - name: indexes
720 - name: mongodb.database_views_count
721 description: Database views
722 unit: views
723 chart_type: line
724 dimensions:
725 - name: views
726 - name: mongodb.database_documents_count
727 description: Database documents
728 unit: documents
729 chart_type: line
730 dimensions:
731 - name: documents
732 - name: mongodb.database_data_size
733 description: Database data size
734 unit: bytes
735 chart_type: line
736 dimensions:
737 - name: data_size
738 - name: mongodb.database_storage_size
739 description: Database storage size
740 unit: bytes
741 chart_type: line
742 dimensions:
743 - name: storage_size
744 - name: mongodb.database_index_size
745 description: Database index size
746 unit: bytes
747 chart_type: line
748 dimensions:
749 - name: index_size
750 - name: replica set member
751 description: These metrics refer to the replica set member.
752 labels:
753 - name: repl_set_member
754 description: replica set member name
755 metrics:
756 - name: mongodb.repl_set_member_state
757 description: Replica Set member state
758 unit: state
759 chart_type: line
760 dimensions:
761 - name: primary
762 - name: startup
763 - name: secondary
764 - name: recovering
765 - name: startup2
766 - name: unknown
767 - name: arbiter
768 - name: down
769 - name: rollback
770 - name: removed
771 - name: mongodb.repl_set_member_health_status
772 description: Replica Set member health status
773 unit: status
774 chart_type: line
775 dimensions:
776 - name: up
777 - name: down
778 - name: mongodb.repl_set_member_replication_lag_time
779 description: Replica Set member replication lag
780 unit: milliseconds
781 chart_type: line
782 dimensions:
783 - name: replication_lag
784 - name: mongodb.repl_set_member_heartbeat_latency_time
785 description: Replica Set member heartbeat latency
786 unit: milliseconds
787 chart_type: line
788 dimensions:
789 - name: heartbeat_latency
790 - name: mongodb.repl_set_member_ping_rtt_time
791 description: Replica Set member ping RTT
792 unit: milliseconds
793 chart_type: line
794 dimensions:
795 - name: ping_rtt
796 - name: mongodb.repl_set_member_uptime
797 description: Replica Set member uptime
798 unit: seconds
799 chart_type: line
800 dimensions:
801 - name: uptime
802 - name: shard
803 description: These metrics refer to the shard.
804 labels:
805 - name: shard_id
806 description: shard id
807 metrics:
808 - name: mongodb.sharding_shard_chunks_count
809 description: Shard chunks
810 unit: chunks
811 chart_type: line
812 dimensions:
813 - name: chunks