[DOC] update channel and output part

[Messj1]

Hi

I used ulog in a AMD environment with an high order channel which override the output channel if config highorder_log level get reached.
ulog is a really nice project for such extending stuff. 💪

Would be nice to have some hints in the documentation. So i rewrote the channel an output part cause the channel configuration is part of channel and not the output. Output doesn't get configured at all 😉

Hope this helps.

Channels

In ulog, logging is always "sent" to exactly one channel. The channel get selected by the configuration. It can also be selected by extending ulog with a mod. (see Custom channel selection )
A channel has one or more configurable outputs that can optionally apply formatting to the message.
By default, two channels exist:

• output, for messages of loggers that are in debug mode, or that are at an enabled level
• drain, for those messages that are filtered away.

Channel selection

By having a separate channel for the drain, there is the opportunity to use another output than noop(link). So you can configure where discarded messages are going.
For example: send all logging records to a database and filter it later, when it get display for example (see output)

By default all log methods on a logger are associated with one of two channels, output and drain. When the logger is created, each log method is sent either to the output channel, or to the drain channel, based on the current log level for that logger and whether that logger is in debug mode.
To configure the drain / output channel selection the following log config can be used:

log := log_setting [; log_setting] ...
log_setting:= [ logger_name [, logger_name] ... = ] log_level
log_level:= [all | error | warn | info | debug | trace | none]
logger_name:= [ * | [-]{regular expression} ]

Custom channel selection

If the default behavior is not enough the channel selection in ulog can easily be extended like followed:

ulog.use({
    after: function (logger) {
        for (var level in this.levels) {
            var channel = logger.enabledFor(level) ? 'output': 'drain';
            // calculate new channel
            logger[level] = logger.channels[channel].fns[level];
        }
    },
});

Output configuration

The channel output, where messages are going, is completely configurable at runtime.
To configure the outputs for a channel, use the log_ config option. The default channels config options are:

• log_output, defaults to console
• log_drain, defaults to noop

To configure the output for a channel, we assign the name of the output to use to the relevant loggers:

log_output=console

This setting can include expressions to target individual loggers, just like the debug and log settings:

log_output=console;noisy-lib:*=noop

The value part is actually a kurly format string. The same syntax can be used here as for configuring formatting.
If more than one output is specified, a multiplex function will be inserted that dispatches the logging to all specified outputs.

log_output=console custom_output

Syntax:

log_channel := channel_setting [; channel_setting] ...
channel_setting:= [ logger_name [, logger_name] ... = ] output_name [ output_name] ...
logger_name:= [ * | [-]{regular expression} ]
output_name:= defined outputs in ulog

Hint: The first match get used. Except the default logger_name (*)

Outputs

Outputs are used in channels to peform the actual task and "log" the data.
By default, the following outputs are included:

Output console

...

Output noop

...

[Download]

@Messj1 Wow another great issue! Thanks! You really invested time in this. That is so great. Thank you.

May I ask have you ever contributed to an Open Source project before? Would you like to give it a shot?
I can learn you how to make a pull request and how to contribute your changes to this project. Let me know if this is something you would like to try.

[Messj1]

@Download What do you think about a mini tutorial with the high_order channel mods i wrote as an example:
https://github.com/FriendsOfTYPO3/frontend_editing/blob/master/Resources/Public/JavaScript/Utils/LoggerPersist.js

• Create highorder ulog channel.
• Creates 2 ulog outputs to persist
  • persist: with indexedDb in use
  • server: calling the sendCallback function

[Download]

@Messj1 Yes that's also an option.
But any changes to the code should happen via Pull Requests. This is why I asked you to create one :)