<commit_before><div align="center">
  <img width="300" heigth="300" src="https://github.com/hyj1991/assets/blob/master/easy-monitor/logo.png" alt="easy-monitor logo">
</div>

[![npm version](https://badge.fury.io/js/easy-monitor.svg)](https://badge.fury.io/js/easy-monitor)
[![Package Quality](http://npm.packagequality.com/shield/easy-monitor.svg)](http://packagequality.com/#?package=easy-monitor)
[![npm](https://img.shields.io/npm/dt/easy-monitor.svg)](https://www.npmjs.com/package/easy-monitor)
[![license](https://img.shields.io/github/license/mashape/apistatus.svg)](LICENSE)

# Easy-Monitor
[中文版](README.md)

## Introduction

A lightweight Node.js performance monitoring tool, you just need to ```require``` it at the entrance of your project, then ```Easy-Monitor``` will show you your Node.js process details.

### I.Functions

* **Find 5 or more functions that take the longest execution time**
* **Find functions that perform more than expected**
* **Find the functions which V8 engine can not optimize**

The number of listings disaplayed above can be configured directly in URL.
You can also set your own rule that you can fiter **functions** and **filePaths** so that the results is what you really want.

The purpose of ```Easy-Monitor``` is to help you more in-depth understanding of our Node process, performance optimization can be more targeted, and ultimately enhance our project experience.


### II.Feature

* **LightWeight**：```Easy-Monitor``` is unconventional C/S physical separation model，all you need to to is ```require``` in your project，there is no additional server/agent deployment costs.

* **RunTime**：```Easy-Monitor``` can provide you runtime performance and memory details, and it can be used for production.

* **Stateless**：```Easy-Monitor``` always show you your node process status when you visit it.

## Compatibility
* Node v6.x
* Node v5.x
* Node v4.x

Temporary don't support Node v7.x.

## Quick Start

```Easy-Monitor``` is simple，only three steps you can start your own performance monitor.

### I.Install

Simply run as：

```bash
npm install easy-monitor
```

### II.Require

Require in your project，argument is your project name, such as:

```js
const easyMonitor = require('easy-monitor');
easyMonitor('your project name');
```

### III.Visit

Open browser, input as below, then you will see detail:

```bash
http://127.0.0.1:12333
```

### IV.A thorough example with Express

```js
'use strict';
const easyMonitor = require('easy-monitor');
easyMonitor('your project name');
const express = require('express');
const app = express();

app.get('/hello', function (req, res, next) {
    res.send('hello');
});

app.listen(8082);
```

Save the above as a JS file, then open your browser and visit ```http://127.0.0.1:12333```, just so simple!

## Customization

### I.Customization Parameters

```Easy-Monitor``` also remain some important
attributes so that we can customize conveniently, it's dependence on the object you set  when executing ```require('easy-monitor')(object)```, this object  can have below attributes as:

* **logLevel**：Number，default is 2，it used to set log level：
	* 0：don't output any log
	* 1：output error log
	* 2：output info log
	* 3：output debug log

* **appName**：String, default is getting from process.title, it used to set your project name.

* **httpServerPort**：Numver, default is 12333, it used to set monitor http server port.

* **filterFunction**：function，default filtering out the profiling results of the 'node_modules' and 'anonymous', and all file paths that don't have the string '/', because of these may be system functions.
Developer can write function to filter your own results, below is the params and returned value:
	* filePath: String, file path that functions at
	* funcName: String, function name
	* returned value: if true remain, if false filtering out

* **monitorAuth**：function，default don't authentication，it used for authentication, developer can write function for own authentication, below is the params and returned value:
	* user：String, it's username
	* pass：String, it's password
	* returned value：a Promise instance，resolve(true) mean authentication pass, resolve(false) or reject mean authentication failed.

### II.Customization Example

Below is a thorough example that ```Easy-Monitor``` with Express：

```js
'use strict';
const easyConfig = {
    logLevel: 3,
    appName: 'My Project 1',
    httpServerPort: 8888,
    filterFunction: function (filePath, funcName) {
        if (funcName === 'anonymous' || ~filePath.indexOf('node_modules')) {
            return false;
        }
        return Boolean(/^\(\/.*/.test(filePath));
    },
    monitorAuth: function (user, pass) {
        return new Promise(resolve => resolve(Boolean(user === 'admin' && pass === '<PASSWORD>')));
    }
};
const easyMonitor = require('easy-monitor');
easyMonitor(easyConfig);

const express = require('express');
const app = express();

app.get('/hello', function helloIndex(req, res, next) {
    let date = Date.now();
    while (Date.now() - date < 300) {
    }
    res.send('hello');
});

app.listen(8082);
```

In this example, log level setted to 3, monitor http server port changed to 8888, also set own filtering rule and simply authentication rule.

More, ```/hello``` setted being blocking after 300ms, you can open ```http://127.0.0.1:8888``` to visit ```Easy-Monitor``` home page, to click the project name or pid, then it will do cpu profiling, meanwhile you can visit ```http://1172.16.17.32:8082/hello``` ceaselessly.

After all, you'll get result by trying it.

## Monitor Page Preview

### I.HomePage

#### 1.Profiling The Whole Project

<img width="550" heigth="300" src="https://github.com/hyj1991/assets/blob/master/easy-monitor/Index_Project.jpeg" alt="Index_Project">

As above picture, you can click the project name, this will profiling the **whole project's process**, include:
* single process mode: only main process
* cluster mode: all cluster process

#### 2.查看项目下某一个子进程

<img width="550" heigth="300" src="https://github.com/hyj1991/assets/blob/master/easy-monitor/Index_Pid.jpeg" alt="Index_Pid">

如图，在cluster模式下项目会有多个子进程，点击某一个特定的pid，则只会对 **此pid对应的子进程** 进行profiling操作。

#### 3.多项目部署

<img width="550" heigth="300" src="https://github.com/hyj1991/assets/blob/master/easy-monitor/Index_Multi.jpeg" alt="Index_Multi">

如图，```Easy-Monitor``` **支持多项目部署**，用法和单项目是一模一样的，可以参考前面的快速开始。那么多项目启动后，监控页面会展示出不同的项目名称和对应的子进程pid。<commit_msg>add English README.md<commit_after><div align="center">
  <img width="300" heigth="300" src="https://github.com/hyj1991/assets/blob/master/easy-monitor/logo.png" alt="easy-monitor logo">
</div>

[![npm version](https://badge.fury.io/js/easy-monitor.svg)](https://badge.fury.io/js/easy-monitor)
[![Package Quality](http://npm.packagequality.com/shield/easy-monitor.svg)](http://packagequality.com/#?package=easy-monitor)
[![npm](https://img.shields.io/npm/dt/easy-monitor.svg)](https://www.npmjs.com/package/easy-monitor)
[![license](https://img.shields.io/github/license/mashape/apistatus.svg)](LICENSE)

# Easy-Monitor
[中文版](README.md)

## Introduction

A lightweight Node.js performance monitoring tool, you just need to ```require``` it at the entrance of your project, then ```Easy-Monitor``` will show you your Node.js process details.

### I.Functions

* **Find 5 or more functions that take the longest execution time**
* **Find functions that perform more than expected**
* **Find the functions which V8 engine can not optimize**

The number of listings disaplayed above can be configured directly in URL.
You can also set your own rule that you can fiter **functions** and **filePaths** so that the results is what you really want.

The purpose of ```Easy-Monitor``` is to help you more in-depth understanding of our Node process, performance optimization can be more targeted, and ultimately enhance our project experience.


### II.Feature

* **LightWeight**：```Easy-Monitor``` is unconventional C/S physical separation model，all you need to to is ```require``` in your project，there is no additional server/agent deployment costs.

* **RunTime**：```Easy-Monitor``` can provide you runtime performance and memory details, and it can be used for production.

* **Stateless**：```Easy-Monitor``` always show you your node process status when you visit it.

## Compatibility
* Node v6.x
* Node v5.x
* Node v4.x

Temporary don't support Node v7.x.

## Quick Start

```Easy-Monitor``` is simple，only three steps you can start your own performance monitor.

### I.Install

Simply run as：

```bash
npm install easy-monitor
```

### II.Require

Require in your project，argument is your project name, such as:

```js
const easyMonitor = require('easy-monitor');
easyMonitor('your project name');
```

### III.Visit

Open browser, input as below, then you will see detail:

```bash
http://127.0.0.1:12333
```

### IV.A thorough example with Express

```js
'use strict';
const easyMonitor = require('easy-monitor');
easyMonitor('your project name');
const express = require('express');
const app = express();

app.get('/hello', function (req, res, next) {
    res.send('hello');
});

app.listen(8082);
```

Save the above as a JS file, then open your browser and visit ```http://127.0.0.1:12333```, just so simple!

## Customization

### I.Customization Parameters

```Easy-Monitor``` also remain some important
attributes so that we can customize conveniently, it's dependence on the object you set  when executing ```require('easy-monitor')(object)```, this object  can have below attributes as:

* **logLevel**：Number，default is 2，it used to set log level：
	* 0：don't output any log
	* 1：output error log
	* 2：output info log
	* 3：output debug log

* **appName**：String, default is getting from process.title, it used to set your project name.

* **httpServerPort**：Numver, default is 12333, it used to set monitor http server port.

* **filterFunction**：function，default filtering out the profiling results of the 'node_modules' and 'anonymous', and all file paths that don't have the string '/', because of these may be system functions.
Developer can write function to filter your own results, below is the params and returned value:
	* filePath: String, file path that functions at
	* funcName: String, function name
	* returned value: if true remain, if false filtering out

* **monitorAuth**：function，default don't authentication，it used for authentication, developer can write function for own authentication, below is the params and returned value:
	* user：String, it's username
	* pass：String, it's password
	* returned value：a Promise instance，resolve(true) mean authentication pass, resolve(false) or reject mean authentication failed.

### II.Customization Example

Below is a thorough example that ```Easy-Monitor``` with Express：

```js
'use strict';
const easyConfig = {
    logLevel: 3,
    appName: 'My Project 1',
    httpServerPort: 8888,
    filterFunction: function (filePath, funcName) {
        if (funcName === 'anonymous' || ~filePath.indexOf('node_modules')) {
            return false;
        }
        return Boolean(/^\(\/.*/.test(filePath));
    },
    monitorAuth: function (user, pass) {
        return new Promise(resolve => resolve(Boolean(user === 'admin' && pass === '<PASSWORD>')));
    }
};
const easyMonitor = require('easy-monitor');
easyMonitor(easyConfig);

const express = require('express');
const app = express();

app.get('/hello', function helloIndex(req, res, next) {
    let date = Date.now();
    while (Date.now() - date < 300) {
    }
    res.send('hello');
});

app.listen(8082);
```

In this example, log level setted to be 3, monitor http server port changed to be 8888, we also set our own filtering rule and simply authentication rule.

More, ```/hello``` setted being blocking after 300ms, you can open ```http://12172.16.31.10:8888``` to visit ```Easy-Monitor``` home page, to click the project name or pid, then it will do cpu profiling, meanwhile you can visit ```http://127.0.0.1:8082/hello``` ceaselessly.

After all, you'll get result by trying it.

## Monitor Page Preview

### I.HomePage

#### 1.Profiling The Whole Project

<img width="550" heigth="300" src="https://github.com/hyj1991/assets/blob/master/easy-monitor/Index_Project.jpeg" alt="Index_Project">

As the picture, you can click the project name, this will profiling the **whole project's process**, include:
* single process mode: only main process
* cluster mode: all cluster process

#### 2.Profiling The Unique Process

<img width="550" heigth="300" src="https://github.com/hyj1991/assets/blob/master/easy-monitor/Index_Pid.jpeg" alt="Index_Pid">

As the picture, there will be multiple child process in cluster mode, you can click unique pid, this will profiling the **unique process** only. 

#### 3.Multi Project Deployment

<img width="550" heigth="300" src="https://github.com/hyj1991/assets/blob/master/easy-monitor/Index_Multi.jpeg" alt="Index_Multi">

As the picture, ```Easy-Monitor``` **suppirt multi project deployment**, the usage is exactly the same as the single project, you can refer to Quick Start.

When you deploy multi projects, monitor homepage will display these different project and their child process pid.
{'fraction_non_alphanumeric': 0.13483061101028432, 'fraction_numerical': 0.019736842105263157, 'mean_word_length': 4.745004344048653, 'pattern_counts': {'":': 0, '<': 19, '<?xml version=': 0, '>': 19, 'https://': 18, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 8, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4279500', 'n_tokens_mistral': 4238, 'n_tokens_neox': 3889, 'n_words': 1412}