Documentation forSolarWinds Observability SaaS

PHP Library instrumentation SDK

The SolarWinds Observability PHP SDK enables custom tracing and metrics reporting. Customization involves adding hooks from our public SDK to your code so that you can take advantage of additional filtering capabilities on the dashboard, change how requests are traced, or capture additional information during the trace.

Get started

The instrumentation customization SDK relies on methods defined in the library. To make your code safe to run in all environments, include the api.php stub file in your code. The api.php stub file provides empty SDK definitions to prevent crashes if your library is uninstalled and the application still has calls to the SDK.

PHP custom spans

By default, the PHP instrumentation creates a php span, and then creates a span for each non-PHP service that it is instrumenting. For example, php_mysql, memcache, phpredis, and curl. If these spans do not provide enough visibility into your application, you can further divide your code into sub-spans.

You can segment your application however you want. For example, the default instrumentation might not recognize calls to external processes; or, maybe there's a discrete subsection of your code that is worth calling out on its own. In either situation, to start a span, call solarwinds_apm_log_entry(). To end the span, call solarwinds_apm_log_exit(). See PHP SDK reference.

solarwinds_apm_log_entry('sayhello');
...
solarwinds_apm_log_exit('sayhello');

Add info events

There are two reasons you might want to create an info event: to attach any meta-data that may be of interest to you during later analysis of a trace. You can classify spans by attaching a pre-defined set of specified key-value pairs as a third parameter. In the Traces Explorer, you can filter for traces with that span type.

To add info to an span, call solarwinds_apm_log anywhere within the span, as shown. If necessary, you can add info to an span at multiple locations. The information events are displayed on the raw span data tab in the Traces Explorer. If all of the key-value pairs for special interpretation are present, the span type is reflected in the span details tab. Follow the link to the SDK documentation for complete syntax and usage information.

solarwinds_apm_log('span-name', 'info', array('key' => $variable));

Set custom transaction name

PHP instrumentation supports these frameworks. If we don’t support your framework, set a custom transaction name for the traced request. Be aware of these restrictions:

  • a transaction name can only be set on active traces (e.g. between solarwinds_apm_start_trace() and solarwinds_apm_end_trace())
  • if set outside an active trace, the call will be ignored
  • if multiple calls are made, only the last call is used
  • empty transaction names will be ignored
  • the final transaction name is converted to lowercase and might be truncated, with invalid characters replaced
solarwinds_apm_set_transaction_name('my-controller/my-action');

Starting a trace

Traces are typically started automatically when a request is made. In certain cases you may want to start a trace manually, for example if you are only interested in tracing a specific area of your code. To start a trace manually, disable auto-instrumentation by setting solarwinds-apm.use_custom_start_trace = 1. Then surround the code you want traced with a call to solarwinds_apm_start_trace() and a call to solarwinds_apm_end_trace().

solarwinds_apm_start_trace('my-name');
// your code
solarwinds_apm_end_trace()

Enabling CLI tracing

By default, Command Line Interface (CLI) tracing is disabled. Set solarwinds-apm.enable_cli = 1 to enable CLI tracing.

Check if library is ready

The library initializes and maintains a connection to the SolarWinds APM collector, and receives settings used for making tracing decisions. Depending on the connection, this process can take a few seconds. If the application receives requests before initialization has completed, these requests will not be traced. While tracing every request is not critical for long-running server processes such as Apache, it could cause issues for short-running apps such as cron jobs or CLI apps. Using this method allows the app to block until initialization has completed and the library is ready for tracing. This method takes an optional timeout value in milliseconds, which tells the library how long to wait to get ready. The default timeout is 0 milliseconds, which results in no blocking. The return value indicates whether the library is ready to receive traces (true) or not (false).

solarwinds_apm_is_ready(1000);

Report errors and exceptions

Errors automatically generate error events in a trace if the solarwinds-apm.enable_error_callback INI setting is not set to zero. When enabled with a non-zero value, the default error handling is further configured by the solarwinds-apm.report_suppressed_errors and solarwinds-apm.use_error_reporting INI settings. Typically, the default SolarWinds Observability error callback handler is only disabled when using a separate error handler.

To manually record an error in a trace, call solarwinds_apm_log_error(). An example showing how to call solarwinds_apm_log_error() with PHP log level E_NOTICE is:

solarwinds_apm_log_error('span-name', 'something is wrong', E_NOTICE);

See Predefined Constants in the PHP Manual for valid error codes. See PHP SDK reference.

Like errors, exceptions are automatically recorded in a trace if the solarwinds-apm.enable_error_callback INI setting is set to any value other than zero. However, if it is set to zero, you'll need to create an exception error event manually, using a call to solarwinds_apm_log_exception() (see PHP SDK reference). In this case, the exception object is passed as a parameter instead of an error message, and additional key values are passed in a hashtable. Also, the stack trace from the exception object is explicitly passed so that the library reports it as the error backtrace instead of as the default stack trace taken from the exception handler.

solarwinds_apm_log_exception('myexcept', $e, array('test' => 'tripleInteger($int)', 'result' => 'InvalidArgumentException generated'), $e->getTrace());

Add PHP data objects instrumentation

Use PHP data objects (PDO) instrumentation to collect performance data relating to query and database usage in PHP applications.

  1. To explicitly enable the PDO instrumentation, either add the following line to your php.ini settings or to the INI settings in solarwinds-apm.ini (located in /etc/php5/conf.d/ for Debian/Ubuntu applications and in /etc/php.d/ for RHEL/CentOS applications.

    solarwinds-apm.enable_wrap_pdo = 1
  2. To verify that the INI value has been successfully set, run php -i or call phpinfo().

PHP SDK reference

<?php
/**
 * SolarWinds APM SDK API for PHP
 *
 * This can be used for autocompletion in many major PHP editors
 * provides documentation for the code
 * and can be used on systems where the solarwinds-apm extension is not loaded
 * to provide no-op versions of functionality
 */

if(!extension_loaded('solarwinds-apm') && !function_exists('solarwinds_apm_set_context')) {

    /**
     * Get array of string representation of current global context (W3C traceparent and tracestate) being used
     * e.g. [traceparent, tracestate]
     * if request is not tracing, will return false
     *
     * @return array|false
     */
    function solarwinds_apm_get_context() {
        return false;
    }

    /**
     * Set a string value for the current global context (W3C traceparent and tracestate) being used
     * will not start a trace, but will set the context to use for tracing even
     * if not currently tracing
     *
     * @return bool true for valid set, false for invalid traceparent or tracestate sent
     */
    function solarwinds_apm_set_context($traceparent, $tracestate) {
        return true;
    }

    /**
     * Check if SolarWinds APM is ready for receiving traces and optionally wait for a given
     * time. 'Ready' here means SolarWinds APM has connected to the collector and has
     * successfully received settings.
     * Note: The ini config option 'solarwinds-apm.max_ready_wait_time' can set this on the
     * global application level.
     *
     * @param int timeout (optional) to wait for becoming ready (in milli seconds).
     *            A value of 0 will turn off waiting for timeout.
     *
     * @return bool true if ready, false otherwise
     */
    function solarwinds_apm_is_ready($timeout = 0) {
        return true;
    }

    /**
     * Attempts to start a new trace
     * Uses solarwinds-apm and feeds in optional incoming W3C traceparent
     * header, and PHP set sample mode or sample rate if applicable
     *
     * If it returns false then tracing is not started
     *
     * if context is set before a trace is started the context provided will be used
     * otherwise a new random context is generated
     *
     * Will throw a PHP Notice if start trace has already been called or autotracing is on
     *
     * @param string layer name for custom tracing
     * @param string traceparent (optional) incoming W3C traceparent (default = null)
     * @param string tracestate (optional) incoming W3C tracestate (default = null), see tracestate details in https://www.w3.org/TR/trace-context/#tracestate-header
     * @param mixed info (optional) if arrayaccess (array or object with hashtable) is sent then the items in the key
     *              value pairs that aren't reserved are sent with the beginning trace
         * @param mixed backtrace (optional) if arrayaccess (array or object with hashtable) that is used as a backtrace
     *               if true is passed PHP generated backtrace is sent, if false
     *               is passed then no backtrace is sent
     *
     * @return array('sample_rate' => value
     *               'sample_source' => value) or false
     */
    function solarwinds_apm_start_trace($layer, $traceparent = null, $tracestate = null, $info = null, $backtrace = true) {
        return false;
    }

    /**
     * Stops a trace
     *
     * If it returns false then tracing was never started or an error occurred
     *
     * @param mixed info (optional) if arrayaccess (array or object with hashtable) is sent then the items in the key
     *              value pairs that aren't reserved are sent with the beginning trace
         * @param mixed backtrace (optional) if arrayaccess (array or object with hashtable) that is used as a backtrace
     *               if true is passed PHP generated backtrace is sent, if false
     *               is passed then no backtrace is sent
     * @param mixed edge (optional) if arrayaccess (array or object with hashtable) is sent then the items are treated
     *              as additional edges to add, if it's a single string the string is added
     * @param string transaction_name (optional) the transaction name to be set for this trace
     *
     * @return boolean (true on success, false on failure)
     */
    function solarwinds_apm_end_trace($info = null, $backtrace = true, $edge = null, $transaction_name = null) {
        return false;
    }

    /**
     * Sets a custom transaction name
     * Can only be called on an active trace (e.g. between solarwinds_apm_start_trace() and solarwinds_apm_end_trace(),
     * or when autotracing is on)
     *
     * @param string transaction_name the transaction name to be set for this trace
     *
     * @return boolean (true on success, false on failure (e.g. empty $transaction_name passed in))
     */
    function solarwinds_apm_set_transaction_name($transaction_name) {
        return false;
    }

    /**
     * Is this request/script currently tracing
     *
     * @return boolean (true on success, false on failure)
     */
    function solarwinds_apm_is_tracing() {
        return false;
    }

    /**
     * Has tracing been started? either by normal means (when use_custom_start_trace is off) or a call to solarwinds_apm_start_trace
     *
     * @return boolean (true on success, false on failure)
     */
    function solarwinds_apm_trace_started() {
        return false;
    }

    /**
     * Creates an event
     *
     * @param string layer (optional) layer name to use (may be null)
     * @param string label label name to trace (entry, exit, info, etc)
     * @param mixed info (optional) if arrayaccess (array or object with hashtable) is sent then the items in the key
     *              value pairs that aren't reserved are sent with the beginning trace
         * @param mixed backtrace (optional) if arrayaccess (array or object with hashtable) that is used as a backtrace
     *               if true is passed PHP generated backtrace is sent, if false
     *               is passed then no backtrace is sent
     * @param mixed edge (optional) if arrayaccess (array or object with hashtable) is sent then the items are treated
     *              as additional edges to add, if it's a single string the string is added
     * @return boolean (true on success, false on failure)
     */
    function solarwinds_apm_log($layer, $label, $info = null, $backtrace = true, $edge = null) {
        return false;
    }

    /**
     * Creates a new entry event
     *
     * @param string layer layer name to use
     * @param mixed info (optional) if arrayaccess (array or object with hashtable) is sent then the items in the key
     *              value pairs that aren't reserved are sent with the beginning trace
     * @param mixed backtrace (optional) if arrayaccess (array or object with hashtable) that is used as a backtrace
     *               if true is passed PHP generated backtrace is sent, if false
     *               is passed then no backtrace is sent
     *
     * @return boolean (true on success, false on failure)
     */
    function solarwinds_apm_log_entry($layer, $info = null, $backtrace = true) {
        return false;
    }

    /**
     * Creates a new exit event
     *
     * @param string layer layer name to use
     * @param mixed info (optional) if arrayaccess (array or object with hashtable) is sent then the items in the key
     *              value pairs that aren't reserved are sent with the beginning trace
     * @param mixed backtrace (optional) if arrayaccess (array or object with hashtable) that is used as a backtrace
     *               if true is passed PHP generated backtrace is sent, if false
     *               is passed then no backtrace is sent
     * @param mixed edge (optional) if arrayaccess (array or object with hashtable) is sent then the items are treated
     *              as additional edges to add, if it's a single string the string is added
     * @return boolean (true on success, false on failure)
     */
    function solarwinds_apm_log_exit($layer, $info = null, $backtrace = true, $edge = null) {
        return false;
    }

    /**
     * Creates an error event
     *
     * @param string layer layer name to use
     * @param string message error message
     * @param int PHP error code
     * @param mixed info (optional) if arrayaccess (array or object with hashtable) is sent then the items in the key
     *              value pairs that aren't reserved are sent with the beginning trace
     * @param mixed backtrace (optional) if arrayaccess (array or object with hashtable) that is used as a backtrace
     * @param mixed edge (optional) if arrayaccess (array or object with hashtable) is sent then the items are treated
     *              as additional edges to add, if it's a single string the string is added
     * @return boolean (true on success, false on failure)
     */
    function solarwinds_apm_log_error($layer, $message, $code, $info = null, $backtrace = null, $edge = null) {
        return false;
    }

    /**
     * Creates an event from a PHP exception
     *
     * @param string layer layer name to use
     * @param object instanceof Exception exception
     * @param mixed info (optional) if arrayaccess (array or object with hashtable) is sent then the items in the key
     *              value pairs that aren't reserved are sent with the beginning trace
     * @param mixed backtrace (optional) if arrayaccess (array or object with hashtable) that is used as a backtrace
     * @param mixed edge (optional) if arrayaccess (array or object with hashtable) is sent then the items are treated
     *              as additional edges to add, if it's a single string the string is added
     * @return boolean (true on success, false on failure)
     */
    function solarwinds_apm_log_exception($layer, Exception $e, $info = null, $backtrace = null, $edge = null) {
        return false;
    }

    /**
     * Creates a new or adds to an existing Summary Metric
     *
     * @param string name the name of the metrics, a part of the "metric key"
     * @param float value a value to be recorded associated with this "metric key"
     * @param int count (optional) default as 1
     * @param boolean host_tag (optional) default as false, whether host information should be included
     * @param string service_name (optional) default as empty, custom service name
     * @param array tags (optional) default as empty, a part of the "metric key"
     *              (e.g. array("region"=>"us-west", "name"=>"web-prod-3", "db"=>"db-prod-1"))
     * @return boolean (true on success, false on failure)
     */
    function solarwinds_apm_metric_summary($name, $value, $count = 1, $host_tag = false, $service_name = null, $tags = null) {
        return false;
    }

    /**
     * Creates a new or adds to an existing Increment Metric
     *
     * @param string name the name of the metrics, a part of the "metric key"
     * @param int count (optional) default as 1
     * @param boolean host_tag (optional) default as false, whether host information should be included
     * @param string service_name (optional) default as empty, custom service name
     * @param array tags (optional) default as empty, a part of the "metric key"
     *              (e.g. array("region"=>"us-west", "name"=>"web-prod-3", "db"=>"db-prod-1"))
     * @return boolean (true on success, false on failure)
     */
    function solarwinds_apm_metric_increment($name, $count = 1, $host_tag = false, $service_name = null, $tags = null) {
        return false;
    }

    /**
     * Get the trace_id, span_id and trace_flags of the currently running request.
     * This info is also appended to log messages if the INI option 'solarwinds-apm.log_trace_id' is enabled.
     *
     * @return string trace_id, span_id and trace_flags
     */
    function solarwinds_apm_get_log_trace_id() {
        return "trace_id=00000000000000000000000000000000 span_id=0000000000000000 trace_flags=00";
    }
}

The scripts are not supported under any SolarWinds support program or service. The scripts are provided AS IS without warranty of any kind. SolarWinds further disclaims all warranties including, without limitation, any implied warranties of merchantability or of fitness for a particular purpose. The risk arising out of the use or performance of the scripts and documentation stays with you. In no event shall SolarWinds or anyone else involved in the creation, production, or delivery of the scripts be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use of or inability to use the scripts or documentation.