{"id":18931551,"url":"https://github.com/mailru/graphite-nginx-module","last_synced_at":"2025-04-05T07:01:13.529Z","repository":{"id":14846400,"uuid":"17569441","full_name":"mailru/graphite-nginx-module","owner":"mailru","description":"An nginx module for collecting stats into Graphite","archived":false,"fork":false,"pushed_at":"2024-11-25T14:30:07.000Z","size":429,"stargazers_count":136,"open_issues_count":5,"forks_count":34,"subscribers_count":19,"default_branch":"master","last_synced_at":"2025-03-29T06:01:15.387Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mailru.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2014-03-09T17:28:40.000Z","updated_at":"2025-02-20T12:32:59.000Z","dependencies_parsed_at":"2024-04-17T12:53:14.963Z","dependency_job_id":"361e7b1a-e6dc-439e-93c9-f6008ab8c67d","html_url":"https://github.com/mailru/graphite-nginx-module","commit_stats":null,"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mailru%2Fgraphite-nginx-module","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mailru%2Fgraphite-nginx-module/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mailru%2Fgraphite-nginx-module/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mailru%2Fgraphite-nginx-module/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mailru","download_url":"https://codeload.github.com/mailru/graphite-nginx-module/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247299828,"owners_count":20916190,"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-08T11:42:34.144Z","updated_at":"2025-04-05T07:01:13.304Z","avatar_url":"https://github.com/mailru.png","language":"C","funding_links":[],"categories":["Logging and observability"],"sub_categories":[],"readme":"graphite-nginx-module\n=====================\n\nAn nginx module for collecting location stats into Graphite.\n\n*This module is not distributed with the Nginx source.* See [the installation instructions](#installation).\n\nFeatures\n========\n\n* Aggregation of location, server or http metrics\n* Calculation of percentiles\n* Sending data to Graphite over UDP or TCP in non-blocking way\n* Sending custom metrics from lua\n\nVersion\n=======\n\nThis document describes graphite-nginx-module [v2.3.0](https://github.com/mailru/graphite-nginx-module/tags) released on 21 August 2018.\n\nSynopsis\n========\n\n```nginx\n\nhttp {\n    graphite_config prefix=playground server=127.0.0.1;\n    server {\n        location /foo/ {\n            graphite_data nginx.foo;\n        }\n    }\n}\n```\n\nDescription\n===========\n\nThis module use shared memory segment to collect aggregated stats from all workers and send calculated values for last minute to Graphite every 60s (default) over UDP or TCP in non-blocking way.\nStats aggegation made on the fly in fixed size buffer allocated on server start and does't affect server performance.\n\nThis module is in active use on [Mail.Ru Sites](http://mail.ru/) (one of largest web-services in Russia) for about a year and considered stable and well-tested.\n\nTo collect metrics from nginx core modules (ssl, gzip, upstream) little patch must be applied on nginx source tree. See [the installation instructions](#installation).\nYou can build this module as a dynamic one, but then you won't be able to collect metrics from nginx core modules (ssl, gzip, upstream) and lua functions.\n\n\nDirectives\n==========\n\n### graphite_config\n\n**syntax:** *graphite_config key1=\u0026lt;value1\u0026gt; key2=\u0026lt;value2\u0026gt; ... keyN=\u0026lt;valueN\u0026gt;*\n\n**context:** *http*\n\nSpecify global settings for a whole server instance.\n\nParam     | Required | Default       | Description\n--------- | -------- | ------------- | -----------\nprefix    |          |               | path prefix for all graphs\nhost      |          | gethostname() | host name for all graphs\nserver    | Yes      |               | carbon-cache server IP address\nprotocol  |          | udp           | carbon-cache server protocol (udp or tcp)\nport      |          | 2003          | carbon-cache server port\nfrequency |          | 60            | how often send values to Graphite (seconds)\nintervals |          | 1m            | aggregation intervals, time interval list, vertical bar separator (`m` - minutes)\nparams    |          | *             | limit metrics list to track, vertical bar separator\nshared    |          | 2m            | shared memory size, increase in case of `too small shared memory` error\nbuffer    |          | 64k           | network buffer size, increase in case of `too small buffer size` error\npackage   |          | 1400          | maximum UDP packet size\ntemplate  |          |               | template for graph name (default is $prefix.$host.$split.$param_$interval) \nerror\\_log|          |               | path suffix for error logs graphs (\\*)\n\n(\\*): works only when nginx_error\\_log\\_limiting\\*.patch is applied to the nginx source code\n\nExample (standard):\n\n```nginx\nhttp {\n    graphite_config prefix=playground server=127.0.0.1;\n}\n```\n\nExample (custom):\n\n```nginx\nhttp {\n    graphite_config prefix=playground server=127.0.0.1 intervals=1m|5m|15m params=rps|request_time|upstream_time template=$prefix.$host.$split.$param_$interval;\n}\n```\n\nExample (error_log):\n\n```nginx\nhttp {\n    graphite_config prefix=playground server=127.0.0.1 error_log=log;\n}\n```\n\n### graphite_default_data\n\n**syntax:** *graphite_default_data \u0026lt;path prefix\u0026gt; [params=\u0026lt;params\u0026gt;] [if=\u0026lt;condition\u0026gt;]*\n\n**context:** *http, server*\n\nCreate measurement point in all nested locations.\nYou can use \"$location\" or \"$server\" variables which represent the name of the current location and the name of current server with all non-alphanumeric characters replaced with \"\\_.\" Leading and trailing \"\\_\" are deleted.\n\nExample:\n\n```nginx\n\n   graphite_default_data nginx.$location;\n\n   location /foo/ {\n   }\n\n   location /bar/ {\n   }\n```\n\nData for `/foo/` will be sent to `nginx.foo`, data for `/bar/` - to `nginx.bar`.\nThe `\u003cparams\u003e` parameter (1.3.0) specifies list of params to be collected for all nested locations. To add all default params, use \\*.\nThe `\u003cif\u003e` parameter (1.1.0) enables conditional logging. A request will not be logged if the condition evaluates to \"0\" or an empty string.\n\nExample(with $server):\n```nginx\n\n    graphite_default_data nginx.$server.$location\n\n    server {\n        server_name foo_host;\n\n        location /foo/ {\n        }\n    }\n\n    server {\n        server_name bar_host;\n\n        location /bar/ {\n        }\n    }\n```\n\nData for `/foo/` will be sent to `nginx.foo_host.foo`, data for `/bar/` - to `nginx.bar_host.bar`.\n\n### graphite_data\n\n**syntax:** *graphite_data \u0026lt;path prefix\u0026gt; [params=\u0026lt;params\u0026gt;] [if=\u0026lt;condition\u0026gt;]*\n\n**context:** *http, server, location, if*\n\nCreate measurement point in specific location.\n\nExample:\n\n```nginx\n\n    location /foo/ {\n        graphite_data nginx.foo;\n    }\n```\n\nThe `\u003cparams\u003e` parameter (1.3.0) specifies list of params to be collected for this location. To add all default params, use \\*.\nThe `\u003cif\u003e` parameter (1.1.0) enables conditional logging. A request will not be logged if the condition evaluates to \"0\" or an empty string.\n\nExample:\n\n```nginx\n\n    map $scheme $is_http { http 1; }\n    map $scheme $is_https { https 1; }\n\n    ...\n\n    location /bar/ {\n        graphite_data nginx.all.bar;\n        graphite_data nginx.http.bar if=$is_http;\n        graphite_data nginx.https.bar if=$is_https;\n        graphite_data nginx.arg params=rps|request_time;\n        graphite_data nginx.ext params=*|rps|request_time;\n    }\n```\n\n### graphite_param\n\n**syntax:** *graphite_param name=\u0026lt;path\u0026gt; interval=\u0026lt;time value\u0026gt; aggregate=\u0026lt;func\u0026gt;*\n\n**context:** *http, server, location, if*\n\nParam      | Required | Description\n---------- | -------- | -----------\nname       | Yes      | path prefix for all graphs\ninterval   | Yes\\*    | aggregation interval, time intrval value format (`m` - minutes)\naggregate  | Yes\\*    | aggregation function on values\npercentile | Yes\\*    | percentile level\n\n#### aggregate functions\nfunc   | Description\n------ | -----------\nsum    | sum of values per interval\npersec | sum of values per second  (`sum` divided on seconds in `interval`)\navg    | average value on interval\ngauge  | gauge value\n\nExample: see below.\n\nNginx API for Lua\n=================\n\n**syntax:** *ngx.graphite.param(\u0026lt;name\u0026gt;)*\n\nGet a link on a graphite parameter name, to use it in place of the name for the functions below.\nThe link is valid up to nginx reload. After getting the link of a parameter, you can still pass\nthe parameter name to the functions below. You can get the link of a parameter multiple times,\nyou'll always get the same object by the same name (a lightuserdata). The function returns false\nif the parameter specified by name doesn't exist. The function returns nil on link getting errors.\nFunctions access parameters information by link faster than by name.\n\n*Available after applying patch to lua-nginx-module.* The feature is present in the patch for lua\nmodule v0.10.12. See [the installation instructions](#build-nginx-with-lua-and-graphite-modules).\n\n**syntax:** *ngx.graphite(\u0026lt;name_or_link\u0026gt;,\u0026lt;value\u0026gt;[,\u0026lt;config\u0026gt;])*\n\nWrite stat value into aggregator function. Floating point numbers accepted in `value`.\n\n*Available after applying patch to lua-nginx-module.* See [the installation instructions](#build-nginx-with-lua-and-graphite-modules).\n\n```lua\nngx.graphite(name, value, config)\n```\n\nExample:\n\n```nginx\n\nlocation /foo/ {\n    graphite_param name=lua.foo_sum aggregate=sum interval=1m;\n    graphite_param name=lua.foo_rps aggregate=persec interval=1m;\n    graphite_param name=lua.foo_avg aggregate=avg interval=1m;\n    graphite_param name=lua.foo_gauge aggregate=gauge;\n\n    content_by_lua '\n        ngx.graphite(\"lua.foo_sum\", 0.01)\n        ngx.graphite(\"lua.foo_rps\", 1)\n        ngx.graphite(\"lua.foo_avg\", ngx.var.request_uri:len())\n        local foo_gauge_link = ngx.graphite.param(\"lua.foo_gauge\")\n        ngx.graphite(foo_gauge_link, 10)\n        ngx.graphite(foo_gauge_link, -2)\n        ngx.graphite(\"lua.auto_rps\", 1, \"aggregate=persec interval=1m percentile=50|90|99\")\n        ngx.say(\"hello\")\n    ';\n}\n```\n\nYou must either specify the `graphite_param` command or pass the `config` argument.\nIf you choose the second option, the data for this graph will not be sent until the first call to ngx.graphite.\n\n**Warning:**\nIf you do not declare graph using `graphite_param` command then memory for the graph will be allocated dynamically in module's shared memory.\nIf module's shared memory is exhausted while nginx is running, no new graphs will be created and an error message will be logged.\n\n**syntax:** *ngx.graphite.get(\u0026lt;name_or_link\u0026gt;)*\n\nGet value of the gauge param with specified `name_or_link`.\n\n**syntax:** *ngx.graphite.set(\u0026lt;name\u0026gt;,\u0026lt;value\u0026gt;)*\n\nSet `value` to the gauge param with specified `name_or_link`.\n\nParams\n======\n\nParam                   | Units | Func | Description\n----------------------- | ----- | ---- | ------------------------------------------\nrequest\\_time           | ms    | avg  | total time spent on serving request\nbytes\\_sent             | bytes | avg  | http response length\nbody\\_bytes\\_sent       | bytes | avg  | http response body length\nrequest\\_length         | bytes | avg  | http request length\nssl\\_handshake\\_time    | ms    | avg  | time spent on ssl handsake\nssl\\_cache\\_usage       | %     | last | how much SSL cache used\ncontent\\_time           | ms    | avg  | time spent generating content inside nginx\ngzip\\_time              | ms    | avg  | time spent gzipping content ob-the-fly\nlua\\_time               | ms    | avg  | time spent on lua code\nupstream\\_time          | ms    | avg  | time spent tailking with upstream\nupstream\\_connect\\_time | ms    | avg  | time spent on upstream connect (nginx \u003e= 1.9.1)\nupstream\\_header\\_time  | ms    | avg  | time spent on upstream header (nginx \u003e= 1.9.1)\nupstream\\_response\\_2xx\\_rps      | rps   | sum  | total upstream responses number with 2xx code (nginx \u003e= 1.9.1)\nupstream\\_response\\_3xx\\_rps      | rps   | sum  | total upstream responses number with 3xx code (nginx \u003e= 1.9.1)\nupstream\\_response\\_4xx\\_rps      | rps   | sum  | total upstream responses number with 4xx code (nginx \u003e= 1.9.1)\nupstream\\_response\\_5xx\\_rps      | rps   | sum  | total upstream responses number with 5xx code (nginx \u003e= 1.9.1)\nupstream\\_response\\_[0-9]{3}\\_rps | rps   | sum  | total upstream responses number with given code (nginx \u003e= 1.9.1)\nrps                     | rps   | sum  | total requests number per second\nkeepalive\\_rps          | rps   | sum  | requests number sent over previously opened keepalive connection\nresponse\\_2xx\\_rps      | rps   | sum  | total responses number with 2xx code\nresponse\\_3xx\\_rps      | rps   | sum  | total responses number with 3xx code\nresponse\\_4xx\\_rps      | rps   | sum  | total responses number with 4xx code\nresponse\\_5xx\\_rps      | rps   | sum  | total responses number with 5xx code\nresponse\\_[0-9]{3}\\_rps | rps   | sum  | total responses number with given code\nupstream\\_cache\\_(miss\\|bypass\\|expired\\|stale\\|updating\\|revalidated\\|hit)\\_rps | rps   | sum  | totar responses with a given upstream cache status\n\nPercentiles\n===========\n\nTo calculate percentile value for any parameter, set percentile level via `/`. E.g. `request_time/50|request_time/90|request_time/99`.\n\nInstallation\n============\n\n#### Requirements\n* nginx: 1.2.0 - 1.14.x\n* lua-nginx-module: 0.8.6 - 0.10.13 (optional)\n\n#### Build nginx with graphite module\n```bash\n\nwget 'http://nginx.org/download/nginx-1.9.2.tar.gz'\ntar -xzf nginx-1.9.2.tar.gz\ncd nginx-1.9.2/\n\n# patch to collect ssl_cache_usage, ssl_handshake_time content_time, gzip_time, upstream_time, upstream_connect_time, upstream_header_time graphs (optional)\npatch -p1 \u003c /path/to/graphite-nginx-module/graphite_module_v1_7_7.patch\n\n./configure --add-module=/path/to/graphite-nginx-module\n\nmake\nmake install\n```\n\n#### Build nginx with graphite dynamic module\n```bash\n\nwget 'http://nginx.org/download/nginx-1.9.2.tar.gz'\ntar -xzf nginx-1.9.2.tar.gz\ncd nginx-1.9.2/\n\n./configure --add-dynamic-module=/path/to/graphite-nginx-module\n\nmake\nmake install\n```\n\n#### Build nginx with lua and graphite modules\n```bash\n\nwget 'https://github.com/chaoslawful/lua-nginx-module/archive/v0.9.16.tar.gz'\ntar -xzf v0.9.16.tar.gz\ncd lua-nginx-module-0.9.16/\n# patch to add api for sending metrics from lua code (optional)\npatch -p1 \u003c /path/to/graphite-nginx-module/lua_module_v0_9_11.patch\ncd ..\n\nwget 'http://nginx.org/download/nginx-1.9.2.tar.gz'\ntar -xzf nginx-1.9.2.tar.gz\ncd nginx-1.9.2/\n\n# patch to collect ssl_cache_usage, ssl_handshake_time content_time, gzip_time, upstream_time, upstream_connect_time, upstream_header_time graphs (optional)\npatch -p1 \u003c /path/to/graphite-nginx-module/graphite_module_v1_7_7.patch\n\n./configure \\\n    --add-module=/path/to/ngx_devel_kit \\\n    --add-module=/path/to/lua-nginx-module \\\n    --add-module=/path/to/graphite-nginx-module\n\nmake\nmake install\n```\n\nInstructions on installing lua-nginx-module can be found in [documentation on lua-nginx-module](https://github.com/chaoslawful/lua-nginx-module#installation).\n\nLicense\n=======\n\nCopyright (c) 2013-2018, Mail.Ru Ltd.\n\nThis module is licensed under the terms of the BSD license.\n\nRedistribution and use in source and binary forms, with or without\nmodification, are permitted provided that the following conditions\nare met:\n\n* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.\n* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.\n\nTHIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS\n\"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT\nLIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR\nA PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT\nHOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,\nSPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED\nTO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR\nPROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF\nLIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING\nNEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS\nSOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmailru%2Fgraphite-nginx-module","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmailru%2Fgraphite-nginx-module","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmailru%2Fgraphite-nginx-module/lists"}