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)