Specify task/batch to be run with debugging enabled within code #1539

Current status quo

Currently it's possible to enable partial debug logging from within Rex code by setting $Rex::Logger::debug to a true value, and disable it with setting it to a false value.

This is a viable approach, but the recommended debugging approach is still to use -d instead, because that includes printing the important initialization context for the given run. Without that context, partial debug logs may be often misleading for the debugging person, and/or may be useless to post in bug reports.

Potential new feature

A task only needs a few things to be useful, and I would prefer to keep it tidy like that to preserve simplicity:

• name
• a default target (local machine, when omitted)
• a coderef to be executed

But there is an internally used options hashref that can be passed as the last parameter to task. Which is the closest already existing concept where it would be possible to accept a debug => {true|false} option which enables debugging at the start of the task and disable it again at the end of the task. Example syntax idea:

task 'debug_this_task', sub {
 say 'I want to debug this task';
}, { debug => TRUE, };

It might be a candidate for a feature request issue, but I'm afraid it has a high potential to raise more questions than it solves. I already wonder about things like:

1. Should we publish this optional internal control feature now, or should it remain internal (which affects a wide range of things from docs, through tests, to backwards compatibility guarantees, etc.)?
2. How exactly to inject the debug enable/disable triggers? Shall Rex internally rewrite the task's coderef (sounds nasty)? Should it re-use hooks (which may or may not trigger depending on how the task is being executed)? Should we add a new set of internal-only hooks for this (sounds to have a low impact/effort ratio)?
3. What are the possible interactions of the debug => {true|false} flag with the existing ways to control debug logs (-d CLI option, or $Rex::Logger::debug = {true|false})? What are the desired behaviors in each case?
4. Should (Can?!) we print the initialization context with partial debugging? How we can retroactively print init debug context in the middle of a task execution? Shall it be a different kind of "task debug context" instead of init context?

Does it worth it?

Overall, I'm not yet convinced about the return on the investment needed to explore, specify, and then implement these details with tests.

Even with my reservations about the missing debug context during initialization when while partially debugging, I find it way less effort and more precise to put a $Rex::Logger::debug = 1; where I would want to start getting debug output and then put a $Rex::Logger::debug = 0; where I want it to stop.

Of course, it's just my quick opinion, and that doesn't automatically mean I'm right about all the details. It's more of an initial list of aspects to be considered by someone who would like to hack on this.

More task debugging patterns

Thinking about this more, another useful pattern could be to trigger debug logging via task parameters, like:

task 'mytask', sub {
 my $parameters = shift;
 $Rex::Logger::debug = 1 if exists $parameters->{debug};
 say 'something';
 $Rex::Logger::debug = 0 if exists $parameters->{debug};
};

Then it can be run on the CLI as rex mytask as usual, but rex mytask --debug would enable debug logging at the start of the task, and disable it again at the end of the task. Note that --debug here is an argument passed to the task, not the rex executable. A variation of this could be to pass values to the argument as well, like rex mytask --debug=1.

If this pattern must be added to multiple tasks, then task hooks might be useful too:

# tasks
task 'mytask', sub {
 say 'something';
};
# task hooks
## replace ALL with a regex to match only some tasks by their name
before 'ALL' => sub {
 my ( $server, $server_ref, $cli_args ) = @_;
 $Rex::Logger::debug = 1 if exists $cli_args->{debug};
};
## replace ALL with a regex to match only some tasks by their name
after 'ALL' => sub {
 my ( $server, $failed, $cli_args ) = @_;
 $Rex::Logger::debug = 0 if exists $cli_args->{debug};
};

The hooks-based approach also prints out more debug context compared to the case where $Rex::Logger::debug is controlled from inside the task (but still not as much context as a global debug would print).

In summary, we have examples of how to control debug behavior various levels:

• from inside a task
• from task hooks to wrap a task as a whole
• globally

This also feels like a good demonstration of the "Rex is a framework, not a tool" mantra. While sometimes it's good to provide convenience shortcuts solutions for common situations into Rex core, the focus is on providing building blocks which enables users to build the tool their situation needs.

More notes for possible core implementation

Looking into this more, the following might be a viable implementation approach to address the second question from above:

• add a debug attribute to the task object constructor in Rex::Task->new() (and related methods as needed)
• set the value of the debug attribute during task creation of tasks according to { debug => {true|false} passed as (internal) task option (e.g. check it in Rex::TaskList::Base->create_task())
• check the value of the debug attribute just before/after running the task code and control the logging behavior accordingly (e.g. in Rex::Task->run())