Painless performance monitoring for Windows.
Switch branches/tags
Nothing to show
Clone or download
Latest commit a850c9f Sep 14, 2018

README.md

mon

Painless performance monitoring for Windows.

Screenshot

Features

  • Monitor local and remote Windows machines (even from Mac OS or Linux).
  • Completely customizable.
  • Support for thresholds.
  • Support for statistical functions.
  • Support for lists.
  • Support for formulas.
  • Support for variables.
  • Support for custom number formats.
  • Automatic process ID to IIS application pool mapping.
  • Support for exporting data to Elasticsearch.

Install

npm install -g monjs

Usage

Monitor the local machine:

mon [<configfile>]

Monitor a remote machine:

mon --server <address>:<port> [<configfile>]

Note: If no config file is specified, the default (and very simple) config is used.

Start a server that lets client connect to and monitor the local machine:

mon serve [--port <port>]

Warning 1: There is no authentication mechanism in this version. Any person who knows the address and port of the server can connect and view its status. Make sure to have proper firewall settings in place.

Warning 2: Data is sent in plain text over an unencrypted HTTP connection in this version. HTTPS support will be added soon.

Config File

To use mon you need to provide it with a config file that specifies which metrics you want to monitor. There are some sample config files in the config directory that you can use as a template.

The format of the config file is as follows:

{
  "groups": [
    {
      # Name of the group
      "name": "CPU",

      # Index of column to display this group in. (Default is 1)
      "column": 1,

      # Array of counters to show in this group
      "counters": [

        # Simple format:
        # Name of the Performance Counter
        "\\Processor(_Total)\\% Processor Time",

        # - OR -

        # Detailed format:
        {
          # Name of the Performance Counter
          "id": "\\Processor(_Total)\\% Processor Time",

          # Display name for the counter (Optional)
          "name": "Total",

          # Formula (Optional)
          "formula": "value / 2",

          # Format (Default is "0,0")
          # See numeraljs.com for a list of available formats.
          "format": "0,0",

          # Threshold values for the counter (Optional)
          # Valid values are: ok, warning and critical
          "threshold": {
            "50": "ok",
            "75": "warning",
            "*": "critical"
          },

          # Statistical functions to calculate and display (Optional)
          # Currently supported functions are: avg and sum
          # The first argument is the number of samples.
          "stats": [
            "avg(60)",
            "sum(1200)"
          ]
        }
      },

      # Array of lists to show in this group
      "lists": [
        {
          # Name of the list
          "name": "CPU Usage",

          # Name of the Performance Counter to generate the list from
          # It must have an asterisk (*) as the instance name.
          "id": "\\Process(*)\\% Processor Time",

          # Formula (Optional)
          "formula": "value / env.NUMBER_OF_PROCESSORS",

          # Maximum number of items to show (Default is 5)
          "count": 5,

          # Sorting order (Default is desc)
          # Valid values are asc and desc.
          "sort": "desc",

          # Items to exclude from the list (Optional)
          "exclude": [
            "_Total",
            "Idle"
          ],

          # OMG! Lists support thresholds as well. (Optional)
          "threshold": {
            "400": "ok",
            "800": "warning",
            "*": "critical"
          },

          # Lists support statistical functions too. How cool is that? (Optional)
          "stats": [
            "avg(60)"
          ]
        }
      ]
    }
  ]
}

Counters

The primary usage of mon is to view values of various Performance Counters that are available in Windows.

To monitor a counter, simply specify its name in the list of counters:

counters: [
  "\\Processor(_Total)\\% Processor Time",
  "\\Processor(_Total)\\% Privileged Time",
  "\\Processor(_Total)\\% User Time"
]

If you need to specify other properties for the counter like format or threshold, use the detailed format:

counters: [
  {
    "name": "Used Memory",
    "id": "\\Process(_Total)\\Working Set",
    "format": "0.000 b"
  },
  {
    "name": "Free Memory",
    "id": "\\Memory\\Available Bytes",
    "format": "0.000 b"
  }
]

Thresholds

There are three levels of threshold (ok, warning, critical) that you can set for each counter to easily see if they are above or below the desired value.

counters: [
  {
    "name": "Free Memory",
    "id": "\\Memory\\Available Bytes",
    "threshold": {
      "1000000000": "critical",
      "2000000000": "warning",
      "*": "ok"
    }
  }
]

Statistical Functions

To get a clearer understanding of how some metrics are doing, you can apply statistical functions like avg and sum to counters.

The following example displays the 60-sample moving average of the % Processor Time counter:

"counters": [
  {
    "id": "\\Processor(_Total)\\% Processor Time",
    "name": "CPU Usage",
    "stats": [
      "avg(60)"
    ]
  }
]

Lists

In addition to displaying values of counters, mon is able to retrieve values of all instances of a counter and compile them into a list. This is very useful for monitoring metrics like top CPU or memory usage.

Lists support thresholds and statistical functions too.

The following example displays a list of top 10 CPU intensive processes along with the 60-sample moving average of the list to provide a better view of the system performance:

lists: [
  {
    "name": "CPU Usage",
    "id": "\\Process(*)\\% Processor Time",
    "count": 10,
    "sort": "desc",
    "exclude": [
      "_Total",
      "Idle"
    ],
    "threshold": {
      "400": "ok",
      "800": "warning",
      "*": "critical"
    },
    "stats": [
      "avg(60)"
    ]
  }
]

Formulas

You can apply any formula to a counter to transform its value:

"counters": [
  {
    "id": "\\Processor(_Total)\\% Processor Time",
    "name": "CPU Usage",
    "formula": "value / 2"
  }
]

This is particularly useful for the \\Process(*)\\% Processor Time counter to display its value in percentage:

lists: [
  {
    "name": "CPU Usage",
    "id": "\\Process(*)\\% Processor Time",
    "formula": "value / env.NUMBER_OF_PROCESSORS"
  }
]

Inside your formula, you can use the value and env variables to respectively access the counter's original value and a list of server's environment variables.

Variables

Sometimes you need to monitor a set of similar metrics for different applications (for example multiple ASP.NET web sites). Instead of creating a separate config file for each of these applications, you can create a single config file and use variables instead.

In your config file replace the name of the instance with your variable:

"counters": [
  "\\Web Service(%apppool%)\\Current Connections",
  "\\W3SVC_W3WP(%apppool%)\\Active Requests",
]

and supply a value for it at startup:

mon [<configfile>] --var apppool=mysite1
mon --server <address>:<port> [<configfile>] --var apppool=mysite1

Process IDs

By default, Performance Counters report multiple processes that have the same name by appending a number to their name (like w3wp#1, w3wp#2, etc).

To have them append the ID of the process instead (like w3wp_1234), follow the instructions in this article: KB281884.

This allows mon to map w3wp processes to their corresponding IIS application pools. Make sure to run mon as admin for this feature to work.

Version History

  • 1.3
    • Added timestamp to logs.
    • Fixed a bug that caused Perfmon to start twice on systems that IIS was not installed.
  • 1.2.1
    • Fixed a bug that caused mon not to start on systems that IIS was not installed.
  • 1.2
    • Added support for saving data to Elasticsearch.
    • Fixed a bug where Perfmon returned invalid data.
  • 1.1
    • Added support for formulas.
  • 1.0
    • Initial release

Author

Soheil Rashidi

Copyright and License

Copyright 2014-2018 Soheil Rashidi

Licensed under the The MIT License (the "License"); you may not use this work except in compliance with the License. You may obtain a copy of the License in the LICENSE file, or at:

http://www.opensource.org/licenses/mit-license.php

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.