Recording Traces

351 June 21, 2021

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)