Review docs and enhance cover of "variables": global, JSON message properties, local variables and "properties"

[deoren]

From a mailing list post:

I am set the variables and using them in filters. But the following are not working as expected or not working at all.
Appreciate if you can share a working example or suggest what i am doing wrong.

Not Working:
set $!configuredseverity = "3";
if ($syslogseverity <= $configuredseverity)

Defaults to severity 7:
set $!configuredseverity = 3;
if ($syslogseverity <= $configuredseverity)

My response:

rsyslog has three types of "variables":

• global variables
• JSON message properties
• local variables

rsyslog also has "properties". The syntax used to access the variables and properties differs slightly depending on the configuration format syntax that you use to access them which is unfortunate, but needed for backwards compatibility (at least for now).

The syntax and scope of each also differs.

This PDF[3] of an article by David Lang gives a great overview of rsyslog as a whole, but in particular the syntax used to access each "variable" type. See the "User Variables" section of the PDF for details.

In your case, I believe (untested) that this is probably the syntax you're looking for:

set $!configuredseverity = "3";
if ($syslogseverity &lt;= $!configuredseverity) then {
doSomethingHere
}

Note the '$!' prefix for configuredseverity. The '$!' is needed when referencing JSON message properties. This is covered in the rsyslog docs, but here and there. For now, I recommend looking at the PDF instead for a concise overview.

References:

[1] http://www.rsyslog.com/doc/v8-stable/configuration/properties.html

[2] http://www.rsyslog.com/doc/v8-stable/rainerscript/variable_property_types.html

[3] https://www.usenix.org/publications/login/october-2013-volume-38-number-5/log-filtering-rsyslog

While it could have just been me flailing about in fatigue, I suspect that the information is spread thinly throughout the docs.

It would be good to find the most appropriate section and enhance it to cover everything I mentioned plus any supporting information that would be useful. We could then reference that section (via an explicit label) in other places to ease maintenance, create an include page with succinct coverage or (perhaps the better approach) do both.

I'm not sure of any potential permissions issues with using the material, but @davidelang's coverage of the topic in his Log Filtering with Rsyslog ;login article is especially good.

[davidelang]

I'm not sure of any potential permissions issues with using the material, but @davidelang's coverage of the topic in his [Log Filtering with Rsyslog](https://www.usenix.org/publications/login/october-2013-volume-38-number-5/log-filtering-rsyslog) `;login` article is especially good.

I have no problem with you using that explination.

[deoren]

@davidelang Awesome, thanks!

[deoren]

@davidelang I was looking back through the mailing list for something else and came across this response from you last year:

there is almost no technical difference between $. variables and $! variables.

$! existed first, and some functions (mmjsonparse) only put things in $!

$. was created because there is a need to have variables that aren't part of $! so that $! can be output in it's entirety.

The global variables $\ are significantly different, much slower, but visible across multiple log messages (and multiple threads), while $! and $. exist only for the one log message.

Adding it here as further reference material for when this ticket is processed.

You have a talent for conveying depth with brevity. :)

[davidelang]

On Wed, 14 Mar 2018, Deoren Moor wrote: @davidelang I was looking back through the mailing list for something else and came across this response from you last year: > there is almost no technical difference between $. variables and $! variables. > > $! existed first, and some functions (mmjsonparse) only put things in $! > > $. was created because there is a need to have variables that aren't part of $! so that $! can be output in it's entirety. > > The global variables $\ are significantly different, much slower, but visible across multiple log messages (and multiple threads), while $! and $. exist only for the one log message. Adding it here as further reference material for when this ticket is processed. You have a talent for conveying depth with brevity. :)

normally I'm told I put too much detail in :-)

[deoren]

@davidelang: normally I'm told I put too much detail in :-)

Down with the naysayers! ;) I've learned a lot reading your writings and appreciate the time you've taken to provide them.

Aside from the articles here (https://www.usenix.org/publications/login/david-lang-series), your writings on GitHub, the mailing list and the docs project, do you publish content elsewhere?

[davidelang]

On Wed, 14 Mar 2018, Deoren Moor wrote: > @davidelang: normally I'm told I put too much detail in :-) Down with the naysayers! ;) I've learned a lot reading your writings and appreciate the time you've taken to provide them. Aside from the articles here (https://www.usenix.org/publications/login/david-lang-series), your writings on GitHub, the mailing list and the docs project, do you publish content elsewhere?

I post on many different mailing lists and a few web forums (most of which have a mailing list mode), but I don't have a blog or anyplace else that I create content for. I don't think the last article in the series ever got linked on that page (splung/ElasticSearch tuning) David Lang

[deoren]

@davidelang: I don't think the last article in the series ever got linked on that page
(splung/ElasticSearch tuning)

Is this the article you're referring to?

"Large Scale Splunk Tuning" at https://www.usenix.org/publications/login/april14/lang

[davidelang]

On Thu, 15 Mar 2018, Deoren Moor wrote: > @davidelang: I don't think the last article in the series ever got linked on that page > (splung/ElasticSearch tuning) Is this the article you're referring to? "Large Scale Splunk Tuning" at https://www.usenix.org/publications/login/april14/lang

Yep, that's the one.

[deoren]

Note to self: https://serverfault.com/questions/896230/how-to-use-global-variables-in-rsyslogd-v8

[atc0005]

Saw these remarks elsewhere from @rgerhards, figured the notes were relevant here (though the context for each may not be sufficiently clear for each remark to stand by itself as included here):

global variable updates are guarded by a mutex. So they are atomic.

---

https://www.rsyslog.com/doc/master/rainerscript/variable_property_types.html?highlight=variables

---

Set the var e.g. to zero and then increment it whenever you need. There is also a random function which you can use to init.