diff options
Diffstat (limited to 'doc/v8compatibility.html')
| -rw-r--r-- | doc/v8compatibility.html | 82 |
1 files changed, 82 insertions, 0 deletions
diff --git a/doc/v8compatibility.html b/doc/v8compatibility.html new file mode 100644 index 00000000..37e8e31f --- /dev/null +++ b/doc/v8compatibility.html @@ -0,0 +1,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> |