BINLOGSEL

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
LOADABLE MODULES
SEE ALSO
AUTHORS
BUG REPORTS
COPYRIGHT

NAME

binlogsel - select records from binary logs

SYNOPSIS

binlogsel [-dnv] [-D DIR] [-i N] [-p PATTERN] [-t FORMAT]
[-I TAG] [-F TIME] [-T TIME]
[-L DIR] [-P DIR] [-m ’MODULE[ ARGS]’]
[FILE...]

binlogsel [-hV]

DESCRIPTION

Binlosel scans binary logs created by vmod-binlog(3) module and selects from them the records that were created within the given time intervals. A time interval is specified using the -F FROMTIME and -T TOTIME options. If both options are used, only records falling within the interval FROMTIME..TOTIME will be returned. If -F is used, but -T is omitted, TOTIME is set to the current time. If -T is used, but -F is omitted, the starting time is set to the time of the earliest available log file. Finally, if neither of options is used, all records will be output. In this case, the operation is equivalent to that of the binlogcat(1) command.

The argument to either option is a mostly free format human readable date string such as "Sun, 29 Feb 2004 16:21:42 -0800" or "2004-02-29 16:21:42" or even "2 days ago". It may contain items indicating calendar date, time of day, time zone, day of week, relative time, relative date, and numbers. An empty string indicates the beginning of the day. For a detailed description of date input formats, see section Date input formats in GNU Coreutils manual. If the info program and coreutils documentation are properly installed at your site, use the following command to view it:

info coreutils ’Date input formats’

Several time intervals can be specified, provided that each of them is preceded by the -I option, which introduces the tag to identify the records pertaining to that interval. This tag is output before each record. For example:

binlogsel -I 1h -F ’1 hour ago’ -I 2d -F ’2 days ago’

This command selects two intervals: records added within the last hour, which will be prefixed on the output with the string 1h, and records added within the last 2 days, which are prefixed by the string 2d.

The log files are searched in the directory specified with the -D command line option. The -i option can be used to define directory indexing level. See vmod-binlog(3), for a description of the underlying directory structure.

If files are listed in the command line, the -D, -i, and -p options are ignored.

The default action of binlogsel is to print matching records on the standard output. This can be changed by the use of loadable modules. A module is a dynamic library which is loaded at program startup and provides functions for handling records in a specific way.

The module to be loaded is supplied with the -m option. For example, the option -m modname instructs binlogsel to load library modname.so. Additional arguments for the module initialization function can be supplied in the same option (note quoting):

binlogsel -m ’modname -n arg’

The module to be loaded is searched in the library path, which consists initially of the single directory $prefix/lib/vmod-binlog. This path can be modified using the -L DIR option, which adds DIR to its end, or by the -P DIR option, which inserts its argument immediately before the default library directory.

See the section LOADABLE MODULES for the discussion of how to write loadable modules.

OPTIONS

	-D DIR		Set base log directory.
	-d		Print timestamps relative to first record in the file.

-F TIME

Select records newer than TIME. See the section DESCRIPTION for a discussion of valid time formats.

	-I TAG		Defines the tag for the -F and -T options that immediately follow it.
	-i N		Set directory indexing level. Valid values for N are 0, 1 and 2.
	-h		Print a short help summary and exit.
	-L DIR		Add DIR to the end of the library search path.

-m ’MODULE[ ARGS]’

Load MODULE.

	-n		Precede each record by its number in the file (0-based).
	-P DIR		Insert DIR into the library search path immediately before the default library directory.

-p PATTERN

Set pattern for log file names. PATTERN must be a valid strftime(3) format string.

-T TIME

Select records older than TIME.

-t FORMAT

Format timestamps according to FORMAT (see strftime(3)). Default is %c.

	-V		Show program version and exit.
	-v		Print information about each file before dumping it.

LOADABLE MODULES

Symbols exported from a loadable module must begin with modname_LTX_, where modname stands for the name of the module without suffix (.so, .la, etc.). In the discussion below, the symbols binlogsel looks for are listed without this prefix. Thus, for example, if the module name is stats.so, the name of the module initialization function must be stats_LTX_init.

Binlogsel expects modules to export the following functions:
void init(char *param, void (*addfn)(const char *, const char *, const
char *));

[OPTIONAL] Initializes the module. The first argument points to the arguments supplied to the module in the command line. The addfn function can be used to add new time intervals. Its usage is:

void addfn(const char *tag, const char *start, const char *end)

where tag is the interval tag, and start and end supply interval start and end times, correspondingly.

void done(void);

[OPTIONAL] Called immediately before binlogsel terminates.

int open(const char *file, size_t recsize, const char *format);

[OPTIONAL] This function is called immediately after opening the new log file. The name of the file is given by the file argument. The recsize argument gives the record size, and format points to the data format specification.

The function must return 0 to indicate success and non-null value on errors.

void close(void);

[OPTIONAL] Called before closing the log file.

void record(const char *tag, time_t ts, void * data);

[MANDATORY] This function processes the record pointed to by data. The tag argument points to the interval tag (can be NULL). Timestamp of the record is given by the ts argument.

AUTHORS

Sergey Poznyakoff

BUG REPORTS

Report bugs to <gray@gnu.org>.

COPYRIGHT

Copyright © 2013-2018 Sergey Poznyakoff
License GPLv3+: GNU GPL version 3 or later <http://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.

Manpage server at man.gnu.org.ua.