# oik-bwtrace 
* Contributors: bobbingwide
* Donate link: http://www.oik-plugins.com/oik/oik-donate/
* Tags: debug, trace, backtrace, actions, filters, immediate trace
* Requires at least: 4.2
* Tested up to: 4.3
* Stable tag: 2.0.5
* License: GPLv2 or later
* License URI: http://www.gnu.org/licenses/gpl-2.0.html

## Description 
Debug trace for WordPress.

* The primary purpose of debug trace is to help in the development of PHP code: plugins or themes.
* The primary purpose of action trace is to help you understand the sequence of events in the server.
* This plugin provides the admin interface to trace functions and action and filter tracing built into plugins that use the oik / bw APIs.

Except for HTML comments, neither oik bwtrace nor oik action trace alters the output of your web pages.
They write their output to a file on the server which you can browse in a separate window.

You can also use the oik trace facilities to assist in problem determination in a live site.


Features:

* Easy to code APIs: bw_trace2(), bw_backtrace() and bw_trace()
* Tracing can be enabled programmatically
* Does not require WP_DEBUG to be defined
* Dynamically activates trace functions
* Implemented as lazy just-in-time code
* Provides contextual information
* Action trace counts help you understand the sequence of actions and filters
* Can be used during regression testing
* Traces ALL server functionality, including AJAX and other background requests
* Minimum performance overhead when tracing is not enabled
* Can be activated in wp-config.php and db.php to trace code before WordPress is fully loaded
* Does not need to be activated if started programmatically or from wp-config.php
* Ability to choose the IP address to trace, defaults to ALL requests
* Writes summary trace record for each transaction into a daily log
* Now operates as a standalone plugin; independent of the oik base plugin
* Integrated with oik-lib shared library management
* Backtraces deprecated logic messages
* Traces and backtraces PHP Error, Warning and Notice messages
* API supports multiple trace levels
* Supports tracing of user defined hooks


The trace record output can include:

* Fully qualified source file name
* Trace record count
* Time stamp
* Current filter information
* Number of database queries that have been performed.
* Current post ID
* Current and peak memory usage (in bytes)
* Files loaded count
* Contextual information

The output for action tracing can include trace records showing:

* Count of action hooks and filters
* Invocation of the 'wp' actions
* Contents of the global wp_rewrite for the 'wp' action
* Summary reports at 'shutdown'
* Information about deprecated logic
* Information related to Errors, Warnings and Notices

New in v2.0.6

* Parameters passed to user selected hooks
* Returned values from user selected filters
* Current status of the global post object for user selected hooks
* Information about attached hook functions for user selected hooks

If you select "Trace 'shutdown' status report and log in summary file"
then you also get a daily summary log, named bwtrace.vt.mmdd

The summary daily log contains information that can be used for performance analysis.
This log is produced even when tracing is not enabled.


See also:

* [bw_trace2()](http://www.oik-plugins.com/oik_api/bw_trace2)
* [bw_backtrace()](http://www.oik-plugins.com/oik_api/bw_backtrace)
* [bw_trace()](http://www.oik-plugins.com/oik_api/bw_trace)


## Installation 
1. Upload the contents of the oik-bwtrace plugin to the `/wp-content/plugins/oik-bwtrace' directory
1. Activate the oik-bwtrace plugin through the 'Plugins' menu in WordPress
1. Define your trace options using Settings > trace options
1. Define your action trace options using Settings > action options
1. Don't forget to disable tracing when you no longer need it

## Frequently Asked Questions 
# Where is the FAQ? 
[oik-bwtrace FAQ](http://www.oik-plugins.com/oik-plugins/oik-bwtrace-debug-trace-for-wordpress/?oik-tab=faq)

# Can I get support? 
Use the contact form on the oik-plugins website.

## Is there a tutorial? 
See this page and short video
[Introduction to oik-bwtrace](http://www.oik-plugins.com/wordpress-plugins-from-oik-plugins/free-oik-plugins/oik-trace-plugin/an-introduction-to-problem-determination-with-oik-bwtrace-debug-trace-for-wordpress)

## How do I trace from startup? 

If we want to include bw_trace(), bw_trace2() or bw_backtrace() calls in WordPress core
then we need to define the functions, so we include /libs/bwtrace.php.

If we want trace and action count to be enabled and reset at WordPress startup then we also need to define these as TRUE

Put the following in your wp-config.php file

`define( 'BW_TRACE_CONFIG_STARTUP', true );
define( 'BW_TRACE_ON', true );
define( 'BW_COUNT_ON', true );
define( 'BW_TRACE_RESET', true );

if ( file_exists( ABSPATH . '/wp-content/plugins/oik-bwtrace/lib/bwtrace.php' ) ) {
  require_once( ABSPATH . '/wp-content/plugins/oik-bwtrace/lib/bwtrace.php' );
}
`

Don't forget to remove or comment out this code when you no longer need it.


## Screenshots 
1. Trace options
2. Action options - part 1
3. Action options - part 2
4. Raw trace output
5. Daily summary log

## Upgrade Notice 
# 2.0.6 
Now supports user selected action hook tracing

* "Other hooks to trace",
* "Filter results to trace"
* "Trace the global post object"
* "Trace attached hook functions"

Added BW_TRACE_VERBOSE ( 64 ); an even higher level than BW_TRACE_DEBUG ( 32 ).

# 2.0.5 
Now supports multiple trace levels.

# 2.0.4 
Upgrade to use 'Error, Warning and Notice' detection in output buffered situations.

# 2.0.3 
Upgrade for improved deprecated logic support and information related to Error, Warning and Notice type messages

# 2.0.2 
Use to find the cause of those pesky "Deprecated constructor" messages

# 2.0.1 
Improved response to "oik_query_libs"

# 2.0.0 
Now works as a standalone plugin. Prior to upgrading oik-bwtrace please deactivate it and upgrade the oik base plugin to 2.6-alpha.0724 or higher.

# 1.28 
Now operates as a standalone plugin

# 1.27 
Current filter reporting and other minor improvements

# 1.26 
Improved logic for self implementation as an MU plugin

# 1.25 
Improved support for action hooks and filters.
Now implements itself as a Must Use (MU) plugin if action counting is selected.
Also contains logic that can be activated in db.php.

# 1.24 
Upgrade to get remote IP address in the summary log

# 1.23 
Fixes warning message when tracing not active but action count tracing is.

# 1.22 
Now outputs a single summary record for each transaction. Required for oik-plugins.com analysis

# 1.21 
Now outputs summary information in comments to the page, except during AJAX processing

# 1.20 
Contains a couple of minor improvements for better analysis of page loading

# 1.19.0307 
This version is tested with WordPress 3.6-alpha-23627

# 1.18.1219 
This version is a standalone version from www.oik-plugins.com

# 1.18.1218 
This version is a standalone version from www.oik-plugins.com

# 1.18 
This version is a standalone version from www.oik-plugins.com
This version matches the child plugin oik-bwtrace in oik v1.17

## Changelog 
# 2.0.6 
* Added: Ad-hoc tracing of filter functions for selected hooks ( Issue #3 )
* Added: Ad-hoc tracing of parameters to selected hooks ( Issue #2 )
* Added: Ad-hoc tracing of the global post object on selected hooks ( Issue #2 )
* Added: BW_TRACE_VERBOSE ( 64 ) level, which is even more detailed than BW_TRACE_DEBUG ( 32 )
* Changed: Enhanced output from Count action hooks and filters ( Issue #7 )
* Changed: Functions traced should allow OO methods invoking trace ( Issue #8 )
* Fixed: Ensure BW_TRACE_level constants are defined ( Issue #4 )
* Fixed: Fix for problem with symlinked file's drive letters ( similar to TRAC #33265 )
* Fixed: Only trace $errcontext when tracing with BW_TRACE_VERBOSE ( Issue #5 )
* Fixed: Strings containing commas in the trace summary file should be wrapped in quotes ( Issue #9 )

# 2.0.5 
* Added: $level parameter (default BW_TRACE_ALWAYS) to the bw_trace2() and bw_backtrace() APIs
* Added: Select box to choose the level of tracing
* Changed: Some bw_trace2() and bw_backtrace() calls to make use of the level capability
* Fixed: Problem when BW_COUNT_ON defined in wp-config.php

# 2.0.4 
* Changed: Now detects when output buffering is in place and uses an alternative function to print_r()

# 2.0.3 
* Added: bw_trace_error_handler() logic for Error, Warning and Notice type messages
* Added: Add logic for each deprecated action or filter
* Changed: Anonymize path in output from bw_trace_included_files()
* Changed: Updated bw_trace_count_report()

# 2.0.2 
* Changed: Now supports deprecated filters and actions
* Changed: Enabled using "Trace deprecated messages" checkbox

# 2.0.1 
* Changed: libs/bwtrace.php now at 2.0.1
* Changed: libs/oik-lib.php now at 0.0.2
* Changed: libs/oik_boot.php now at 3.0.0
* Changed: libs/bobbfunc.php now at 3.0.0
* Changed: libs/oik-admin.php now at 3.0.0 and uses _bw_c() instead of c()
* Changed: Uses "wp_loaded" to test for shared libraries for admin logic
* Changed: Implements "oik_query_libs" with priority 12, was 10

# 2.0.0 
* Changed: Summary trace record doesn't show trace file name if 0 trace records produced
* Changed: Merged shared libraries with oik-libs v0.0.1
* Changed: Reversioned using semantic versioning, to reflect incompatibility with oik v2.5
* Changed: Must Use plugin also version 2.0.0
* Changed: Some docblock comment updates
* Deleted: Some commented out code removed

# 1.28 
* Added: Shared library files in /libs folder to enable standalone operation
* Added: includes/bwtrace_actions.php to register trace action processing
* Added: option to control inclusion of the current filter ( cf=aaa ) in trace records
* Added: option to control the files loaded count ( F=nnn ) in trace records
* Changed: Admin pages no longer display "oik documentation" or "support oik" boxes
* Changed: Sequence of input fields in the oik trace options page
* Changed: Some functions deleted from libs/bobbfunc.php
* Changed: Some functions renamed in libs/bobbfunc.php
* Changed: Trace options and action options admin pages are only available when "oik-admin" library is available
* Changed: Uses bw_trace_anonymize_symlinked_file() to cater for symlinked files
* Changed: admin/oik-bwaction.inc is now redundant; but not yet deleted.
* Changed: oik_trace_reset_notes() checks for "oik-sc-help" library.
* Deleted: oik_action_summary()
* Fixed: br() does not attempt to translate null text
* Tested: With WordPress and WPMS 4.2 and above.
* Tested: With and without: oik-lib v0.1 and oik v2.6

# 1.27 
* Changed: current filter now shows the full tree. No longer necessary to trace the array separately
* Fixed: Trace function count no longer doubly incremented.
* Added: Option to report the $bw_trace_functions array at shutdown. bw_trace_functions_traced()
* Changed: Sequence of action hooks invoked for 'shutdown': included files, saved queries, output buffer, functions traced, status report
* Changed: Improved more docblock comments and some programming style

# 1.26 
* Changed: Improved activating/de-activating of the oik-bwtrace MU plugin when BW_COUNT_ON is not defined true
* Deprecated: Moved more deprecated functions and logic related to the original action tracing and logging to includes/deprecated.php
* Changed: bw_lazy_trace_config_startup() no longer references BW_ACTIONS_ON nor BW_ACTIONS_RESET; deprecated constants
* Changed: bw_trace_plugin_startup() loads global $bw_action_options regardless of the $bw_trace_options settings.
* Changed: bw_trace_count_plugins_loaded() now uses global $bw_action_options
* Changed: bw_trace_output_buffer() checks the output buffer status

# 1.25 
* Added: includes/deprecated.php for deprecated functions, excluding original immediate action tracing
* Changed: Dependent upon oik v2.6-alpha.0525 for .php versions of include files
* Changed: Deprecated some .inc files in favour of .php files.
* Changed: Moved bw_this_plugin_first() to admin/oik-bwtrace.inc
* Changed: Relabelled 'Count immediate actions' to 'Count action hooks and filters'
* Changed: Added options for specific action tracing functionality that was previously hardcoded
* Changed: bw_summarise_actions() - deprecated; no longer called by bw_action_summary()
* Changed: oik action options page rewrite;
* Changed: removed the slow action trace logic.
* Disabled: Disabled immediate action tracing... the last WordPress version for which this logic was supported was 3.6
* Changed: Improved some docblock comments
* Added: includes/_oik-bwtrace-mu.php - implements the MU version of the plugin
* Changed: Moved bw_lazy_trace_config_startup() to includes/bwtrace-config.php
* Changed: bw_lazy_trace_config_startup() now supports BW_COUNT_ON constant. When true it loads the action hook and filter counting logic and 'activates' the MU version of the plugin
* Changed: oik-bwtrace.php now uses oik_bwtrace_loaded() to perform startup processing

# 1.24 
* Added: records the trace file name in the summary log file
* Added: remote IP address included in the summary log file
* Fixed: Doesn't write HTML comments for JSON or XMLRPC requests
* Fixed: Doesn't write HTML comments for SiteGround cache check: sgCacheCheck
* Changed: Commented out tracing of global wp_rewrite

# 1.23 
* Fixed: Warning $wpdb->elapsed_query_time property missing
* Changed: Documented the fields in the bwtrace.vt.mmdd log file; where vt is simply an abbreviation of value and text

# 1.22 
* Added: Automatically sets SAVEQUERIES if recording the total number of queries performed
* Changed: bw_trace_saved_queries() formats the output in the trace log
* Changed: bw_trace_included_files() formats the output in the trace log
* Fixed: bw_trace_c3() now detects "short" parameter - set for async-upload of a new file
* Added: bwtrace.vt file stores summary of all activity
* Added: trace action counting - with "Count immediate actions" checkbox
* Added: Responds to "plugins_loaded" to start trace count logic
* Added: bw_trace_wp()
* Added: bw_trace_add_shutdown_actions() to defer adding actions responding to "shutdown"

# 1.21 
* Added: Logic originally developed for oik-shortcodes to display summary information at shutdown
* Added: Logic to trace included files: at startup and shutdown
* Added: Logic to trace saved queries: at startup and shutdown
* Added: Trace elapsed time - displayed after current timestamp
* Added: Trace number of included files as F=nnnn
* Changed: bw_lazy_backtrace() handles args which are arrays

# 1.20 
* Fixed: oik action tracing is not invoked if oik action settings have not been defined
* Added: Lists loaded files during shutdown processing
* Changed: trace IP is trimmed on input validation
* Added: Support for action trace output to be written in CSV format
* Added: bw_trace_bwechos()
* Added: tracing will attempt to use obsafe_print_r() instead of print_r()
* Changed: Minor improvement in determining the calling function
* Added: bw_trace_hook_all() for performing immediate action tracing. Makes original solution partially redundant.
* Changed: bw_action_file() - minor performance improvements
* Changed: bw_lazy_trace_action_immediate() also logs $arg3

# 1.19.0307
* Added official support for WordPress 3.5.1
* Added support for  WordPress 3.6-alpha-23627  - there have been some minor comment changes in plugin.php

# 1.18.1219 
* Added support for WordPress 3.5.1-alpha (as of 2012/12/19)

# 1.18.1218.2100
* Fixed: New optional values no longer included in the action log

# 1.18.1218 
* Added: Immediate action tracing helps you discover ALL the actions and filters
* Added: Immediate action tracing automatically replaces wp-includes/plugin.php
* Added: Trace record may includes current and peak memory usage (in bytes)
* Added: Inclusion of post ID and number of queries now optional

# 1.18 
* Added: Code to relocate from part of oik to a separate plugin
* Added: Updates are provided from oik-plugins

# up to 1.16 
* Please see the change log in oik for versions prior to 1.17

## Further reading 
If you want to read more about the oik plugins then please visit the
[oik plugin](http://www.oik-plugins.com/oik)
**"the oik plugin - for often included key-information"**