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
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head><title>Compatibility notes for rsyslog v8</title>
</head>
<body>
<h1>Compatibility Notes for rsyslog v8</h1>
This document describes things to keep in mind when moving from v7 to v8. It
does not list enhancements nor does it talk about compatibility concerns introduced
by earlier versions (for this, see their respective compatibility documents). Its focus
is primarily on what you need to know if you used v7 and want to use v8 without hassle.
<p>Version 8 offers a completely rewritten core rsyslog engine. This resulted in
a number of changes that are visible to users and (plugin) developers.
Most importantly, pre-v8 plugins <b>do not longer work</b> and need to
be updated to support the new calling interfaces. If you developed a plugin,
be sure to review the developer section below.
</p>
<h2>Mark Messages</h2>
<p>In previous versions, mark messages were by default only processed if an
action was not executed for some time. The default has now changed, and mark
messages are now always processed. Note that this enables faster processing
inside rsyslog. To change to previous behaviour, you need to add
action.writeAllMarkMessages="off" to the actions in question.
<h2>What Developers need to Know</h2>
<h3>output plugin interface</h3>
<p>To support the new core engine, the output interface has been considerably
changed. It is suggested to review some of the project-provided plugins for
full details. In this doc, we describe the most important changes from a high
level perspective.
<p><b>Multi-thread awareness required</b></p>
<p>The new engine activates one <b>worker</b>instance of output actions on
each worker thread. This means an action has now three types of data:
<ul>
<li>global
<li>action-instance - previously known pData, one for each action inside the config
<li>worker-action-instance - one for each worker thread (called pWrkrData), note
that this is specific to exactly one pData
</ul>
The plugin <b>must</b> now by multi-threading aware. It may be called by multiple
threads concurrently, but it is guaranteed that each call is for a unique
pWrkrData structure. This still permits to write plugins easily, but enables the
engine to work with much higher performance. Note that plugin developers
should assume it is the norm that multiple concurrent worker action instances
are active a the some time.
<p><b>New required entry points</b></p>
<p>In order to support the new threading model, new entry points are required.
Most importantly, only the plugin knows which data must be present in pData and
pWrkrData, so it must created and destroy these data structures on request of
the engine. Note that pWrkrData may be destroyed at any time and new ones
re-created later. Depending on workload structure and configuration, this can happen
frequently.
<p>New entry points are:
<ul>
<li>createWrkrInstance
<li>freeWrkrInstance
</ul>
The calling interface for these entry points has changed. Basically,
they now receive a pWrkrData object instead pData. It is assumed that
createWrkrInstance populates pWrkrData->pData appropriately.
<ul>
<li>beginTransaction
<li>doAction
<li>endTransaction
</ul>
<p><b>RS_RET_SUSPENDED is no longer supported when creating an action instance</b>
<p>This means a plugin must not try to establish any connections or the like
before any of its processing entry points (like beginTransaction or doAction)
is called. This was generally also the case von v7, but was not enforced in
all cases. In v8, creating action creation fails if anything but RS_RET_OK
is returned.
<a href="http://www.rsyslog.com/g/BSD">rsyslog BSD blocks info</a>
page for more information and how to upgrade your config.
<p>[<a href="manual.html">manual index</a>] [<a href="http://www.rsyslog.com/">rsyslog site</a>]</p>
<p><font size="2">This documentation is part of the
<a href="http://www.rsyslog.com/">rsyslog</a> project.<br>
Copyright © 2013 by <a href="http://www.gerhards.net/rainer">Rainer Gerhards</a> and
<a href="http://www.adiscon.com/">Adiscon</a>. Released under the GNU GPL
version 2 or higher.</font></p>
</body></html>
|
