From a28e1549cebdd549bee94bedd63a9bd412361f1c Mon Sep 17 00:00:00 2001 From: Liu Lantao Date: Sat, 12 May 2018 01:59:24 +0800 Subject: [PATCH] Update documents to reflect the latest changes Signed-off-by: Liu Lantao --- README.md | 58 +++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 43 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 714d371..075c550 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,29 @@ # About -Monitor the incoming and outgoing traffic metrics in realtime for NGINX http subsystem. +Monitor the incoming and outgoing traffic metrics in realtime for `NGINX` http subsystem. Realtime traffic and status code monitor solution for NGINX, need less memory and cpu than realtime log analyzing. Useful for http traffic accounting based on NGINX config logic ( by-location or by-server or by-user-defined-variable ). +## Why? + +Real-time log analysis solution, +which requires multiple machines for storage and analysis, +are too heavy for application monitoring. + +An cost-effective solution is needed to monitor the traffic metrics/status of application requests. +That solution should be accurate, sensitive, robust, light weight enough, and not affected by traffic peaks. + +## How it works? + +The context of this module keeps a list of **metrics** identified by `accounting_id`. + +When a new **request** hits the server, the module will try to find its `accounting_id`, calculate statistics, and **aggregate** them into the corresponding metrics. + +For every period (defined by `interval`), a timer event is triggered, these metrics are rotated and exported to log files or remote log servers. + +--- + # Installation [![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2FLax%2Fnginx-http-accounting-module.svg?type=shield)](https://app.fossa.io/projects/git%2Bgithub.com%2FLax%2Fnginx-http-accounting-module?ref=badge_shield) @@ -65,12 +84,19 @@ http_accounting http_accounting_log -------------------- -**syntax:** *http_accounting_log \* +**syntax:** *http_accounting_log \ \[level]* **default:** *-* **context:** *http* +Configures logging. +Support both local `file` path, or `stderr`, or `syslog:`. +The second parameter is the log level. +For more details of supported params, refer to [this page from nginx.org](http://nginx.org/en/docs/ngx_core_module.html#error_log). + +If not specified, accounting log will be written to `/dev/log`. + http_accounting_id -------------------- **syntax:** *http_accounting_id \* @@ -79,9 +105,8 @@ http_accounting_id **context:** *server, location, if in location* -Specifies current request belongs to which accounting_id. - -This directive was first introduced in the v0.1 release, and can use variable in v1.0 and above. +Sets the `accounting_id` string by user defined variable. +This string is used to determine which `metrics` a request/session should be aggregated to. http_accounting_interval ------------------------ @@ -105,11 +130,14 @@ Randomly staggers the reporting interval by 20% from the usual time. # Usage -This module writes statistics to syslog. You should edit your syslog configuration. +This module can be configured to writes statistics to local file, remote log server or local syslog device. + +To collect logs with syslog, +refer [Lax/ngx_http_accounting_module-utils](http://github.com/Lax/ngx_http_accounting_module-utils) to for sample configuration / utils. -For sample configuration / utils, see: [Lax/ngx_http_accounting_module-utils](http://github.com/Lax/ngx_http_accounting_module-utils) +Some open-source log-aggregation software such as logstash also support syslog input, which will help you establish a central log server. -## Sample syslog output +## Metrics log format Apr 8 11:19:46 localhost NgxAccounting: pid:8555|from:1428463159|to:1428463186|accounting_id:default|requests:10|bytes_in:1400|bytes_out:223062|latency_ms:1873|upstream_latency_ms:1873|200:9|302:1 @@ -119,18 +147,18 @@ The output contains a list of k/v for the accounting metrics, in the sequence of |------------------|----------| | `pid` | pid of nginx worker process | | `from` / `to` | metric was collected between these timestamps | -| `accounting_id` | identify for the accounting unit, you name it with `http_accounting_id` directive | -| `requests` | count of total requests processed | +| `accounting_id` | identify the accounting unit, set with `http_accounting_id` directive | +| `requests` | count of total requests processed in current period | | `bytes_in` | total bytes receiverd by the server | | `bytes_out` | total bytes send out by the server | -| `latency_ms` | a sum of `$request_time`, in `millisecond` | -| `upstream_latency_ms` | a sum of `$upstream_response_time`, in `millisecond` | -| `200` / `302` / `400` / `404` / `500` ... | count of requests which response is with http code `200`/`302`/`400`/`404`/`500`, etc | +| `latency_ms` | sum of `$request_time`, in `millisecond` | +| `upstream_latency_ms` | sum of `$upstream_response_time`, in `millisecond` | +| `200` / `302` / `400` / `404` / `500` ... | count of requests with http status code `200`/`302`/`400`/`404`/`500`, etc | # Branches -* master : new feathers -* v2-freeze-20110526 : works with nginx version(0.7.xx, 0.8.xx), nginx 0.9 is not tested. didn't work with nginx above 1.0.x. +* master : main development branch. +* v2-freeze-20110526 : legacy release. works with nginx version(0.7.xx, 0.8.xx), nginx 0.9 is not tested. didn't work with nginx above 1.0.x. # Contributing