{"id":43865,"library":"spm-agent-mongodb","title":"SPM Agent for MongoDB","description":"SPM Agent for MongoDB (v3.0.4) is a monitoring agent that collects and reports MongoDB metrics to Sematext Cloud (APM). It supports MongoDB clusters, replica sets, and standalone instances, providing real-time visibility into performance, queries, connections, and disk usage. The agent runs as a system service and requires Node.js and admin privileges (ClusterAdmin role) to access MongoDB internal metrics. Key differentiators include seamless integration with Sematext's monitoring stack, support for Kerberos authentication, Docker deployment via SPM-Client image, and automatic anomaly detection. It is released regularly but no fixed cadence is published.","status":"active","version":"3.0.4","language":"javascript","source_language":"en","source_url":"https://github.com/sematext/spm-agent-mongodb","tags":["javascript","SPM","APM","application performance monitoring","Sematext","performance monitoring","monitoring","alerting","anomaly detection"],"install":[{"cmd":"npm install spm-agent-mongodb","lang":"bash","label":"npm"},{"cmd":"yarn add spm-agent-mongodb","lang":"bash","label":"yarn"},{"cmd":"pnpm add spm-agent-mongodb","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Native MongoDB driver for Node.js; required to connect and query MongoDB instances.","package":"mongodb","optional":false}],"imports":[{"note":"This package is a CLI agent, not a library. It is installed globally or used via Docker. No programmatic imports.","wrong":"Cannot be imported as a module; use spm-mongodb-setup or spm-agent-mongodb CLI.","symbol":"SPM Agent for MongoDB (CLI tool)","correct":"Install globally: npm i spm-agent-mongodb -g"},{"note":"Run from command line: spm-agent-mongodb <SPM_TOKEN> <MONGODB_URL>. Also configurable via environment or config file.","wrong":"Do not use require() as it is a CLI tool.","symbol":"MongoDB metrics agent","correct":"spm-agent-mongodb TOKEN URL"}],"quickstart":{"code":"sudo npm i spm-agent-mongodb -g\nsudo spm-mongodb-setup -t YOUR_SPM_TOKEN -m mongodb://localhost:27017/local\n# Then start the agent as a service (systemd):\nsudo systemctl start spm-agent-mongodb\n# Or run directly:\nspm-agent-mongodb YOUR_SPM_TOKEN mongodb://localhost:27017/local","lang":"javascript","description":"Installs the agent globally, configures it with a Sematext token and MongoDB URL, then starts the monitoring agent as a service or interactive process."},"warnings":[{"fix":"Grant clusterMonitor role or clusterAdmin and read on any database to the MongoDB user used by the agent.","message":"The agent requires admin rights (ClusterAdmin role) and read access to any database. Without proper permissions, metrics collection will fail silently.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Install libkrb5-dev via apt-get before npm install: apt-get install libkrb5-dev","message":"Kerberos authentication requires libkrb5-dev system package. Missing it leads to build failures during npm install.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Migrate from old config (e.g., /etc/spm-agent-mongodb.cfg) to new location and format.","message":"Earlier versions used a different config file location and format. v3.x uses /etc/sematext/spm-agent-mongodb.config.","severity":"deprecated","affected_versions":">=3.0.0"},{"fix":"Deploy multiple Docker containers for different MongoDB endpoints.","message":"The agent does not support running multiple instances on the same host out-of-the-box; each MongoDB cluster requires a separate agent installation or Docker container.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Backup /etc/sematext/spm-agent-mongodb.config before running spm-mongodb-setup again.","message":"The setup script spm-mongodb-setup may overwrite existing config file if run again. Backup your config before re-running.","severity":"gotcha","affected_versions":">=0.0.0"}],"env_vars":null,"search_vec":"'access':61 'admin':56 'agent':2,6,13,46 'alert':110 'anomali':88,111 'apm':23,102 'applic':103 'authent':78 'automat':87 'cadenc':97 'client':84 'cloud':22 'cluster':27 'clusteradmin':58 'collect':15 'connect':41 'deploy':80 'detect':89,112 'differenti':66 'disk':43 'docker':79 'fix':96 'imag':85 'includ':67 'instanc':32 'integr':69 'intern':63 'javascript':100 'kerbero':77 'key':65 'metric':19,64 'mongodb':4,8,18,26,62 'monitor':12,73,105,108,109 'node.js':54 'perform':39,104,107 'privileg':57 'provid':33 'publish':99 'queri':40 'real':35 'real-tim':34 'regular':93 'releas':92 'replica':28 'report':17 'requir':53 'role':59 'run':47 'seamless':68 'sematext':21,71,106 'servic':51 'set':29 'spm':1,5,83,101 'spm-client':82 'stack':74 'standalon':31 'support':25,75 'system':50 'time':36 'usag':44 'v3.0.4':9 'via':81 'visibl':37","created_at":"2026-06-05T17:01:51.198121+00:00","updated_at":"2026-06-05T17:01:51.198121+00:00","problems":[{"fix":"If using Sematext EU, run 'sudo spm-mongodb-setup -r EU' to configure EU API endpoints.","cause":"DNS resolution failure when connecting to Sematext US endpoint.","error":"Error: getaddrinfo ENOTFOUND apps.sematext.com"},{"fix":"Ensure the MongoDB user has clusterMonitor and read on any database roles.","cause":"Agent's MongoDB user lacks required roles.","error":"MongoError: not authorized on db to execute command"},{"fix":"Install build-essential: sudo apt-get install build-essential","cause":"Missing system build tools (C++ compiler, make) required for Kerberos native module.","error":"npm ERR! gyp: No 'target_arch' was specified."}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"http://www.sematext.com","github":"https://github.com/sematext/spm-agent-mongodb","docs":null,"changelog":null,"pypi":null,"npm":"spm-agent-mongodb","openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-05","next_check":"2026-09-03","install_tag":null}}