mmstat.3

mmstatd包含一个 C库和服务器

.\" $Id: mmstat.3,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 January 1, 2003
.Os
.Dt MMSTAT 3
.Sh NAME
.Nm mmstat
.Nd Statistical book-keeper with transaction isolation and recovery support
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/time.h>
.Fd #include <mmtypes.h>
.Fd #include <mmstat.h>
.Ft bool
.Fn mmstat_initialize "void"
.Ft bool
.Fn mmstat_init "MMSTAT *mms" "bool persistant" "bool autoflush"
.Ft bool
.Fn mmstat "MMSTAT *mms" "enum stat_type type" "int64_t value" "char *fmt" "..."
.Ft bool
.Fn mmstat_transact "MMSTAT *mms" "bool lock"
.Ft MMSTATRES *
.Fn mmstat_report "char *fmt" "..."
.Ft MMSTATRES *
.Fn mmstat_freeres "MMSTATRES *res"
.Ft MMSTATENT *
.Fn mmstat_nextres "MMSTATRES *res"
.Ft bool
.Fn mmstat_rotate "char *pattern" "char *prefix"
.Sh DESCRIPTION
mmstat consists of a daemon (mmstatd) and library API (mmstat). mmstatd
handles a statistical database on a key/value pair basis and stores for
each the creation and modification timestamps as well. These entries may
be volatile or persistant. Through the mmstat library applications may
create, update, and delete statistical keys. The mmstatd design was made
around two asynchroneous processes, the logger and the librarian. The logger
dispatches update requests writing recovery logs and syncing to disk, while
the librarian processes those logs, affecting the memory database, and syncs
that database to disk at fixed intervals.
.Pp
.Fn mmstat_initialize
is optional and can be called to initialize the library. Other library
functions will automatically do this if need be; It however may be necessary
to force this initialization to occur using this function before using
.Xr chroot 2
since the socket and configuration files may not longer be available from
the new root jail. Note that
.Fn mmstat_report
and
.Fn mmstat_rotate
cannot be pre-initialized and that those calls will fail if the socket file
is not available. Note that internally the
.Nm MMSTATCONF
environment variable will be checked to determine an alternative configuration
file to read. Otherwise the default consists of
.Nm /etc/mmstatd.conf .
.Pp
.Fn mmstat_init
initializes supplied MMSTAT
.Fa mms
object. This is required before calling other mmstat functions using this
handle. It in fact transforms the object into a handle suitable for other
calls. There is no need to perform any special cleanup on the handle once
done with it. It can be reused multiple times, arbritrarily, since it first
was initialized. The handle is initialized for persistant storage if
.Fa persistant
is TRUE, or for volatile storage if FALSE. Volatile keys are not stored
into the disk database, they also will not be recovered in case of a crash.
If
.Ar autoflush
is TRUE, updated or reset entries will automatically be deleted when they
reach zero, atomically. This can be useful with volatile keys for a
"who" service for instance.
Multiple handles can be obtained by the same process.
.Pp
.Fn mmstat
permits to create, modify or delete a statistical key-based entry.
.Fa mms
consists of the handle to perform operation through,
.Fa type
should be STAT_UPDATE, STAT_RESET or STAT_DELETE.
.Fa value
consists of the value to add to the specified key, or value to reset it
to when STAT_RESET is used.
.Fa fmt
specifies the key to perform operation on. When a key does not exist, it is
automatically created on the fly, unless a '*' and '?' wildcard matching
pattern is provided to only operate on existing matching keys. Only
applications which belong to the LOG_GROUP can affect statistic changes. See
.Xr mmstatd.conf 5
for more information.
.Pp
.Fn mmstat_transact
allows to transaction-protect a set of
.Fn mmstat
function calls. These operations will be isolated from other requests and
are therefore guarenteed to be atomic.
.Fa mms
is the handle to affect, and
.Fa lock
should be TRUE (lock) or FALSE (unlock).
.Pp
.Fn mmstat_report
permits to retreive statistics from the database.
.Fa fmt
should be NULL if a full report is wanted, a pattern with * and ? wildcard
matching, or an absolute key name. It should be noted that only applications
which belong to the STAT_GROUP are allowed to obtain statistic reports. See
.Xr mmstatd.conf 5
for details.  Some care should be taken when requesting reports, since load
on the librarian daemon is much higher when processing reports than updates.
It is important that the applications process the report as fast as possible
with
.Fn mmstat_nextres
and then call
.Fn mmstat_freeres
to allow the librarian to perform it's vital tasks. See
.Nm mmstatd/src/mmstat.c
for an example on how to do this.
.Pp
.Fn mmstat_freeres
closes the internal IPC resources established with the librarian process. It
is important to call this function after
.Fn mmstat_report
is called, and as soon as possible to free the librarian.
.Fa res
consists of the report results that were obtained from it.
.Pp
.Fn mmstat_nextres
allows to obtain results one by one from the
.Fa res
handle obtained from
.Fn mmstat_report
sequencially. The results are obtained into an MMSTATENT structure, as defined
in
.Aq Pa mmstat.h
(described below).
.Bd -literal -offset indent
typedef mmstat_entry {
    int64_t value;
    time_t created, modified;
    uid_t uid;
    char key[KEY_SIZE];
    bool persistant;
} MMSTATENT;
.Ed
.Pp
.Fn mmstat_rotate
permits to atomically rename all persistant keys matching
.Fa pattern
(with optional * and ? wildcard) by inserting
.Fa prefix
string before each. This is very useful for weekly/monthly/yearly rotation
of statistics by cron events. This function also forces an immediate db sync
to disk.
.Sh RETURN VALUES
.Fn mmstat_initialize
returns TRUE on success, or FALSE if the configuration file or logging socket
could not be accessed.
.Pp
.Fn mmstat_init
returns TRUE on success, or FALSE on error (socket could not be created).
.Pp
.Fn mmstat
returns TRUE on success, or FALSE on error. It should be noted that in the case
of a transaction protected operation, the results of the closing
.Fn mmstat_transact
should be evaluated instead.
.Pp
.Fn mmstat_transact
returns TRUE when a lock is acquired, but FALSE if a lock is already active
on the specified handle. When a lock is released,
.Fn mmstat_transact
returns TRUE if the set of operations could be processed, or FALSE otherwise.
.Pp
.Fn mmstat_report
returns an
.Fa MMSTATRES
results handle pointer on success, or NULL on error.
.Pp
.Fn mmstat_freeres
always returns NULL.
.Pp
.Fn mmstat_nextres
returns the next entry of results as an
.Fa MMSTATENT
pointer in the specified
.Fa MMSTATRES
set, but returns NULL when reaching the end of results.
.Pp
.Fn mmstat_rotate
returns FALSE if it could not establish connection with the mmstat daemon,
or TRUE otherwise.
.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 SEE ALSO
.Xr mmstatd.conf 5 ,
.Xr mmstatd 8 ,
.Xr mmstat 8 ,
.Xr syslog 3 ,
.Xr chroot 2 .
.Sh STANDARDS
None whatsoever, it was custom-designed from scratch. It however was written
to comply with most ANSI-C programming norms, and is expected to run on a
system conforming to IEEE Std 1003.1-1990 (``POSIX'').
.Sh HISTORY
mmstatd and mmstat library were primarily written on NetBSD 1.5.3 for the
mmftpd and mmmail suite of daemons.
.Sh AUTHOR
The mmstat protocol is Copyright (c) 2002-2003, Matthew Mondor, All Rights Reserved.
The mmstat library and the mmstatd daemon were written by Matthew Mondor.
.Sh BUGS
Please report any bug to [e-mail]