Chain Targets
Chain Targets
Stumpless offers a lot of targets for different types of logging. These targets are all carefully confined to a single endpoint though - you can’t easily create a target that will send log messages to multiple places. For example a file target that logs to two files isn’t possible.
Instead of manually sending messages to each desired target, you can instead use a chain to compose several different targets together. Log entries sent to the chain will be sent to each of the targets within, allowing for a sequence of targets that can simplify the logging calls in your own application.
The interface for chain targets themselves is simple but effective. Chains can be nested within one another, and when combined with other features such as filters can be used to create relatively complex logging chains.
A Simple Sequence
Making a basic chain with just a few targets is straightforward. First, create the chain, and then add the targets you want to be included.
First, let’s make our targets for the chain. We’ll start with a simple model where we send messages to both a file and stdout.
file_target = stumpless_open_file_target( "chain-example.log" );
stdout_target = stumpless_open_stdout_target( "chain-example-stdout" );
Next, let’s apply a filter so that the output on the console doesn’t get too overwhelming. We’ll apply a mask so that messages lower than info severity aren’t printed out, as well as messages of the highest severity since we will handle those differently. If you want to see more about how to use masks to filter messages, check out the filter example.
mask = STUMPLESS_SEVERITY_MASK_UPTO( STUMPLESS_SEVERITY_INFO )
& ~STUMPLESS_SEVERITY_MASK_UPTO( STUMPLESS_SEVERITY_ERR );
stumpless_set_target_mask( stdout_target, mask );
Now for the main event: making the chain itself! It’s pretty straightforward.
// create a new chain
simple_chain = stumpless_new_chain( "example-simple-chain" );
// add our targets to the chain
stumpless_add_target_to_chain( simple_chain, stdout_target );
stumpless_add_target_to_chain( simple_chain, file_target );
Sending messages to this chain is also simple: we just treat it the same as any other target! This will create an entry in the file, as well print an entry to stdout.
stumpless_add_message( simple_chain, "simple chain message" );
Nesting Chains
Chains also allow us to create hierarchical logging structures. To do this, we add chains to other chains, applying filters along the way to control message flow down to lower levels.
To show this, we’ll create two more chains. First, an error chain that will send high-level errors to stderr, as well as to a log buffer where we can investigate them in our application later.
stderr_target = stumpless_open_stderr_target( "chain-example-stderr" );
error_buffer_target = stumpless_open_buffer_target( "chain-example-buffer",
error_buffer,
sizeof( error_buffer ) );
error_chain = stumpless_new_chain( "example-error-chain" );
stumpless_add_target_to_chain( error_chain, stderr_target );
stumpless_add_target_to_chain( error_chain, error_buffer_target );
mask = STUMPLESS_SEVERITY_MASK_UPTO( STUMPLESS_SEVERITY_ERR );
stumpless_set_target_mask( error_chain, mask );
Next, we create a top-level chain, and put our previous two chains into it. This is the chain that we’ll use as our actual logging target.
main_chain = stumpless_new_chain( "example-main-chain" );
stumpless_add_target_to_chain( main_chain, error_chain );
stumpless_add_target_to_chain( main_chain, simple_chain );
Now lets send some messages through the chain.
stump_em( "emergency!" );
stump_a( "alert!" );
stump_c( "critical!" );
stump_er( "error!" );
stump_w( "warning..." );
stump_n( "notice" );
stump_i( "informational" );
stump_d( "debug" );
stump_d( "trace" );
When we run this program, we see the following output. If you have special
highlighting rules or other handling for stderr you’ll see the difference
between messages that were sent to it instead of standard output, but you may
not otherwise.
# these messages are sent to stderr
<8>1 2024-03-27T12:11:05.815725Z Angus - - - - emergency!
<9>1 2024-03-27T12:11:05.815734Z Angus - - - - alert!
<10>1 2024-03-27T12:11:05.815741Z Angus - - - - critical!
<11>1 2024-03-27T12:11:05.815748Z Angus - - - - error!
# and these appear on stdout
<12>1 2024-03-27T12:11:05.815755Z Angus - - - - warning...
<13>1 2024-03-27T12:11:05.815760Z Angus - - - - notice
<14>1 2024-03-27T12:11:05.815765Z Angus - - - - informational
# note that debug messages are missing, since they were filtered from stdout
All of the messages appear in our file, including the debug information:
<8>1 2024-03-27T12:11:05.815732Z Angus - - - - emergency!
<9>1 2024-03-27T12:11:05.815739Z Angus - - - - alert!
<10>1 2024-03-27T12:11:05.815746Z Angus - - - - critical!
<11>1 2024-03-27T12:11:05.815753Z Angus - - - - error!
<12>1 2024-03-27T12:11:05.815758Z Angus - - - - warning...
<13>1 2024-03-27T12:11:05.815763Z Angus - - - - notice
<14>1 2024-03-27T12:11:05.815768Z Angus - - - - informational
<15>1 2024-03-27T12:11:05.815770Z Angus - - - - debug
<15>1 2024-03-27T12:11:05.815773Z Angus - - - [trace file="stumpless/docs/examples/chain/chain_example.c" line="84" function="main"] trace
And finally, let’s run a check on the contents of our error buffer, to see if there’s anything that we need to know about.
printf( "\nerrors logged in memory:\n" );
do {
read_size = stumpless_read_buffer( error_buffer_target,
message_buffer,
sizeof( message_buffer ) );
printf( "%s\n", message_buffer );
} while( read_size > 1 );
This portion of the output looks like this:
errors logged in memory:
<8>1 2024-03-27T12:11:05.815730Z Angus - - - - emergency!
<9>1 2024-03-27T12:11:05.815737Z Angus - - - - alert!
<10>1 2024-03-27T12:11:05.815744Z Angus - - - - critical!
<11>1 2024-03-27T12:11:05.815751Z Angus - - - - error!
Finally, we need to clean up. Chains make this pretty easy, providing a
destructor to close all targets within them as well (including other chains).
If you’d rather only close the chain, use stumpless_close_chain_only instead.
stumpless_close_chain_and_contents( main_chain );
stumpless_free_all( );