{"id":19653555,"url":"https://github.com/sematext/spm-agent","last_synced_at":"2025-04-28T17:31:36.992Z","repository":{"id":27902102,"uuid":"31393788","full_name":"sematext/spm-agent","owner":"sematext","description":"SPM Agent Framework written in NodeJS","archived":false,"fork":false,"pushed_at":"2023-10-19T12:23:22.000Z","size":831,"stargazers_count":9,"open_issues_count":3,"forks_count":1,"subscribers_count":21,"default_branch":"master","last_synced_at":"2025-04-15T21:23:28.422Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://sematext.com/spm","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sematext.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-02-26T23:12:07.000Z","updated_at":"2022-03-28T23:07:12.000Z","dependencies_parsed_at":"2024-06-18T22:59:18.656Z","dependency_job_id":"4a418ad0-7eac-42ee-8c41-f7e44c1cf08e","html_url":"https://github.com/sematext/spm-agent","commit_stats":{"total_commits":316,"total_committers":10,"mean_commits":31.6,"dds":0.5126582278481013,"last_synced_commit":"5f1d35e4ca84458a5e03e59e57d81be67c91e8c6"},"previous_names":[],"tags_count":41,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sematext%2Fspm-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sematext%2Fspm-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sematext%2Fspm-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sematext%2Fspm-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sematext","download_url":"https://codeload.github.com/sematext/spm-agent/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251355428,"owners_count":21576357,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-11T15:14:29.595Z","updated_at":"2025-04-28T17:31:36.714Z","avatar_url":"https://github.com/sematext.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Sematext Agent Framework for Node.js\n\nA framework for monitoring agents written in Node.js for sending metrics to [Sematext Cloud](https://sematext.com/cloud) or InfluxDB. The Sematext [Node.js monitoring agent](https://github.com/sematext/spm-agent-nodejs) is built on top of this framework.\n\n\n## Functionality\n\n- Sender interface to Sematext backend receivers\n- Buffering metrics in case of network outages\n- Reconnect after failures\n- Logging functions \n- Configuration handling \n- Pluggable agents\n\n## Example to Implement a Monitoring Agent\n\nSematext Cloud supports the Influx Line Protocol for  metric ingestion. \n\nAgent modules must provide a `start` and `stop`function.   \n\nThe function `agent.addMetrics(metric)` collects a metric, which is shipped in bulk requests via Influx Line Protocol to the metrics receiver. \n\nAll metric objects, must have the mandatory fields `measurement`, `tags` and `fields`: \n\n- measurement - the name of the measurement e.g. 'process.memry'\n- tags - key/value pairs, useful for filtering or aggregation of data\n- fields - numeric fields with the measurement values\n\n```js\n\nconst SpmAgent = require('spm-agent')\nconst client = new SpmAgent()\nconst os = require('os')\n\n// configure client, with non-default values\n// or use the file ./.spmagentrc in YAML format\n// the default configuration contains values for Sematext Cloud US\n// SpmAgent.Config.tokens.spm = process.env.MONITORING_TOKEN\nSpmAgent.Config.influx = {\n  dbName: 'metrics',\n  // change receiver to Sematext Cloud EU\n  // default is spm-receiver.sematext.com for US region\n  host: 'spm-receiver.eu.sematext.com',\n  port: 443,\n  protocol: 'https'\n}\n\n// a monitoring agent needs a start an stop function\nclass MemoryMonitor {\n  start (agent) {\n    this.agent = agent\n    // initialize your metrics collector ...\n    // Typically agents collect metrics periodically, every N seconds. The time between // two collection activities is the collectionInterval, specified in milliseconds.\n    this.tid = setInterval(function () {\n      const measurement = {\n        // measurment namespace\n        measurement: 'process.memory',\n        timestap: new Date(),\n        tags: {\n          role: 'frontend',\n          'os.host': os.hostname()\n          // The monitoring token can be set as 'tags.token' value\n          // Routing a metrics to a different monitoring app\n          // requires setting the `token` tag\n          // ,token = process.env.OTHER_APP_TOKEN\n        },\n        // metrics names and values\n        fields: {\n          rss: process.memoryUsage().rss\n        }\n      }\n      // pass metrics to sender schedule\n      agent.addMetrics(measurement)\n    }, SpmAgent.Config.collectionInterval)\n  }\n\n  stop () {\n    if (this.tid) {\n      clearInterval(this.tid)\n    }\n  }\n}\n\nclient.createAgent(new SpmAgent.Agent(new MemoryMonitor()))\n\n// log collected metrics to console\n// observe all metrics for testing/debuggin\nclient.on('metrics', console.log)\n// observe a specific metric using the measurment name\nclient.on('process.memory', console.log)\n\n```\n\n## Metric Tags\n\nThe agent is able to use environment variables as metrics tags. \nDefine a list of environment variables to be used as metric tags.\n\nLet's assume this is the enviroment of the monitored application: \n\n```\n\u003e env\nTERM_PROGRAM=Apple_Terminal\nTERM=xterm-256color\nSHELL=/bin/bash\nTMPDIR=/var/folders/v6/bh2q1xsn27g4d2g54z2ylv100000gn/T/\nTERM_PROGRAM_VERSION=404.1\nTERM_SESSION_ID=F12E0DBD-BF40-466D-85EC-08E89EDC3440\nUSER=stefan\nPWD=/Users/stefan\nHOME=/Users/stefan\nLOGNAME=stefan\nLC_CTYPE=UTF-8\nDISPLAY=/private/tmp/com.apple.launchd.J60ybGpban/org.macosforge.xquartz:0\n_=/usr/bin/env\n```\n\nYou want to see later the performance metrics aggregated or filtered for specific user. \nIn this case the agent should collect the user name as tag. You can find the user name in the process environment variable `USER`. \nLet's also assume the workingdirectory of the application `PWD` is another relevant identifier for your monitored application. \n\nTo configure the agent collecting USER and PWD as tags you can specify a commaseparated list of environment variables for the the agent configuration: \n\n```\n# add the values of env. variables USER, PWD as tags to metrics\nexport MONITORING_TAGS_FROM_ENV=\"USER, PWD\"\n```\n\nThe generated metrics include then the environment variable name and its value as tags. The result in Influx Line Protocol (ILP) format, produced by the agent for metric called `swap`: \n\n```\nswap, USER=stefan,PWD=/Users/stefan out=0i,in=0i 1576765680000000000\n```\n\nDefine static tags in `key:value` format \n\n```\nexport MONITORING_TAGS_FROM_ENV=\"organisation:sematext, service:api\"\n\n```\n\nThe result in in ILP format: \n\n```\nswap, organisation=sematext,service=api out=0i,in=0i 1576765680000000000\n```\n\n\nBoth types of tags can be mixed: \n\n```\nexport MONITORING_TAGS_FROM_ENV=\"organisation:sematext, service:api, USER, PWD\"\n\n```\n\nThe result in in ILP format: \n\n```\nswap, organisation=sematext,service=api,USER=stefan,PWD=/Users/stefan,os.host=imac.local out=0i,in=0i 1576765680000000000\n```\n\n\nThe config file entry `influx.tagsFromEnv` in `.spmagenrc` works as well: \n\n```\ntokens: \n  spm: 'YOUR_MONITORING_TOKEN'\n  infra: 'YOUR_INFRA_MONITROING_TOKEN'\ninflux:\n  tagsFromEnv: 'organisation:sematext, USER, PWD' \n  dbName: 'metrics'\n  host: spm-receiver.sematext.com\n  protocol: https\n  port: 443\n  \n```     \n\n# Contribute \n\nLet us know about monitoring agents you need, maybe you like to contribute with your domain expertise!\n\n# Related Modules\n\n- [Node.js Monitoring](https://sematext.com/integrations/nodejs/)\n- [spm-agent-nodejs](https://github.com/sematext/spm-agent-nodejs)\n- [Sematext Cloud](https://sematext.com/) - full stack observability platform\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsematext%2Fspm-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsematext%2Fspm-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsematext%2Fspm-agent/lists"}