Create a new API to standardize application tracing

[bobbingwide]

Having read #30934 and #28319, I think it's best if I raise a new requirement.

My proposal isn't about logging, it's related to problem determination tracing; the ability to dynamically activate trace logic to help someone to track down a problem.

I have been using my own solution ( a plugin called oik-bwtrace ) for a while now.

There are two dormant APIs that I need to make available at all times, even when tracing is not activated.

Since these functions are currently not available by default I've had to be careful where I use them. To circumvent the problem of trying to use an API which doesn't exist, many of my plugins have dependencies on a base plugin which supplies the dormant APIs.

Life would be a lot simpler if WordPress came with a set of dormant functions which I can rely on to exist.

This proposal is for two trace APIs. It could easily be extended to support logging.

The dormant APIs have the same basic structure

function dormant_api( easy to use parameters ) {
  global $api_set_active;
  if ( $api_set_active ) {
    lazy_api( easy to use parameters );
  }
}

In this example $api_set_active is just a boolean.
It's set to true when the API logic is activated, false otherwise.

To cater for different levels of tracing ( or logging ) we can either implement the test in the dormant API, or pass it to the lazy_api().

This solution is different from 'pluggable'.
The dormant APIs need to exist, from very early on.
The lazy APIs are provided by implementing plugins and should be implemented as pluggable.

The two APIs I really do need are currently called bw_trace2() and bw_backtrace().

I've attached the latest version of my shared library file that defines these APIs and the constants they use.

Assuming that these APIs will be required to trace WordPress core logic I feel that they need to have been defined early on in wp-settings.php

I therefore propose a new file called dormant.php which can, if the developer so wishes, be included in wp-config.php but would otherwise be loaded in wp-settings.php before load.php.

Note: It's the implementing plugin's responsibility to know when it's safe to do things.
In my implementation of a hook for the 'all' action I've used multiple strategies which involve loading my APIs in wp-config.php before wp-settings.php, using a Must-Use plugin to be able to record most hooks, but requiring a custom db.php to be able to capture everything. I can't do it before db.php since add_action()'s not available until then.

[bobbingwide]

Some dormant APIs required for problem determination tracing

[jorbin]

I'm having a bit of a difficult time understanding this proposal. Perhaps you can help:

It sounds like you would like some helpers for backtracing available? Is that correct? How are these helpers more valuable than debug_backtrace? How would you envision core using these APIs?

[bobbingwide]

Hi, the main differences between the APIs I'm proposing and the standard PHP logic are:

• ability to control when the output is produced - easily turn on / off the functionality
• output does not affect what the end user sees
• ability to provide lots of contextual information

The similarities are:

• API always available

In my oik-bwtrace plugin I have basically delivered two APIs: trace and backtrace

A simple call to the trace routine ( bw_trace2 ) will produce a lot more information than var_dump or print_r, will do it consistently and should be more robust.

The lazy_ versions of the APIs are pluggable, so they can be implemented in a variety of ways.

Whether or not core makes use of the APIs itself is a difficult question to answer.
When debugging a problem I often resort to adding trace and backtrace calls in my local copy.
More often and not they don't need to be permanent. The important thing is that they're easy to use and provide useful information.

The lazy_ versions of the APIs are pluggable, so they can be implemented in a variety of ways.
In my oik-bwtrace plugin ( ​https://wordpress.org/plugins/oik-bwtrace/ ) I've built a whole host of functionality to support advanced debugging and tracing of logic.

But everything is dependent on the initial dormant APIs.

[jdgrimes]

I used to do a lot of my debugging using var_dump(), error_log(), etc., and I had my own library of tools kind of like this. Then I started using xDebug and a proper IDE that integrated with its remote debugging API. This is definitely superior in most cases. The only time that I still use my own tools is if using xDebug isn't a possibility or isn't set up and I just need to do something real quick. In other words, I think it is much better to encourage people to use a different debugging workflow, especially for local development. As far as attempting to debug a live site goes, I can see where and API like this would be helpful (been there, done that). However, most problems will be plugin-related, and since it will be forever and a day before most plugins start using such an API in a helpful way, I'm not sure that it is worth pursuing. Of course you can always manually mark up plugin code with these functions during debugging. But you can already do that now, just as I used to do.

Anyway, I can just imagine that I thought this might be a pretty good idea when the ticket was first opened, but looking back I'm glad that I usually don't use a debugging workflow like this anymore. So I question whether it makes sense to promote this particular debugging workflow in core.

[bobbingwide]

Unfortunately in my experience there are many more situations where problems occur but a proper debug environment is not available.

Until we provide a common starting point, plugins and themes will continue to use home grown solutions for common problem determination.