https://github.com/yahoo/monitr

A Node.js process monitoring tool.
https://github.com/yahoo/monitr

cpp nodejs process-monitoring web

Last synced: about 7 hours ago
JSON representation

A Node.js process monitoring tool.

• Host: GitHub
• URL: https://github.com/yahoo/monitr
• Owner: yahoo
• License: bsd-3-clause
• Created: 2013-09-23T17:54:25.000Z (over 11 years ago)
• Default Branch: master
• Last Pushed: 2024-10-28T22:08:45.000Z (2 months ago)
• Last Synced: 2025-01-04T04:07:19.212Z (7 days ago)
• Topics: cpp, nodejs, process-monitoring, web
• Language: C++
• Homepage:
• Size: 197 KB
• Stars: 315
• Watchers: 29
• Forks: 39
• Open Issues: 6
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

• awesome-repositories - yahoo/monitr - A Node.js process monitoring tool. (C++)

README

        
# monitr

Nodejs process monitoring module

This package is tested only with Node.js LTS versions.

_Note: This module currently works only on Linux operating systems_.

## External statistics reporting

This module starts a separate thread within the Nodejs runtime that

monitors and collects statistics about the running nodejs process.

These statistics are then sent as JSON messages via UDP datagrams over

a local domain socket.

Here is the list of data the module reports periodically:

```

 { status:

     { pid: ,

       ts: ,

       cluster: ,

       reqstotal: ,

       utcstart: ,

       events: ,,

       cpu: ,

       mem: ,

       cpuperreq: ,

       oreqs: ,

       sys_cpu: ,

       oconns: ,

       user_cpu: ,

       rps: ,

       kbs_out: ,

       elapsed: ,

       kb_trans: ,

       jiffyperreq: ,

       gc: {

           scavenge: { count: , elapsed_ms: , max_ms:  },

           marksweep: { count: , elapsed_ms: , max_ms:  }

       }

    }

 }

```

## GC introspection

It provides the running nodejs application with the ability to

introspect garbage collection activity by creating read-only

properties at `process.monitor.gc` that reports:

1.  `count`: number of times GC stop-the-world events occurred

2.  `elapsed`: cumulative time (in milliseconds) spent in GC

# Installation

With [npm](http://npmjs.org) do:

```

npm install monitr

```

# Usage

```js

var monitor = require('monitr');

```

## start()

```js

monitor.start();

```

Spawns a thread and monitors the process. Writes process stats every second to the socket path.

## stop()

```js

monitor.stop();

```

Terminates the thread and closes the socket.

## setIpcMonitorPath(socketPath)

```js

monitor.setIpcMonitorPath('/tmp/my-process-stats.mon');

```

Sets the datagram socket name to write the stats. Defaults to /tmp/nodejs.mon

# Health Status

Monitr supports custom health functionality whereby the app can report its own health.

The following methods are added to process.monitor to set and get the health information.

```js

setHealthStatus(isDown, statusCode)

isDown()

getStatusCode()

getStatusTimestamp() - Return seconds when setHealthStatus was last called

getStatusDate() - Return Date object

```

Once setHealthStatus is invoked, the status json, described above, will have following additional fields.

```js

health_status_timestamp: ,

health_is_down: ,

health_status_code: 

```

# Handling HUP events

`Monitr` installs a custom `SIGHUP` handler which will optionally

print out a NodeJS stack backtrace of the Javascript currently being

executed.  This can be useful for debugging where a NodeJS process may

be _stuck_.

# Implementation

It looks up /proc/* files on the system to report CPU Usage.  It looks

up /proc/pid/* files on the system to report its own stats.

`process.monitor.*` methods are set by `lib/monitor.js`.

It calls the process.monitor.* methods to report total requests since

monitoring started (`reqstotal`), current requests in flight

(`oreqs`), current open connections (`oconns`) and total data returned

since monitoring started (`kb_trans`).  _Note: `oreqs` may be greater

than `oconns` when keepalive is enabled_.

It attaches to the v8 garbage collection hooks to instrument (for each

GC type) the following stats for each reporting interval.

1.  `count` : number of times GC type invoked

2.  `elapsed_ms`: total elapsed time nodejs thread is blocked

3.  `max_ms`:  maximum time spent blocked by any one GC event

# Example

Please refer to examples/README.md for examples showing the use of these functions.

# Build Status

[![Build Status](https://secure.travis-ci.org/yahoo/monitr.png?branch=master)](http://travis-ci.org/yahoo/monitr)

# Node Badge

[![NPM](https://nodei.co/npm/monitr.png)](https://nodei.co/npm/monitr/)