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
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
|
========
umberlog
========
--------------------------------------
CEE-enhanced syslog message generation
--------------------------------------
:Author: Gergely Nagy <algernon@balabit.hu>
:Date: 2012-04-28
:Manual section: 3
:Manual group: CEE-enhanced syslog Manual
SYNOPSIS
========
::
#include <umberlog.h>
void ul_openlog (const char *ident, int option, int facility);
void ul_closelog (void);
int ul_syslog (int priority, const char *format, ....);
int ul_vsyslog (int priority, const char *format, va_list ap);
void ul_legacy_syslog (int priority, const char *format, ...);
void ul_legacy_vsyslog (int priority, const char *format, va_list ap);
void ul_format (int priority, const char *format, ...);
void ul_vformat (int priority, const char *format, va_list ap);
DESCRIPTION
===========
**ul_openlog()** (also aliased to **openlog()**) is a wrapper around
the original **openlog()** function, which opens a connection to the
system logger for a program. The updated version adds support for a
number of new option flags, described below.
**ul_closelog()** (also aliased to **closelog()**) is similar to
**ul_openlog()** in that it is a wrapper around the original
**closelog()**. It clears any settings set so far, to get back to a
clean state.
**ul_legacy_syslog()** and **ul_legacy_vsyslog()** are both thin
layers over the original **syslog()** and **vsyslog()** functions, and
the library overrides the original functions with this two. The only
change these functions bring, are that the message they generate will
be a CEE-enhanced message, with a JSON payload. See below for an
explanation on what this means.
**ul_syslog()** and **ul_vsyslog()** are two new functions provided by
the library, that have similar interface to the legacy **syslog()**
functions, but they can be used to add arbitrary key-value pairs to
the emitted message. After the *msg_format* format string, and any
other parameters it refers to, there must be a NULL-terminated list of
*key*, *value format*, *format parameters*. Each of these pairs,
constructed from the *key* and the **printf(3)**-style *value format*
will be added to the generated message. Note that position specifiers
(e.g. **%2$**) are not currently supported.
**ul_format()** and **ul_vformat()** do the same as the syslog
variants above, except the formatted payload is not sent to syslog,
but returned as a newly allocated string.
RETURN VALUE
============
When successful, **ul_syslog()** and **ul_vsyslog()** return zero,
while **ul_format()** and **ul_vformat()** return a character string.
On failure the former two will return non-zero, the latter two
**NULL**, and set *errno* appropriately.
CEE PAYLOAD
===========
All of the improved **syslog()** functions, the legacy and overridden
ones and the new ones too turn the original syslog message into a
CEE-enabled JSON payload, with the original message put into the *msg*
field, and any additional fields put into the same structure.
By default, unless the **LOG_UL_NODISCOVER** option flag is set, all
of these functions will also add a few automatically discovered fields
into the payload:
*pid*
The process ID of the program, as returned by **getpid()** The value
of this is - by default - determined at the time of calling
**ul_openlog()**, but if caching is disabled, it will be rechecked
every time.
*facility*, *priority*
The syslog facility and priority as a text string.
*program*
The identification set at the time of **ul_openlog()**.
*uid*, *gid*
The user and group ID of the process, determined at **ul_openlog()**
time by default, unless caching is disabled.
*host*
The name of the originating host, determined at **ul_openlog()**
time by default, using **gethostname()**.
*timestamp*
High-precision timestamp, in textual format. Included by default,
but can be controlled by the **LOG_UL_NOTIME** option flag at
**ul_openlog()** time.
EXTRA OPTION FLAGS
==================
The *option* argument to **ul_openlog()** is an OR of any of the
original **openlog()** flags, and these:
LOG_UL_NODISCOVER
Disable all automatic discovery, and only include the *message*,
and any specified *key-value* pairs in the generated message.
LOG_UL_NOCACHE
When automatic discovery is enabled, disable caching certain
properties, that might change between the call to **openlog()** and
the **ul_syslog()** invocation.
LOG_UL_NOCACHE_UID
Disable the *uid* and *gid* caching when automatic discovery is
enabled, but do cache the rest.
LOG_UL_NOTIME
Do not add a high-precision timestamp to the generated message when
automatic discovery is enabled.
EXAMPLES
========
::
status = ul_syslog(LOG_NOTICE, "Logged in user: %s", username,
"service", "%s", service,
"auth-method", "%s", auth_method,
"sessionid", "%d", session_id,
NULL);
SEE ALSO
========
**syslog(1)**
COPYRIGHT
=========
This page is part of the *libumberlog* project, and is available under
the same 2-clause BSD license as the rest of the project.
|
