Recording Traces

Once initialized, the DecaLog SDK is ready to record traces.
To add your own spans to the main trace, start by asking the Engine to return a traces logger for your already registered slug and use it to start and stop spans:

<?php $traces = \DecaLog\Engine::tracesLogger( 'my-plugin-slug' ); // Starting main process $root = $traces->startSpan( 'My Main Span' ); // Starting sub-process $span = $traces->startSpan( 'My Sub Span', $root ); // ... sub-do something $traces->endSpan( $span ); // ... do something $traces->endSpan( $root );
Code language: PHP (php)

As you can see, you can specify the parent span as the second argument of start_span() method to nest spans. There’s no limit to the nesting levels (well, there’s always a limit, but it is common practice to have as many levels as needed to offer a full understanding of what’s happening). Inversely, you can avoid using this nesting feature and produce a flat spans tree if it’s relevant to what you’re doing.

If you want to “attach” your root spans to the parent WordPress span, you can use the following predefined constants:

  • DECALOG_SPAN_MUPLUGINS_LOAD: WordPress MU plugins loading sequence.
  • DECALOG_SPAN_PLUGINS_LOAD: WordPress plugins loading sequence.
  • DECALOG_SPAN_THEME_SETUP: WordPress theme setting-up sequence.
  • DECALOG_SPAN_USER_AUTHENTICATION: WordPress user authenticating sequence.
  • DECALOG_SPAN_PLUGINS_INITIALIZATION: WordPress plugins initialization sequence.
  • DECALOG_SPAN_MAIN_RUN: main WordPress process.
  • DECALOG_SPAN_SHUTDOWN: WordPress shutdown sequence.

For example, to start a new span having the WordPress plugins load process as parent, you must do:

<?php $traces = \DecaLog\Engine::tracesLogger( 'my-plugin-slug' ); // Starting main process, having WordPress plugins load as parent $root = $traces->startSpan( 'My Main Span', DECALOG_SPAN_PLUGINS_LOAD ); // ... do something $traces->endSpan( $root );
Code language: PHP (php)

Limitations

Any span started after the DECALOG_MAX_SHUTDOWN_PRIORITY in the WordPress shutdown hook will be dropped by DecaLog.

<?php // 'My Span' will be recorded: add_action( 'shutdown', function() { \DecaLog\Engine::tracesLogger( 'my-plugin-slug' )->startSpan( 'My Span', DECALOG_SPAN_SHUTDOWN ); }, DECALOG_MAX_SHUTDOWN_PRIORITY, 0 ); // 'My Span' will not be recorded: add_action( 'shutdown', function() { \DecaLog\Engine::tracesLogger( 'my-plugin-slug' )->startSpan( 'My Span', DECALOG_SPAN_SHUTDOWN ); }, DECALOG_MAX_SHUTDOWN_PRIORITY + 1, 0 );
Code language: PHP (php)