{"id":13523231,"url":"https://github.com/influxdata/nginx-influxdb-module","last_synced_at":"2025-04-11T01:32:30.386Z","repository":{"id":34422204,"uuid":"38354286","full_name":"influxdata/nginx-influxdb-module","owner":"influxdata","description":null,"archived":false,"fork":false,"pushed_at":"2023-06-30T15:08:52.000Z","size":73,"stargazers_count":39,"open_issues_count":9,"forks_count":13,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-24T22:42:01.516Z","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":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/influxdata.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2015-07-01T06:38:16.000Z","updated_at":"2024-04-17T16:07:37.000Z","dependencies_parsed_at":"2024-01-13T21:53:09.610Z","dependency_job_id":null,"html_url":"https://github.com/influxdata/nginx-influxdb-module","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/influxdata%2Fnginx-influxdb-module","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/influxdata%2Fnginx-influxdb-module/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/influxdata%2Fnginx-influxdb-module/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/influxdata%2Fnginx-influxdb-module/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/influxdata","download_url":"https://codeload.github.com/influxdata/nginx-influxdb-module/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248325282,"owners_count":21084901,"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-08-01T06:00:57.465Z","updated_at":"2025-04-11T01:32:30.363Z","avatar_url":"https://github.com/influxdata.png","language":"C","funding_links":[],"categories":["C"],"sub_categories":[],"readme":"# NGINX InfluxDB Module :unicorn:\n\nA module to monitor request passing trough an NGINX server by sending\nevery request to an InfluxDB backend exposing UDP.\n\n## Exported Fields (per request)\n\n| Metric                | Type    | Description                                                                                                                                |\n|-----------------------|---------|--------------------------------------------------------------------------------------------------------------------------------------------|\n| method                | string  | The HTTP request method that has been given as a reply to the caller                                                                       |\n| status                | integer | The HTTP status code of the reply from the server (refer to [RFC 7231](https://tools.ietf.org/html/rfc7231#section-6.1) for more details)  |\n| bytes_sent            | integer | The number of bytes sent to a client body + header                                                                                         |\n| body_bytes_sent       | integer | The number of bytes sent to a client only for body                                                                                         |\n| header_bytes_sent     | integer | The number of bytes sent to a client for header and body                                                                                   |\n| request_length        | integer | Request length (including request line, header, and request body)                                                                          |\n| uri                   | string  | The called uri (e.g: /index.html)                                                                                                          |\n| extension             | string  | The extension of the served file (e.g: js, html, php, png)                                                                                 |\n| content_type          | string  | The content type of the response (e.g: text/html)                                                                                          |\n| request_time          | string  | Request processing time in seconds with a milliseconds resolution                                                                          |\n\n\n## Dynamic fields (per request)\n\nYou can enrich the exported field set with some custom fields using the `influxdb_dynamic_fields` directive.\nYour fields need to be compliant with the line protocol in terms of type and quoting, see [here](https://docs.influxdata.com/influxdb/v1.6/write_protocols/line_protocol_tutorial/#field-set)\nfor more details.\n\nThis means that if you use a string in the directive it must be double quoted, like:\n\n```\ninfluxdb_dynamic_fields myfield=\"mystring\";\n```\n\nIf you are using a variable to populate that field it must meet the same criteria as a normal string:\n\n```\nset namespace myapp\ninfluxdb_dynamic_fields namespace=\"$namespace\";\n```\n\nOn the other end, an integer doesn't want to be escaped:\n\n```\ninfluxdb_dynamic_fields namespace=100;\n```\n\nBut since InfluxDB assumes that all numerical field values are float you might want to specify that it is an integer instead\nif your numeric value is:\n\n```\ninfluxdb_dynamic_fields namespace=100i;\n```\n\nIf you want to know more about Data types supported in line protocol read the [Data Types](https://docs.influxdata.com/influxdb/v1.6/write_protocols/line_protocol_tutorial/#data-types) section\nin the line protocol documentation.\n\nPlease remember that the metrics are sent after the request is processed so if a metric fails to be ingested by InfluxDB\nbecause of line protocol formatting you will not have it in the database, refer to the logs in that case.\n\nThe module doesn't do any quotes escaping or check on dynamic fields for performances reasons.\n\n## Installation\n\n## With dynamic modules\n\nBuild dynamic module with local Nginx:\n```\nmkdir build\npushd build\ngit clone http://github.com/influxdata/nginx-influxdb-module.git\nwget -nv -O - https://nginx.org/download/nginx-1.16.0.tar.gz | tar zx\npushd nginx-1.16.0\neval \"./configure --add-dynamic-module=../nginx-influxdb-module $(nginx -V 2\u003e\u00261 \u003e/dev/null | grep  -o '\\--with.*')\"\nmake modules\npopd\npopd\n```\n\nAdd to local Nginx:\n```\nsed -i -e \"1 s/^/load_module \\\\/nginx-1.16.0\\\\/objs\\\\/ngx_pagespeed.so\\\\; \\\\n/;\" /etc/nginx/nginx.conf\nnginx -s reload\n```\n\n## Build the module statically with NGINX\n\n```\nmkdir build\npushd build\ngit clone http://github.com/influxdata/nginx-influxdb-module.git\nwget -nv -O - https://nginx.org/download/nginx-1.16.0.tar.gz | tar zx\npushd nginx-1.16.0\n./configure --add-module=../nginx-influxdb-module\nmake -j\npopd\npopd\n```\n\n## Configuration\n\nTo configure it you just need the `influxdb` directive.\n\nPlease **be aware** that you are configuring the module to write to InfluxDB via UDP,\nthis means that `host` can only be an IP address and not an hostname and that the port\nis configured to serve a database via UDP.\n\n\n### Pre-defined fields example\n\n```\ninfluxdb server_name=myserver host=127.0.0.1 port=8089 measurement=mymeasures enabled=true;\n```\n\nIf you don't want to expose InfluxDB via UDP you can start a Telegraf bound to `127.0.0.1`\nthat is exposing UDP using the [socket listener service](https://github.com/influxdata/telegraf/tree/release-1.6/plugins/inputs/socket_listener) plugin, then you can send the data via HTTP to your InfluxDB using the [InfluxDB Output Plugin](https://github.com/influxdata/telegraf/tree/1.8.0/plugins/outputs/influxdb). The approach using telegraf on localhost has the advantage that you can \"offload\" requests to Influx, you can send requests in batch using a time window and that since `127.0.0.1` is on the `loopback` interface you have an MTU of `65536` that is extremely higher than the usual `1500`.\n\nYou can find a sample configuration for InfluxDB to expose UDP in [hack/influxdb.conf](hack/influxdb.conf).\n\n### Dynamic fields example\n\n```\n# Normally you have only this\ninfluxdb server_name=myserver host=127.0.0.1 port=8089 measurement=mymeasures enabled=true\n\n# If you want to use dynamic fields too\nset namespace myapp\ninfluxdb_dynamic_fields namespace=\"$server_name\" user_agent=\"$http_user_agent\" myinteger=10000;\n```\n\n### Full Example\n\nA full example config looks like this\n\n```nginx\nuser  nginx;\nworker_processes  auto;\ndaemon off;\n\n#load_module path/to/the/module/ngx_http_influxdb_module.so; needed if a dynamic module\npid        /var/run/nginx/nginx.pid;\n\n\nevents {\n    worker_connections  1024;\n}\n\nhttp {\n    include       /etc/nginx/mime.types;\n    default_type  application/octet-stream;\n\n    sendfile        on;\n\n    keepalive_timeout  65;\n\n    server {\n        listen       8080;\n        server_name  localhost;\n        location / {\n            root   /usr/share/nginx/html;\n            influxdb server_name=myserver host=127.0.0.1 port=8089 measurement=mymeasures enabled=true;\n            influxdb_dynamic_fields namespace=\"mynamespace\" server_name=\"$server_name\" user_agent=\"$http_user_agent\" myinteger=10000;\n            index  index.html index.htm;\n        }\n\n        error_page   500 502 503 504  /50x.html;\n        location = /50x.html {\n            root   /usr/share/nginx/html;\n        }\n    }\n\n}\n\n```\n\n\n### Local Testing\n\nTo test changes locally, there's a script in `hack/` called `build-start.sh` that can\nbuild the local changes against the current nginx source code taken from github.\n\nTo run, the script also requires docker in order to start influxdb, chronograf and other testing proxy backends\n\n```bash\n./hack/build-start.sh\n```\n\n- You can reach chronograf (through nginx) at `http://127.0.0.1:8082/`\n- You can reach chronograf (directly) at `http://127.0.0.1:8888/`\n- A static hello world page can be reached at `http://127.0.0.1:8080`\n\n\nYou can access the influxdb instance CLI via:\n\n```bash\n docker exec -it test-nginx-influxdb influx\n```\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finfluxdata%2Fnginx-influxdb-module","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finfluxdata%2Fnginx-influxdb-module","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finfluxdata%2Fnginx-influxdb-module/lists"}