-
Notifications
You must be signed in to change notification settings - Fork 3
/
phptop.1
138 lines (136 loc) · 8.04 KB
/
phptop.1
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
.\" Yes, this file is manually edited.
.\"
.TH "PHPTOP" "1" "2024/01/26" "\ 0.5.11" "\ "
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.SH "NAME"
phptop \- print system ressource usage statistics from PHP scripts
.SH "SYNOPSIS"
phptop [options]
.sp
.SH "DESCRIPTION"
phptop prints per query and average metrics comparable to the 'time' program or shell builtin: wallclock, user and system CPU time along with memory and other ressources usage. It can be used from the command line to diagnose performance problem in quasi real time (minimum sampling is 1 minute) with minimal overhead, or to generate HTML reports.
.sp
Performance data is measured by a simple PHP hook (\fBphptop_hook.php\fP) which is automatically run on every PHP script execution via the \fBauto_prepend\fP PHP option. These data are collected in your web server error log, provided you have setup PHP to log errors (\fPlog_errors = On\fP) and not display them in your regular output (\fBdisplay_errors = Off\fP) - which should be the case of any sane production server.
.sp
The phptop command will then parse those error logs and output useful statistics (see INTERPRETATION below).
.sp
.SH "OPTIONS"
.TP
\-a, \-\-average
Show per-hit average values instead of cumulated time.
.TP
\-c, \-\-count N
Limit output to top N URLs (default is 10).
.TP
\-d, \-\-domain
Only use domain, ignore URL path.
.TP
\-f, \-\-full\-query
Consider full URL with CGI parameters (ie. do not strip ?param=...).
.TP
\-g, \-\-goto DATE
Instead of analysing data starting from now and back up to --time seconds, start from DATE. The format may use absolute or relative dates in a quite natural language, see Perl's Time::ParseDate module. Examples of valid DATE strings: yesterday, 2 hours ago, 15:30, last monday.
.TP
\-h, \-\-help
Display a short options summary.
.TP
\-l, \-\-log path
Logfiles to parse, you may use several \-l options and wildcards in paths. Be careful to quote your wildcards in order they are not interpreted by your shell. If no \-l options are used, try a few guesses.
.TP
\-m, \-\-mangle :RE:REPLACE:
Mangle URLs before sorting and counting them, allows to collapse similar URLs into a comme one. For instance:
phptpop --mangle ':/user/.*:/user/xxx:'
This is a perl substitution, things like modifiers (:g to match all ocurrences, :i for insenstive case, etc.), captures and back-references all work. This substitution is applied before the -p|--path and -d|--domain options.
.TP
\-o, \-\-output mode
Output mode: text or html (default is 'text').
.TP
\-p, \-\-path\-only
Only print URL paths, skip the http(s):https://<host> prefix.
.TP
\-r, \-\-relative
Show time values relative to the sample period (see -t). For instance, a cumulated 30sec user time for a 300sec sample will be shown as '10%'. Hits are also printed relative to the total of parsed records.
.TP
\-s, \-\-sort key
Sort by hit, time, user, sys or mem (default is 'hit'). You may use several \-s options, they will generate as much statistics in one go (hence reusing the parsing effort efficiently).
.TP
\-t, \-\-time N
Parse data from now back to N seconds (default is 300, ie. 5 minutes).
.TP
\-v, \-\-version
Display version number and copyright information.
.SH "EXAMPLES"
Using phptop to print the top CPU (user) consumers for the last 10min:
.sp
.sp
.nf
phptop -l /path/to/error.log -t 600
.fi
.sp
Getting stats from the last 10 minutes, sorted by hits, from well known log files:
.sp
.sp
.nf
phptop -p
.fi
.sp
Hint: on a given server, define a shell alias which already sets the proper error log paths. This way you don't have to repeat them again. Bash recipe:
.sp
.sp
.nf
$ echo "alias phptop='phptop -l /home/*/log/error.log'" >>.bashrc
$ source .bashrc
$ phptop -t60
.fi
.SH "INTERPRETATION"
Wallclock, system and user times are cumulated for similar URLs, and the total per URL is shown. It is an absolute time value which must be related to your observation window (-t option). The wallclock time is not a very interesting measure, since it depends on your server ressources, on the client and on the client-server bandwidth, minus buffering effects. Interpret it with much caution.
.sp
The user and system time are CPU ressources. For a one minute observation window (-t 60), on a quad-core system you have 4 minutes (240 seconds) worth of CPU time to be split between user (CPU running application code), system (CPU running kernel code) and idle (CPU waiting I/O or doing nothing). With --relative, the same system will show up to 400% worth of CPU time. On a busy and healthy server, user and system time add up to the whole available CPU time. If your user and system total time is low and far from the available CPU time, consult your server loadavg: if it's high (more than your number of CPUs), your server is probably waiting on I/O (more often disk than network); if it's low, your application might be waiting on remote services (think remote HTTP APIs) which are slow or not responding.
.sp
The memory figures can't be added, it would not make any sense. Instead simple satistics like peak (maximum) and average memory per URL are computed. The peak memory usage is very interesting when running phptop over a large time window (one day or more) to figure out your optimal PHP \fBmemory_limit\fP figure, which is itself very useful for proper configuration and usage of system ressources (number of PHP processes, SQL server connections, and so on). Over a short time window it also acts as a poor man's profiler, and may spot some memory abuses.
.sp
.SH "DISCUSSION"
phptop hooks into existing code via the \fBauto_prepend_file\fP PHP option. This option might be set and overriden at different levels by other programs (global, per-directory, per-vhost, etc). Since phptop has been verified to have no measurable impact on heavy production servers, it is considered to be a good idea to enable it globally. If your server uses several log files (typically one per virtual host), you will be able to only pickup needed data at analysis time (which is the potentially costly phase).
.sp
phptop records data via the \fBerror_log()\fP PHP instruction. The author considers that any sane server setup should have a working error log, and it would have been inefficient and dangerous to handle custom logging (which would obviously end up firing lots of open/write/close, not being properly rotated and so on). This method is efficient and safe, but it has some drawbacks, see BUGS below.
.sp
At analysis time (when launching phptop itself), care has been taken to read and parse only the needed amount of data. Most importantly it will use the tac(1) command to 'reverse tail' the error logs, and default to a slower method if this command is not found. phptop can parse plain and gzipped log files.
.sp
The analysis process itself is mostly CPU bound if your error log sits on a reasonably available storage, and runs at approx. 15,000 samples/sec on a 2.4Ghz Intel core. That is why phptop output should be almost instantaneous while analysing the last minutes (eg. -t 300), even on a very busy server (100 req/sec or more).
.sp
.SH "BUGS"
phptop should run '-s user' as a default instead of the useless-but-look-ma-my-hits '-s hit'.
.sp
phptop pollutes error logs with non-error information, but this makes phptop fast and safe (see DISCUSSION). As a side effect, phptop won't collect data for scripts run throught the CLI SAPI (it pollutes their stderr), which is a shame.
.sp
Please file bugs at \fIhttps://github.com/bearstech/phptop/issues\fR.
.sp
.SH "ENVIRONMENT VARIABLES"
.sp
.TP
COLUMNS
If set and stdout is a tty, overrides the detected terminal width. If there is no terminal (like when piping to another program), set output width.
.sp
.SH "FILES"
.sp
.nf
/usr/share/phptop/phptop_hook.php
.fi
.SH "AUTHOR"
Written by Vincent Caron
.sp
Homepage at \fIhttps://github.com/bearstech/phptop\fR
.sp
.SH "COPYRIGHT"
.sp
Copyright © 2009-2024 Bearstech. License GPLv3+: GNU GPL version 3 or later <http:https://gnu.org/licenses/gpl.html>.
This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.
.sp
.SH "SEE ALSO"
.sp
.nf
time(1), getrusage(2)
.fi