README.md
1# php-fpm_exporter
2
3
4[](https://goreportcard.com/report/github.com/hipages/php-fpm_exporter)
5[](https://godoc.org/github.com/hipages/php-fpm_exporter)
6[](https://sonarcloud.io/dashboard?id=hipages_php-fpm_exporter)
7[](https://hub.docker.com/r/hipages/php-fpm_exporter/)
8[](http://isitmaintained.com/project/hipages/php-fpm_exporter "Average time to resolve an issue")
9[](http://isitmaintained.com/project/hipages/php-fpm_exporter "Percentage of issues still open")
10[](https://www.codetriage.com/hipages/php-fpm_exporter)
11[](#contributors)
12
13A [prometheus](https://prometheus.io/) exporter for PHP-FPM.
14The exporter connects directly to PHP-FPM and exports the metrics via HTTP.
15
16A webserver such as NGINX or Apache is **NOT** needed!
17
18## Table of Contents
19
20<!-- toc -->
21
22- [Features](#features)
23- [Usage](#usage)
24 * [Options and defaults](#options-and-defaults)
25 * [Why `--phpfpm.fix-process-count`?](#why---phpfpmfix-process-count)
26 * [CLI Examples](#cli-examples)
27 * [Docker Examples](#docker-examples)
28 * [Kubernetes Example](#kubernetes-example)
29- [Metrics collected](#metrics-collected)
30- [Grafana Dasbhoard for Kubernetes](#grafana-dasbhoard-for-kubernetes)
31- [FAQ](#faq)
32- [Development](#development)
33 * [E2E Tests](#e2e-tests)
34- [Contributing](#contributing)
35- [Contributors](#contributors)
36- [Alternatives](#alternatives)
37
38<!-- tocstop -->
39
40## Features
41
42* Export single or multiple pools
43* Export to CLI as text or JSON
44* Connects directly to PHP-FPM via TCP or Socket
45* Maps environment variables to CLI options
46* Fix for PHP-FPM metrics oddities
47* [Grafana Dashboard](https://grafana.com/dashboards/4912) for Kubernetes
48
49## Usage
50
51`php-fpm_exporter` is released as [binary](https://github.com/hipages/php-fpm_exporter/releases) and [docker](https://hub.docker.com/r/hipages/php-fpm_exporter/) image.
52It uses sensible defaults which usually avoids the need to use command parameters or environment variables.
53
54`php-fpm_exporter` supports 2 commands, `get` and `server`.
55The `get` command allows to retrieve information from PHP-FPM without running as a server and exposing an endpoint.
56The `server` command runs the server required for prometheus to retrieve the statistics.
57
58### Options and defaults
59
60| Option | Description | Environment variable | Default value |
61|------------------------|-------------------------------------------------------|------------------------------|-----------------|
62| `--web.listen-address` | Address on which to expose metrics and web interface. | `PHP_FPM_WEB_LISTEN_ADDRESS` | [`:9253`](https://github.com/prometheus/prometheus/wiki/Default-port-allocations) |
63| `--web.telemetry-path` | Path under which to expose metrics. | `PHP_FPM_WEB_TELEMETRY_PATH` | `/metrics` |
64| `--phpfpm.scrape-uri` | FastCGI address, e.g. unix:///tmp/php.sock;/status or tcp://127.0.0.1:9000/status | `PHP_FPM_SCRAPE_URI` | `tcp://127.0.0.1:9000/status` |
65| `--phpfpm.fix-process-count` | Enable to calculate process numbers via php-fpm_exporter since PHP-FPM sporadically reports wrong active/idle/total process numbers. | `PHP_FPM_FIX_PROCESS_COUNT`| `false` |
66| `--log.level` | Only log messages with the given severity or above. Valid levels: [debug, info, warn, error, fatal] (default "error") | `PHP_FPM_LOG_LEVEL` | info |
67
68### Why `--phpfpm.fix-process-count`?
69
70`php-fpm_exporter` implements an option to "fix" the reported metrics based on the provided processes list by PHP-FPM.
71
72We have seen PHP-FPM provide metrics (e.g. active processes) which don't match reality.
73Specially `active processes` being larger than `max_children` and the actual number of running processes on the host.
74Looking briefly at the source code of PHP-FPM it appears a scoreboard is being kept and the values are increased/decreased once an action is executed.
75The metric `active processes` is also an accumulation of multiple states (e.g. Reading headers, Getting request information, Running).
76Which shouldn't matter and `active processes` should still be equal or lower to `max_children`.
77
78`--phpfpm.fix-process-count` will emulate PHP-FPMs implementation including the accumulation of multiple states.
79
80If you like to have a more granular reporting please use `phpfpm_process_state`.
81
82* https://bugs.php.net/bug.php?id=76003
83* https://stackoverflow.com/questions/48961556/can-active-processes-be-larger-than-max-children-for-php-fpm
84
85### CLI Examples
86
87* Retrieve information from PHP-FPM running on `127.0.0.1:9000` with status endpoint being `/status`
88 ```
89 php-fpm_exporter get
90 ```
91
92* Retrieve information from PHP-FPM running on `127.0.0.1:9000` and `127.0.0.1:9001`
93 ```
94 php-fpm_exporter get --phpfpm.scrape-uri tcp://127.0.0.1:9000/status,tcp://127.0.0.1:9001/status
95 ```
96
97* Run as server with 2 pools:
98 ```
99 php-fpm_exporter server --phpfpm.scrape-uri tcp://127.0.0.1:9000/status,tcp://127.0.0.1:9001/status
100 ```
101
102* Run as server and enable process count fix via environment variable:
103 ```
104 PHP_FPM_FIX_PROCESS_COUNT=1 go run main.go server --web.listen-address ":12345" --log.level=debug
105 ```
106
107### Docker Examples
108
109* Run docker manually
110 ```
111 docker pull hipages/php-fpm_exporter
112 docker run -it --rm -e PHP_FPM_SCRAPE_URI="tcp://127.0.0.1:9000/status,tcp://127.0.0.1:9001/status" hipages/php-fpm_exporter
113 ```
114
115* Run the docker-compose example
116 ```
117 git clone git@github.com:hipages/php-fpm_exporter.git
118 cd php-fpm_exporter/test
119 docker-compose -p php-fpm_exporter up
120 ```
121 You can now access the following links:
122
123 * Prometheus: http://127.0.0.1:9090/
124 * php-fpm_exporter metrics: http://127.0.0.1:9253/metrics
125
126 [](https://asciinema.org/a/1msR8nqAsFdHzROosUb7PiHvf)
127
128### Kubernetes Example
129
130TBD
131
132## Metrics collected
133
134```
135# HELP phpfpm_accepted_connections The number of requests accepted by the pool.
136# TYPE phpfpm_accepted_connections counter
137# HELP phpfpm_active_processes The number of active processes.
138# TYPE phpfpm_active_processes gauge
139# HELP phpfpm_idle_processes The number of idle processes.
140# TYPE phpfpm_idle_processes gauge
141# HELP phpfpm_listen_queue The number of requests in the queue of pending connections.
142# TYPE phpfpm_listen_queue gauge
143# HELP phpfpm_listen_queue_length The size of the socket queue of pending connections.
144# TYPE phpfpm_listen_queue_length gauge
145# HELP phpfpm_max_active_processes The maximum number of active processes since FPM has started.
146# TYPE phpfpm_max_active_processes counter
147# HELP phpfpm_max_children_reached The number of times, the process limit has been reached, when pm tries to start more children (works only for pm 'dynamic' and 'ondemand').
148# TYPE phpfpm_max_children_reached counter
149# HELP phpfpm_max_listen_queue The maximum number of requests in the queue of pending connections since FPM has started.
150# TYPE phpfpm_max_listen_queue counter
151# HELP phpfpm_process_last_request_cpu The %cpu the last request consumed.
152# TYPE phpfpm_process_last_request_cpu gauge
153# HELP phpfpm_process_last_request_memory The max amount of memory the last request consumed.
154# TYPE phpfpm_process_last_request_memory gauge
155# HELP phpfpm_process_request_duration The duration in microseconds of the requests.
156# TYPE phpfpm_process_request_duration gauge
157# HELP phpfpm_process_requests The number of requests the process has served.
158# TYPE phpfpm_process_requests counter
159# HELP phpfpm_process_state The state of the process (Idle, Running, ...).
160# TYPE phpfpm_process_state gauge
161# HELP phpfpm_scrape_failures The number of failures scraping from PHP-FPM.
162# TYPE phpfpm_scrape_failures counter
163# HELP phpfpm_slow_requests The number of requests that exceeded your 'request_slowlog_timeout' value.
164# TYPE phpfpm_slow_requests counter
165# HELP phpfpm_start_since The number of seconds since FPM has started.
166# TYPE phpfpm_start_since counter
167# HELP phpfpm_total_processes The number of idle + active processes.
168# TYPE phpfpm_total_processes gauge
169# HELP phpfpm_up Could PHP-FPM be reached?
170# TYPE phpfpm_up gauge
171```
172
173## Grafana Dasbhoard for Kubernetes
174
175The Grafana dashboard can be found [here](https://grafana.com/dashboards/4912).
176There is also a more generic version [here](./grafana/kubernetes-php-fpm.json).
177
178<img src="https://grafana.com/api/dashboards/4912/images/3079/image" width="600">
179
180## FAQ
181
182* **How to update "Metrics collected"?**
183
184 Copy&paste the output from:
185 ```
186 curl http://127.0.0.1:12345/metrics | grep phpfpm | grep "#"
187 ```
188
189## Development
190
191### E2E Tests
192
193The E2E tests are based on docker-compose and bats-core. Install the required components, e.g. via brew on MacOS:
194
195```bash
196brew tap kaos/shell
197brew install docker-compose bats-core kaos/shell/bats-assert kaos/shell/bats-support
198```
199
200After the components are installed run the E2E tests:
201
202```bash
203make tests-e2e
204```
205
206## Contributing
207
208Contributions are greatly appreciated.
209The maintainers actively manage the issues list, and try to highlight issues suitable for newcomers.
210The project follows the typical GitHub pull request model.
211See " [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/) " for more details.
212Before starting any work, please either comment on an existing issue, or file a new one.
213
214## Contributors
215
216Thanks goes to these wonderful people ([emoji key](https://github.com/all-contributors/all-contributors#emoji-key)):
217
218<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
219<!-- prettier-ignore-start -->
220<!-- markdownlint-disable -->
221<table>
222 <tr>
223 <td align="center"><a href="http://enricostahn.com"><img src="https://avatars3.githubusercontent.com/u/362174?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Enrico Stahn</b></sub></a><br /><a href="#question-estahn" title="Answering Questions">��</a> <a href="https://github.com/hipages/php-fpm_exporter/commits?author=estahn" title="Code">��</a> <a href="https://github.com/hipages/php-fpm_exporter/commits?author=estahn" title="Documentation">��</a> <a href="#maintenance-estahn" title="Maintenance">��</a> <a href="https://github.com/hipages/php-fpm_exporter/commits?author=estahn" title="Tests">⚠️</a></td>
224 <td align="center"><a href="https://github.com/XooR"><img src="https://avatars2.githubusercontent.com/u/120429?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Stanislav Antic</b></sub></a><br /><a href="https://github.com/hipages/php-fpm_exporter/commits?author=XooR" title="Code">��</a></td>
225 <td align="center"><a href="http://herb123456.blogspot.com/"><img src="https://avatars1.githubusercontent.com/u/1568165?v=4?s=100" width="100px;" alt=""/><br /><sub><b>herb</b></sub></a><br /><a href="https://github.com/hipages/php-fpm_exporter/commits?author=herb123456" title="Code">��</a></td>
226 <td align="center"><a href="https://github.com/Nyoroon"><img src="https://avatars1.githubusercontent.com/u/182203?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Smoked Cheese</b></sub></a><br /><a href="https://github.com/hipages/php-fpm_exporter/issues?q=author%3ANyoroon" title="Bug reports">��</a> <a href="https://github.com/hipages/php-fpm_exporter/commits?author=Nyoroon" title="Code">��</a></td>
227 <td align="center"><a href="https://www.old-games.ru"><img src="https://avatars3.githubusercontent.com/u/7388179?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Alexander</b></sub></a><br /><a href="https://github.com/hipages/php-fpm_exporter/commits?author=sas1024" title="Code">��</a></td>
228 <td align="center"><a href="https://github.com/stanxing"><img src="https://avatars2.githubusercontent.com/u/23288646?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Stan Xing</b></sub></a><br /><a href="https://github.com/hipages/php-fpm_exporter/commits?author=stanxing" title="Code">��</a></td>
229 <td align="center"><a href="https://github.com/itcsoft54"><img src="https://avatars2.githubusercontent.com/u/22459145?v=4?s=100" width="100px;" alt=""/><br /><sub><b>itcsoft54</b></sub></a><br /><a href="https://github.com/hipages/php-fpm_exporter/commits?author=itcsoft54" title="Code">��</a></td>
230 </tr>
231 <tr>
232 <td align="center"><a href="http://128.io"><img src="https://avatars0.githubusercontent.com/u/44527?v=4?s=100" width="100px;" alt=""/><br /><sub><b>John S Long</b></sub></a><br /><a href="#infra-adduc" title="Infrastructure (Hosting, Build-Tools, etc)">��</a></td>
233 <td align="center"><a href="https://github.com/danielocallaghan"><img src="https://avatars.githubusercontent.com/u/62488?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Daniel O'Callaghan</b></sub></a><br /><a href="https://github.com/hipages/php-fpm_exporter/commits?author=danielocallaghan" title="Code">��</a></td>
234 <td align="center"><a href="https://github.com/stchr"><img src="https://avatars.githubusercontent.com/u/166079?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Simon Stücher</b></sub></a><br /><a href="https://github.com/hipages/php-fpm_exporter/issues?q=author%3Astchr" title="Bug reports">��</a></td>
235 <td align="center"><a href="https://sterba.dev"><img src="https://avatars.githubusercontent.com/u/48120735?v=4?s=100" width="100px;" alt=""/><br /><sub><b>André Sterba</b></sub></a><br /><a href="https://github.com/hipages/php-fpm_exporter/commits?author=andresterba" title="Code">��</a></td>
236 </tr>
237</table>
238
239<!-- markdownlint-restore -->
240<!-- prettier-ignore-end -->
241
242<!-- ALL-CONTRIBUTORS-LIST:END -->
243
244This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
245
246## Stargazers over time
247
248[](https://starchart.cc/hipages/php-fpm_exporter)
249
250## Alternatives
251
252* [bakins/php-fpm-exporter](https://github.com/bakins/php-fpm-exporter)
253* [peakgames/php-fpm-prometheus](https://github.com/peakgames/php-fpm-prometheus)
254* [craigmj/phpfpm_exporter](https://github.com/craigmj/phpfpm_exporter)
255
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}