Skip to content

Commit 1cc05a6

Browse files
nikbytenikbyte
authored
event_flatstore improvements (#3649)
* event_flatstore: add time-based rotation (thanks and credits to @razvancrainea) * event_flatstore: add line count-based and size-based rotation, and rotation event * event_flatstore: add escape_delimiter parameter to replace delimiters inside field values * event_flatstore: replace deprecated IPC call with ipc_send_rpc_all()
1 parent 7cf0ad4 commit 1cc05a6

3 files changed

Lines changed: 620 additions & 16 deletions

File tree

‎modules/event_flatstore/doc/event_flatstore_admin.xml‎

Lines changed: 163 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
<chapter>
44

55
<title>&adminguide;</title>
6-
6+
77
<section id="overview" xreflabel="Overview">
88
<title>Overview</title>
99
<para>
@@ -48,11 +48,11 @@
4848
</itemizedlist>
4949
</para>
5050
</section>
51-
</section>
51+
</section>
5252
<section>
5353
<title>External Libraries or Applications</title>
5454
<para>
55-
The following libraries or applications must be installed before
55+
The following libraries or applications must be installed before
5656
running &osips; with this module loaded:
5757
<itemizedlist>
5858
<listitem>
@@ -106,6 +106,35 @@ modparam("event_flatstore", "delimiter", ";")
106106
</programlisting>
107107
</example>
108108
</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>
109138
<section id="param_file_permissions" xreflabel="file_permissions">
110139
<title><varname>file_permissions</varname> (string)</title>
111140
<para>
@@ -142,6 +171,96 @@ modparam("event_flatstore", "file_permissions", "664")
142171
...
143172
modparam("event_flatstore", "suppress_event_name", 1)
144173
...
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+
...
145264
</programlisting>
146265
</example>
147266
</section>
@@ -169,11 +288,47 @@ modparam("event_flatstore", "suppress_event_name", 1)
169288
<para>
170289
MI FIFO Command Format:
171290
</para>
172-
<programlisting format="linespecific">
173-
opensips-cli -x mi evi_flat_rotate _path_to_log_file_
291+
<programlisting format="linespecific">
292+
opensips-cli -x mi evi_flat_rotate _path_to_log_file_
174293
</programlisting>
175-
</section>
176-
</section>
177-
</chapter>
294+
</section>
295+
</section>
296+
297+
<section id="exported_events" xreflabel="Exported Events">
298+
<title>Exported Events</title>
178299

300+
<section id="event_E_FLATSTORE_ROTATION" xreflabel="E_FLATSTORE_ROTATION">
301+
<title>
302+
<function moreinfo="none">E_FLATSTORE_ROTATION</function>
303+
</title>
304+
305+
<para>
306+
The event is raised every time <emphasis>event_flatstore</emphasis>
307+
opens a new log file (manual <command>evi_flat_rotate</command>,
308+
auto-rotate by <varname>rotate_period</varname>, or
309+
thresholds <varname>rotate_count</varname>/<varname>rotate_size</varname>).
310+
External apps can subscribe to monitor log-rotation activity.
311+
</para>
179312

313+
<para>Parameters:</para>
314+
<itemizedlist>
315+
<listitem><para>
316+
<emphasis>timestamp</emphasis> – Unix epoch (seconds) when the
317+
rotation was performed.
318+
</para></listitem>
319+
<listitem><para>
320+
<emphasis>reason</emphasis> – one of the strings
321+
<emphasis>count</emphasis>, <emphasis>size</emphasis>,
322+
<emphasis>period</emphasis> or <emphasis>mi</emphasis>.
323+
</para></listitem>
324+
<listitem><para>
325+
<emphasis>filename</emphasis> – full path of the new log file.
326+
</para></listitem>
327+
<listitem><para>
328+
<emphasis>old_filename</emphasis> – full path of the previous
329+
log file, or empty string if none existed.
330+
</para></listitem>
331+
</itemizedlist>
332+
</section>
333+
</section>
334+
</chapter>

0 commit comments

Comments
 (0)