mmstat.8

mmstatd包含一个 C库和服务器

.\" $Id: mmstat.8,v 1.3 2003/01/09 08:07:08 mmondor Exp $
.\"
.\" Copyright (C) 2002-2003, Matthew Mondor
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. 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.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"      This product includes software written by Matthew Mondor.
.\" 4. The name of Matthew Mondor may not be used to endorse or promote
.\"    products derived from this software without specific prior written
.\"    permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY MATTHEW MONDOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 
.\" IN NO EVENT SHALL MATTHEW MONDOR BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
.\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd 1 Jan, 2003
.Dt MMSTAT 8
.Os
.Sh NAME
.Nm mmstat
.Nd Administration utility to access mmstatd functions
.Sh SYNOPSIS
.Nm mmstat [h]report
.Op Ar key|pattern
.Nm mmstat reset
.Ar p|v[a] key|pattern%value
.Op Ar key|pattern%value ...
.Nm mmstat update
.Ar p|v[a] key|pattern%value
.Op Ar key|pattern%value ...
.Nm mmstat delete
.Ar key|pattern
.Op Ar key|pattern ...
.Nm mmstat rotate
.Ar pattern prefix
.Sh DESCRIPTION
The
.Nm mmstatd
daemon is controled by parameters found in
.Nm /etc/mmstatd.conf
file. However, a binary is also provided with it to ease administration,
.Nm mmstat ,
which still uses the same configuration file. It basically internally uses
.Xr mmstat 3
function calls to provide a shell interface to administrators.
.Nm mmstat
returns 0 on success, or -1 on error.
.Pp
.Nm mmstat [h]report
.Op Ar key|pattern
.Pp
This invokation method permits to retreive a full statistics report, if no
arguments are specified, a report on a single key, if an absolute key name
is specified, or (slower) a report on all keys matching specified pattern,
which can use '*' and '?' wildcards. If
.Nm hreport
is specified instead of
.Nm report ,
a more humanly readable report form will be shown (can be useful to use
as-is for CGIs, etc).
.Pp
.Nm mmstat reset
.Ar p|v[a] key|pattern%value
.Op Ar key|pattern%value ...
.Pp
.Nm mmstat update
.Ar p|v[a] key|pattern%value
.Op Ar key|pattern%value ...
.Pp
Allow to reset or update volatile or persistant keys (either by absolute name
or pattern matching using '?' and '*'), using specified values. Key/value
pairs are specified separated with '%' character which is illegal in a key
name and thus consists of an ideal separator. If an operation is performed on
a non-existing key, it is automatically created on-the-fly (unless a pattern
rather than absolute key name). If more than a single
.Ar key|pattern%value
pairs are specified, operations are performed atomically within a protected
transaction on all of them. Of course the number of supplied pairs should not
exceed
.Ar MAX_TRANSACT
as specified in
.Aq Pa mmstat.h
headerfile.
.Ar p
means that operations should be persistant (as well as any new created key),
while
.Ar v
means that those should be volatile, and thus forgot about in case of a crash
or
.Nm mmstatd
daemon restart. If
.Ar a
is also specified, this instructs mmstatd to automatically flush/delete any
key that reaches 0 after the operation, atomically.
For reset operations, the value part of a pair specifies what
value to initialize the corresponding key to; For update operations the current
key contents is increased by the specified value (which may also be a negative
number).
.Pp
.Nm mmstat delete
.Ar key|pattern
.Op Ar key|pattern ...
.Pp
Causes specified key(s), represented by their absolute name, or ones matching
supplied '?' and '*' wildcard matching pattern, to be deleted
from the statistics database. If more than a single key is specified, a
transaction-protected atomic operation is performed on all of them, of course
still subject to
.Ar MAX_TRANSACT
according to the maximum number of keys that can be specified.
.Pp
.Nm mmstat rotate
.Ar pattern prefix
.Pp
Will perform an atomic rename operation on all persistant keys matching
specified
.Ar pattern
by inserting the specified
.Ar prefix
before each matching key name. '*' and '?' wildcards are allowed in the
.Ar pattern
argument. This is most useful to perform automatic weekly or monthly rotation
of statistical keys via a cron events scheduler for instance. This function
also causes an immediate database sync to disk.
.Sh EXAMPLES
Obtain a nicely formatted key/value based statistical report:
.Bd -literal -offset indent -compact
mmstat report | awk '{printf "%-64s %d\\n", $6, $5}' | sort
.Ed
.Pp
An alias to obtain a more sophisticated report:
.Bd -literal -offset indent -compact
alias report='printf "%10s %-13s %s\\n" "COUNTER" "MODIFIED" "KEY"; mmstat report | awk "{printf \\"date -r %d +%s\\\\\\ %s\\\\\\ %%y%%m%%d.%%H%%M%%S\\n\\", \\$4, \\$6, \\$5}" | sh | sort | awk "{printf \\"%10s %s %s\\n\\", \\$2, \\$3, \\$1}"'
.Ed
.Pp
Show who is currently connected on mmftpd:
.Bd -literal -offset indent -compact
mmstat report 'mmftpd.who.*'
.Ed
.Pp
Reset all keys with mmftpd in their name to 0:
.Bd -literal -offset indent -compact
mmstat report | grep mmftpd | awk '{printf "%s%%%d ", $6, 0}' |
	xargs mmstat reset p
.Ed
.Pp
Increase the persistant my.test key by 4 while atomically decreasing the
persistant my.test2 key by 2:
.Bd -literal -offset indent -compact
mmstat update p 'my.test%4' 'my.test2%-2'
.Ed
.Pp
Delete all keys with mmftpd in their name:
.Bd -literal -offset indent -compact
mmstat report | awk '{print $6}' | grep mmftpd | xargs mmstat delete
.Ed
.Pp
Example of a monthly cron entry to rename all mmftpd.* keys to YYYYMM-mmftpd.*
using the last month label:
.Bd -literal -compact
30 5 1 * * mmstat rotate 'mmftpd.*' `date -r $((\`date +%s\`-86400)) +%Y%m-`
.Ed
.Pp
Example of a daily cron entry to rename all mmftpd.* keys to YYYYMMDD-mmftpd.*
using the last day for the stamp:
.Bd -literal -compact
30 5 * * * mmstat rotate 'mmftpd.*' `date -r $((\`date +%s\`-86400)) +%Y%m%d-`
.Ed
.Sh ENVIRONMENT
.Bl -tag -width XXXXXXXXXX
.It Pa Nm MMSTATCONF
If set, specifies the absolute location of the configuration file to load
instead of the default
.Nm /etc/mmstatd.conf .
.El
.Sh AUTHOR
mmstat and related daemon and library were written by Matthew Mondor,
and are Copyright (c) 2002-2003, Matthew Mondor, All rights reserved.
It originally was written for the mmftpd and mmmail suite of daemons by the
same author.
.Sh FILES
.Bl -tag -width XXXXXXXXXXXXXXXXXXXX -compact
.It Pa <mmstat.h>
Headerfile used both by
.Nm mmstatd
daemon and
.Nm mmstat
utility, defining related
.Ar MAX_TRANSACT
variable.
.Pp
.It Pa /etc/mmstatd.conf
Configuration file for both
.Nm mmstatd
daemon and
.Nm mmstat
utility.
.El
.Sh SEE ALSO
.Xr mmstat 3 ,
.Xr mmstatd.conf 5 ,
.Xr mmstatd 8 .
.Sh BUGS
Please report any bug to [e-mail]