Ubuntu Manpage: pseudolog - pseudo log parser

Provided by: pseudo_1.9.0+git20211111+300d7570720b-2_amd64

NAME

       pseudolog - pseudo log parser

SYNOPSIS

       pseudolog -l [-Pv] [ -E timeformat ] [ -x flags ] [SPECIFICATIONS]

       pseudolog [-UPv] [ -E timeformat ] [ -F format ] [ -x flags ]

       pseudolog -h

       pseudolog -D [-Pv] [ -E timeformat ] [ -x flags ] [SPECIFICATIONS] [SPECIFICATIONS]

DESCRIPTION

The pseudolog utility displays, creates, or deletes log entries associated with the pseudo
daemon. Creation of log entries is useful only to create timestamps or notes; for
instance, you could create a log entry before beginning a process, so there would be a
timestamp for the beginning of that process. There are a number of special options used
to match or create the components of a log entry; these are called specifications, and are
detailed in the SPECIFICATIONS section below.

The following other options are supported:

-h Print a usage message and exit.

-D Delete rows selected by the query. This is not reversible.

-E timeformat
Specify a format string (for strptime(3) or strftime(3) to use) for displaying or
interpreting time stamps. The same format is used both for parsing and displaying
stamps.

-F format
Specifies a format string for displaying log entries. This format cannot be used
to create log entries, only for display. The format string is a printf(3) type
format string, with format specifiers matching the option characters used in
specifications (see SPECIFICATIONS). There are some limitations on allowed
formats, and misuse of this feature could cause interesting or surprising
failures.

-l Create a log entry. This option is mutually exclusive with the -F option, or with
any relative specifications (see below).

-P path Specify that path should be used as the PSEUDO_PREFIX value, overriding any
environment setting.

-U Restrict query output to unique rows. Rows will have members defined by the -F
(format) option. If all members are the same between two rows, only one is
displayed. Applies only to queries.

-v Increase verbosity (debug level). Not useful except when debugging pseudo.
Deprecated; use -x.

-xflags Specify debugging flags of interest. Not useful except when debugging pseudo.

Other option characters are defined as specifications, and all of those require
arguments to specify their values.

SPECIFICATIONS

The various components of a log entry can be specified, either as command-line options, or
as format specifiers. In either case, the same character is used for a given component of
a log entry. When querying values, one of the following prefixes may be prepended to a
value; otherwise, the value is used for a literal match (an SQL = operator).

> Greater than; true if the related field is greater than the provided value.

< Less than; true if the related field is less than the provided value.

& Bitwise and; true if the related field, bitwise-and the provided value, is non-
zero. (This is useful primarily for permissions or modes.)

= Equal to. (This is a no-op, as of this writing.)

! Not equal to.

% Similar to ~. This is valid only on text fields, and is equivalent to the SQL
LIKE operator, with % patterns on the ends; it performs an unanchored, case-
insensitive match.

~ Similar to %. This is valid only on text fields, and is equivalent to the SQL
LIKE operator, but performs an anchored match. The match is case-insensitive.
The specifier ~%foo% is equivalent to the specifier %foo.

^ Unlike. This is the inverse of ~; it specifies NOT LIKE.

Escape the string. This is useful if you want to have one of the other modifiers
at the beginning of the string.

Only =and.ft R modifiers may be used in conjunction with the -l option.

The following characters correspond to specific fields in a log entry. In general,
numeric values are parsed in the standard C idiom (where a leading 0 indicates an octal
value, and a leading 0x indicates a hexadecimal value, and any other number is decimal).
A few fields are parsed or displayed in other ways, as detailed in their entries.

a Access mode. This is an access mode specified in the form used by fopen(3), such
as "r+" to indicate read/write access. Note that specifying a as an access mode
will include non-append writes, as the "a" mode implies write and append both.
This feature is slightly experimental and may not correctly identify the access
type of every access. The string x may be specified to indicate execute access.

c Client ID (the PID of a client).

d Device number (from a stat buffer).

f File descriptor. In some cases, messages have an associated file descriptor
identified.

g GID. The group ID associated with an entry.

G Tag. This is a text field. In log entries created by pseudo, this field holds
the value that the environment variable PSEUDO_TAG had in the client's
environment.

i Inode number (from a stat buffer).

I ID. This is the database row number. Normally these are assigned as
monotonically increasing values as rows are inserted, making them a more reliable
sorting mechanism than timestamps. The default ordering is by ID. m Permissions.
These can be entered as an octal value or as a symbolic mode string, similar to
the output of ls(1) -l. The file type component is ignored.

M Mode. This can be entered as an octal value or as a symbolic mode string, similar
to the output of ls(1) -l. This is tested against the whole file mode, including
both the type and permissions bits. In general, it is more useful to use the m or
t specifiers.

o Operation. This is the name of the file system operation (e.g., "open" or
"rename").

O Order. This takes another specification character as the field on which to order
results. A '<' implies a descending order sort, a '>' or no modifier specifies an
ascending order sort. By default, records are sorted by ID.

p File path. This is a text field.

r Result. This is the pseudo result code, most often "fail" or "succeed". Note
that "fail" doesn't mean that an underlying operation failed; for instance, if a
"stat" operation fails, it usually means that there was no entry in the pseudo
database.

R Program. This is the program name (as retrieved by glibc's
program_invocation_name variable), which has the full path if and only if the
program was invoked by full path name.

s Timestamp. The format of this field is controlled by the -E format string, which
is used with strftime(3) when displaying entries, or with strptime(3) when
interpreting command line values. There is a small selection of common default
time formats understood by the parser. Time fields not specified default to the
current time. Note that specifying a time stamp when creating a log entry may
yield confusing results.

S Severity. Log messages can have a severity, with the default for file operations
being "info". t File type. This corresponds to the first letter of a mode
string, or the values accepted by the -type option to find(1). This is compared
only against the file type bits of a mode.

T Text. This is an optional field available for user use when creating log entries,
or to hold the text of an error message when an error is logged. It is, of
course, a text field.

u UID. The user ID associated with an entry.

y Type. This is usually "op" for operations, or "ping" for the ping messages
clients send to confirm server availability. Other types should rarely occur, but
include "ack" and "nak" for server responses (which are never logged), and "halt"
for shutdown messages (currently not logged).

EXAMPLES

       The following examples illustrate some of the likely usage patterns for pseudolog.

       pseudolog -m '&020' -t d
               Report on all directories which are group-writeable.

       pseudolog -m 755 -t f
               Report on all plain files which have the mode rwxr-xr-x.

       pseudolog -s '>03:19:00' -s '<03:20:00'
               Report on all entries created after 03:19:00 and before 03:20:00  on  the  current
               date.

       pseudolog -p '~/usr/bin/%' -F '%-8o %p'
               Report on every entry with a path beginning with the string '/usr/bin', displaying
               the operation name (in a space-padded field of  eight  characters,  left-adjusted)
               followed by the path.

       pseudolog -l -T 'stamp test'
               Create an entry with all fields zero or blank, except for the text field, which is
               set to the text "stamp test", and the timestamp, which is set to the current time.

       pseudolog -D -r succeed -F '%p' -O p
               Display all paths for which operations succeeded, sorted by path value.

ENVIRONMENT

       The only environment variable supported by pseudolog is:

       PSEUDO_PREFIX
               If set, the variable PSEUDO_PREFIX is used to determine the path to  use  to  find
               the logs.db database file, in PSEUDO_PREFIX/var/pseudo.

BUGS

       The  user might think our intent is to replace all of SQL.  It's not.  If the options here
       aren't enough, rather than adding more options to this already fairly  elaborate  program,
       just do raw SQL queries on the logs.db file.

       The  formatting  options  are  handled  by  converting them into printf(3) format strings,
       without much checking.  As a result, it is possible for a malformed format string to cause
       printf() to explode unexpectedly.