diff options
Diffstat (limited to 'doc/v8compatibility.html')
| -rw-r--r-- | doc/v8compatibility.html | 119 |
1 files changed, 119 insertions, 0 deletions
diff --git a/doc/v8compatibility.html b/doc/v8compatibility.html new file mode 100644 index 00000000..549a7fef --- /dev/null +++ b/doc/v8compatibility.html @@ -0,0 +1,119 @@ +<!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>Modules WITHOUT v8 Support</h2> +<p>The following modules will not properly build under rsyslog v8 and +need to be updated: +<ul> +<li>plugins/omgssapi +<li>plugins/omhdfs +<li>plugins/omrabbitmq - not project supported +<li>plugins/omzmq3 - not project supported +<li>plugins/mmrfc5424addhmac - was a custom project, requires sponsoring + for conversion +<li>plugins/omoracle - orphaned since a while -- use omlibdbi instead +<li>plugins/mmsnmptrapd - waiting for demand +<li>plugins/mmcount - scheduled to be updated soon +</ul> + +<h2>Untested Modules</h2> +<p>The following modules have been updated and successfully +build, but no "real" test were conducted. Users of these modules +should use extra care. +<ul> +<li>mmsequence +<li>omprog +<li>omsnmp +<li>mmfields +<li>mmpstrucdata +<li>plugins/mmaudit +<li>omlibdbi - will be tested soon +<li>ommongodb - larger changes still outstanding +<li>ompgsql - larger chages still outstanding +<li>omuxsock +</ul> +<p>In addition to bug reports, success reports are also appreciated for +these modules (this may save us testing). + +<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>NOTE: the v8 output module interface is not yet stable.</b> It is highly +likely that additional changes will be made within the next weeks. So if you +convert a module now, be prepared for additional mandatory changes. + +<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. + +<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> |