Skip to content

Commit f27c912

Browse files
nikbytenikbyte
committed
event_flatstore: fix rotation handling and add optional file headers
1 parent 9368075 commit f27c912

4 files changed

Lines changed: 657 additions & 56 deletions

File tree

‎modules/event_flatstore/doc/event_flatstore_admin.xml‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -264,6 +264,25 @@ modparam("event_flatstore", "suffix", "$time(%Y)")
264264
</programlisting>
265265
</example>
266266
</section>
267+
<section id="param_header" xreflabel="header">
268+
<title><varname>header</varname> (string)</title>
269+
<para>
270+
If set, the string is written as the very first line of
271+
every new log file created by the module.
272+
Useful for column names.
273+
</para>
274+
<para>
275+
<emphasis>Default value is <quote>""</quote> (disabled)</emphasis>.
276+
</para>
277+
<example>
278+
<title>Set <varname>header</varname> parameter</title>
279+
<programlisting format="linespecific">
280+
...
281+
modparam("event_flatstore", "header", "time,event,param1,param2")
282+
...
283+
</programlisting>
284+
</example>
285+
</section>
267286
</section>
268287
<section id="exported_functions" xreflabel="exported_functions">
269288
<title>Exported Functions</title>

‎modules/event_flatstore/doc/event_flatstore_admin.xml.orig‎

Lines changed: 338 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,338 @@
1+
<!-- Module User's Guide -->
2+
3+
<chapter>
4+
5+
<title>&adminguide;</title>
6+
7+
<section id="overview" xreflabel="Overview">
8+
<title>Overview</title>
9+
<para>
10+
The <emphasis>event_flatstore</emphasis>
11+
module provides a logging facility for different events,
12+
triggered through the &osips; Event Interface, directly from the &osips;
13+
script. The module logs the events along with their parameters in plain
14+
text files.
15+
</para>
16+
</section>
17+
<section>
18+
<title>Flatstore socket syntax</title>
19+
<para>
20+
<para><emphasis>flatstore:path_to_file</emphasis></para>
21+
</para>
22+
<para>
23+
Meanings:
24+
<itemizedlist>
25+
<listitem><para>
26+
<emphasis>flatstore:</emphasis> - informs the Event Interface that the
27+
events sent to this subscriber should be handled by the
28+
<emphasis>event_flatstore</emphasis> module.
29+
</para> </listitem>
30+
<listitem><para>
31+
<emphasis>path_to_file</emphasis> - path to the file where the logged events will be appended to. The file will be created if it does not exist. It must be a valid path and not a directory.
32+
</para> </listitem>
33+
</itemizedlist>
34+
</para>
35+
</section>
36+
<section id="dependencies" xreflabel="Dependencies">
37+
<title>Dependencies</title>
38+
<section>
39+
<title>&osips; Modules</title>
40+
<para>
41+
The following modules must be loaded before this module:
42+
<itemizedlist>
43+
<listitem>
44+
<para>
45+
<emphasis>No dependencies on other &osips; modules</emphasis>.
46+
</para>
47+
</listitem>
48+
</itemizedlist>
49+
</para>
50+
</section>
51+
</section>
52+
<section>
53+
<title>External Libraries or Applications</title>
54+
<para>
55+
The following libraries or applications must be installed before
56+
running &osips; with this module loaded:
57+
<itemizedlist>
58+
<listitem>
59+
<para>
60+
<emphasis>none</emphasis>
61+
</para>
62+
</listitem>
63+
</itemizedlist>
64+
</para>
65+
</section>
66+
<section id="exported_parameters" xreflabel="Exported Parameters">
67+
<title>Exported Parameters</title>
68+
<section id="param_max_open_sockets" xreflabel="max_open_sockets">
69+
<title><varname>max_open_sockets</varname> (integer)</title>
70+
<para>
71+
Defines the maximum number of simultaneously opened files by the
72+
module. If the maximum limit is reached, an error message will be
73+
thrown, and further subscriptions will only be possible after at
74+
least one of the current subscriptions will expire.
75+
</para>
76+
<para>
77+
<emphasis>
78+
Default value is <quote>100</quote>.
79+
</emphasis>
80+
</para>
81+
<example>
82+
<title>Set <varname>max_open_sockets</varname> parameter</title>
83+
<programlisting format="linespecific">
84+
...
85+
modparam("event_flatstore", "max_open_sockets", 200)
86+
...
87+
</programlisting>
88+
</example>
89+
</section>
90+
<section id="param_delimiter" xreflabel="delimiter">
91+
<title><varname>delimiter</varname> (string)</title>
92+
<para>
93+
Sets the separator between the parameters of the event in the logging file.
94+
</para>
95+
<para>
96+
<emphasis>
97+
Default value is <quote>,</quote>.
98+
</emphasis>
99+
</para>
100+
<example>
101+
<title>Set <varname>delimiter</varname> parameter</title>
102+
<programlisting format="linespecific">
103+
...
104+
modparam("event_flatstore", "delimiter", ";")
105+
...
106+
</programlisting>
107+
</example>
108+
</section>
109+
<section id="param_escape_delimiter" xreflabel="escape_delimiter">
110+
<title><varname>escape_delimiter</varname> (string)</title>
111+
<para>
112+
Optional replacement sequence that will be written <emphasis>instead
113+
of</emphasis> the <link linkend="param_delimiter"><varname>delimiter</varname></link>
114+
whenever this character (or sequence) occurs inside a string
115+
parameter.
116+
This allows you to keep the log file parse-friendly even when user
117+
data itself may contain delimiter symbols.
118+
</para>
119+
<para>
120+
If set, its length <emphasis>must be exactly equal</emphasis> to the
121+
length of <varname>delimiter</varname>.
122+
</para>
123+
<para>
124+
<emphasis>
125+
Default value is <quote>""</quote> (escaping disabled).
126+
</emphasis>
127+
</para>
128+
<example>
129+
<title>Enable escaping of ',' with '|'</title>
130+
<programlisting format="linespecific">
131+
...
132+
modparam("event_flatstore", "delimiter", ",")
133+
modparam("event_flatstore", "escape_delimiter", "|")
134+
...
135+
</programlisting>
136+
</example>
137+
</section>
138+
<section id="param_file_permissions" xreflabel="file_permissions">
139+
<title><varname>file_permissions</varname> (string)</title>
140+
<para>
141+
Sets the permissions for the newly created logs. It
142+
expects a string representation of a octal value.
143+
</para>
144+
<para>
145+
<emphasis>
146+
Default value is <quote>644</quote>.
147+
</emphasis>
148+
</para>
149+
<example>
150+
<title>Set <varname>file_permissions</varname> parameter</title>
151+
<programlisting format="linespecific">
152+
...
153+
modparam("event_flatstore", "file_permissions", "664")
154+
...
155+
</programlisting>
156+
</example>
157+
</section>
158+
<section id="param_suppress_event_name" xreflabel="suppress_event_name">
159+
<title><varname>suppress_event_name</varname> (int)</title>
160+
<para>
161+
Suppresses the name of the event in the log file.
162+
</para>
163+
<para>
164+
<emphasis>
165+
Default value is <quote>0/OFF</quote> (the event's name is printed).
166+
</emphasis>
167+
</para>
168+
<example>
169+
<title>Set <varname>suppress_event_name</varname> parameter</title>
170+
<programlisting format="linespecific">
171+
...
172+
modparam("event_flatstore", "suppress_event_name", 1)
173+
...
174+
</programlisting>
175+
</example>
176+
</section>
177+
<section id="param_rotate_period" xreflabel="rotate_period">
178+
<title><varname>rotate_period</varname> (int)</title>
179+
<para>
180+
When used, it triggers a file auto-rotate. The period is matched
181+
against the absolute time of the machine, can be useful to trigger
182+
auto-rotate every minute, or every hour.
183+
</para>
184+
<para>
185+
<emphasis>
186+
Default value is <quote>0/OFF</quote> (the file is never auto-rotated)
187+
</emphasis>
188+
</para>
189+
<example>
190+
<title>Set <varname>rotate_period</varname> parameter</title>
191+
<programlisting format="linespecific">
192+
...
193+
modparam("event_flatstore", "rotate_period", 60) # rotate every minute
194+
modparam("event_flatstore", "rotate_period", 3660) # rotate every hour
195+
...
196+
</programlisting>
197+
</example>
198+
` </section>
199+
<section id="param_rotate_count" xreflabel="rotate_count">
200+
<title><varname>rotate_count</varname> (int|string)</title>
201+
<para>
202+
Defines after how many written lines the log file is rotated.
203+
The value may exceed the 32-bit integer limit; in that case pass
204+
it <emphasis>as a string</emphasis>, e.g. "5000000000".
205+
</para>
206+
<para><emphasis>Default value is <quote>0/OFF</quote>.</emphasis></para>
207+
<example>
208+
<title>Rotate after five billion lines</title>
209+
<programlisting format="linespecific">
210+
...
211+
modparam("event_flatstore", "rotate_count", "5000000000")
212+
...
213+
</programlisting>
214+
</example>
215+
</section>
216+
<section id="param_rotate_size" xreflabel="rotate_size">
217+
<title><varname>rotate_size</varname> (int|string)</title>
218+
<para>
219+
Sets the maximum size of a file before it is rotated. A size
220+
suffix of <quote>k</quote>, <quote>m</quote> or <quote>g</quote>
221+
(multiples of 1024) may be provided.
222+
Very large values can be supplied as strings, e.g.
223+
"8589934592" for 8 GiB.
224+
</para>
225+
<para><emphasis>Default value is <quote>0/OFF</quote>.</emphasis></para>
226+
<example>
227+
<title>Rotate at 2 GiB</title>
228+
<programlisting format="linespecific">
229+
...
230+
modparam("event_flatstore", "rotate_size", "2g")
231+
...
232+
</programlisting>
233+
</example>
234+
</section>
235+
<section id="param_suffix" xreflabel="suffix">
236+
<title><varname>suffix</varname> (string)</title>
237+
<para>
238+
Modifies the file that &osips; writes events into by
239+
appending a suffix to the the file specified in the flatstore
240+
<emphasis>socket</emphasis>.
241+
</para>
242+
<para>
243+
The suffix can contain string formats (i.e. variables mixed with
244+
strings). The path of the resulted file is evaluated when the first
245+
event is raised/written in the file after a reload happend, or when
246+
the <emphasis>rotate_period</emphasis>, if specified, triggers a rotate.
247+
</para>
248+
<para>
249+
This parameter does not affect the matching of the event socket -
250+
the matching will be done exclusively using the flatstore
251+
<emphasis>socket</emphasis> registered.
252+
</para>
253+
<para>
254+
<emphasis>
255+
Default value is <quote>""</quote> (no suffix is added)
256+
</emphasis>
257+
</para>
258+
<example>
259+
<title>Set <varname>suffix</varname> parameter</title>
260+
<programlisting format="linespecific">
261+
...
262+
modparam("event_flatstore", "suffix", "$time(%Y)")
263+
...
264+
</programlisting>
265+
</example>
266+
</section>
267+
</section>
268+
<section id="exported_functions" xreflabel="exported_functions">
269+
<title>Exported Functions</title>
270+
<para>
271+
No exported functions to be used in the configuration file.
272+
</para>
273+
</section>
274+
275+
<section id="exported_mi_functions" xreflabel="Exported MI Functions">
276+
<title>Exported MI Functions</title>
277+
<section id="mi_rotate" xreflabel="event_flatstore:rotate">
278+
<title>
279+
<function>event_flatstore:rotate</function>
280+
</title>
281+
<para>
282+
Replaces obsolete MI command: <emphasis>evi_flat_rotate</emphasis>.
283+
</para>
284+
285+
<para>
286+
It makes the processes reopen the file specified as a parameter to the command in order to be compatible with a logrotate command. If the function is not called after the mv command is executed, the module will continue to write in the renamed file.
287+
</para>
288+
<para>
289+
Name: <emphasis>event_flatstore:rotate</emphasis>
290+
</para>
291+
<para>Parameters: <emphasis>path_to_file</emphasis></para>
292+
<para>
293+
MI FIFO Command Format:
294+
</para>
295+
<programlisting format="linespecific">
296+
opensips-cli -x mi event_flatstore:rotate _path_to_log_file_
297+
</programlisting>
298+
</section>
299+
</section>
300+
301+
<section id="exported_events" xreflabel="Exported Events">
302+
<title>Exported Events</title>
303+
304+
<section id="event_E_FLATSTORE_ROTATION" xreflabel="E_FLATSTORE_ROTATION">
305+
<title>
306+
<function moreinfo="none">E_FLATSTORE_ROTATION</function>
307+
</title>
308+
309+
<para>
310+
The event is raised every time <emphasis>event_flatstore</emphasis>
311+
opens a new log file (manual <command>event_flatstore:rotate</command>,
312+
auto-rotate by <varname>rotate_period</varname>, or
313+
thresholds <varname>rotate_count</varname>/<varname>rotate_size</varname>).
314+
External apps can subscribe to monitor log-rotation activity.
315+
</para>
316+
317+
<para>Parameters:</para>
318+
<itemizedlist>
319+
<listitem><para>
320+
<emphasis>timestamp</emphasis> – Unix epoch (seconds) when the
321+
rotation was performed.
322+
</para></listitem>
323+
<listitem><para>
324+
<emphasis>reason</emphasis> – one of the strings
325+
<emphasis>count</emphasis>, <emphasis>size</emphasis>,
326+
<emphasis>period</emphasis> or <emphasis>mi</emphasis>.
327+
</para></listitem>
328+
<listitem><para>
329+
<emphasis>filename</emphasis> – full path of the new log file.
330+
</para></listitem>
331+
<listitem><para>
332+
<emphasis>old_filename</emphasis> – full path of the previous
333+
log file, or empty string if none existed.
334+
</para></listitem>
335+
</itemizedlist>
336+
</section>
337+
</section>
338+
</chapter>

0 commit comments

Comments
 (0)