Add ability to get the root-router

[ferbar]

What this PR does / why we need it:
This patch adds a way in event_emitter_router(label_name) to get the root event router. To use an empty string "" for the default router is just a proposal, maybe @DEFAULT would fit better.
Why I needed it:
I did not see another way to get an event it is once assigned to a label back the default route. The concat filter can send timedout events to a special label. With the route plugin the tag can be prefixed and with @label "" the event can be sent to the default filters and output.

Docs Changes:
Will be updated if there is any interest.

Release Note:
Enable to get root router by Fluent::PluginHelper::EventEmitter::event_emitter_router("@ROOT")

[ashie]

Please add tests for it.

[ashie]

I'm not sure adding it and candidates of the label (Empty or @DEFAULT or @ROOT) name are reasonable or not.
@repeatedly Do you have any opinions?

[ferbar]

@ashie please let me know how to continue. I'm afraid someone is already using @DEFAULT, so @ROOT would probably be better. Thanks!

[repeatedly]

candidates of the label (Empty or @default or @root) name are reasonable or not.

We use ROOT in some places, so @ROOT is better than @DEFAULT and others.

fluentd/lib/fluent/config/v1_parser.rb

Line 44 in da162e1

root = Element.new('ROOT', '', attrs, elems)

[ashie]

@ferbar Could you replace with @ROOT and add unit test?
If you hard to add unit test, please let me know, we'll add it instead.

[ferbar]

@ashie I changed '' to '@root', will test it tomorrow. I'm sorry I don't get it with the unit-tests. I found test/plugin_helper/test_event_emitter.rb, but I didn't find out how to do the

assert(event_emitter_router("@ROOT" == Engine.root_agent.event_router)

I will check what
<label @ROOT>
will do. That should probably be prevented...

Thanks!

[ashie]

I've added tests for event_emitter_router.

But ... I'm now doubting to use the label name @ROOT as a reserved word in this context.
I am sorry that I repeat the discussion...

Because it's too simple, users might be already using it in their configurations. It means it breaks backward compatibility.
Although the prefix @ is known as reserved word in Fluentd's configuration file, I think it's not applicable for label names because example configurations in the document uses @ prefix as label names. Most users use @ prefix as label names since the document exemplify it, it's not always necessary though.

When we add a new reserved word, we should ensure to select a word which is used rarely.
e.g.)

• @ROOT_EVENT_ROUTER
• @__ROOT__
• ...

How do you think about it? @cosmo0920 @kenhys @repeatedly

[kenhys]

• @__ROOT__

It may be better.
And another idea, how about @__ROOT__@ or @ROOT@ (with prefix @ and suffix @ )
I makes easy to distinct a bit.

[ferbar]

I think this is the right place to check if someone is using the root_event_router in a label tag:
https://github.com/fluent/fluentd/blob/master/lib/fluent/root_agent.rb#L133

[ashie]

BTW fluentd has a built-in label @ERROR.
To keep consistency of naming-convention, @ROOT might be better than names like @__ROOT__.

[ferbar]

Added an error message for

<label @ROOT>
  <match debug.**>
    @type stdout
    @id stdout_output
  </match>
</label>

2021-07-29 15:08:16 +0200 [info]: parsing config file is succeeded path="fluent.conf"
2021-07-29 15:08:16 +0200 [error]: config error file="fluent.conf" error_class=Fluent::ConfigError error="Invalid label name (@ROOT)"

[ashie]

Added an error message for

<label @ROOT>
  <match debug.**>
    @type stdout
    @id stdout_output
  </match>
</label>

2021-07-29 15:08:16 +0200 [info]: parsing config file is succeeded path="fluent.conf"
2021-07-29 15:08:16 +0200 [error]: config error file="fluent.conf" error_class=Fluent::ConfigError error="Invalid label name (@ROOT)"

Thanks, now it can notify users about incompatibility of config file.
Let's go with this.

[ferbar]

@ashie, @cosmo0920:

Should we add some documentation on these pages:
https://docs.fluentd.org/configuration/config-file#error-label

https://docs.fluentd.org/configuration/routing-examples

What about removing the @ in @SYSTEM @METRICS ?