« Back to Product

Documentation

Send feedback!

IPS_GetTraceList

 array IPS_GetTraceList (int $TraceID)

Parameters

TraceID

ID of the trace entry

Returns

An array of trace entries, starting with the entry TraceID, followed by its parent entry and so on up to the start of the chain. Each entry contains the following information as key => value pairs:

Index Type Description
TraceID integer Unique, ascending ID of the entry
ParentID integer ID of the entry that caused this entry (0 = start of a chain)
ChildIDs array IDs of the entries caused by this entry
Depth integer Position in the chain, starting at 1 (0 = placeholder for an entry that is no longer available)
ObjectID integer ID of the object the entry belongs to (1 = no object, e.g. for WebServer)
Sender string Kind of entry (see sender table)
ExecutionUser string User on whose behalf it was executed (e.g. @admin; @unknown if no user was logged in)
TimeStamp integer Unix timestamp of the creation
Data array Additional information as key => value pairs, depending on the sender (see sender table)

Sender table

Sender Description ObjectID Data
Variable A value was written to a variable (even without a change) Variable VariableID, Value, OldValue
RequestAction The action of a variable was requested Variable VariableID, ActionID, Value, Sender
RequestAction The RequestAction function of an instance was called for a status variable Instance Ident, Value
TriggerEvent A triggered event runs its action Event EventID, ActionID, Environment, Trigger, VariableID, Value
CyclicEvent A cyclic event runs its action Event EventID, ActionID, Environment
Script A script is executed Script Sender, ScriptID, FilePath, SenderID
Event PHP code is executed on behalf of an event Event Sender, ScriptID, FilePath, SenderID
Instance PHP code is executed for a target object Target object Sender, ScriptID, FilePath, SenderID
Timer A timer of an instance is executed Instance TimerName, Instance, RunOnce
DataFlow An instance receives data through the data flow Receiving instance InstanceID, ParentID
WebServer A request to the WebServer (file/hook) or a JSON-RPC call 1 Path or Method, RemoteIP, ProxyIPs (only behind proxies)
System Placeholder for an entry that is no longer available 1 Reason

Description

In traces the kernel records what caused what: every entry represents one operation – e.g. writing a variable, the event triggered by it, its action or script, a RequestAction, a timer or a request to the WebServer – and refers to the entry that caused it via ParentID and to the entries it caused itself via ChildIDs. For every cause this results in a tree that shows, for example, why a variable has changed.

The function returns the entry TraceID and all entries that caused it: the first element is the entry itself, the last element is the start of the chain (ParentID 0). The entries caused by an entry are listed in ChildIDs and can also be retrieved with this function. The IDs of the entries of an object are returned by IPS_GetTraceIDList.

If an entry of the chain is no longer available, the list ends with a placeholder: Depth 0, Sender "System", ObjectID 1 and the reason in Data → Reason. If there is no entry with the ID TraceID, the function fails with "No trace with ID … found".

Traces are only kept in memory and are lost on a restart. The last 25 entries are kept per object, and the last 1000 entries in total for entries without an object (e.g. WebServer). An older entry is kept as long as a kept entry still descends from it, so chains stay complete. When an object is deleted, its entries are removed. Strings in Data are shortened to 100 bytes and marked with "...".

Example

print_r(IPS_GetTraceList(1));

/* e.g. returns:
Array
(
    [0] => Array
        (
            [ChildIDs] => Array
            (
            )
            [Data] => Array
            (
                [OldValue] => 0
                [Value] => 5
                [VariableID] => 10018
            )
            [Depth] => 1
            [ExecutionUser] => @admin
            [ObjectID] => 10018
            [ParentID] => 0
            [Sender] => Variable
            [TimeStamp] => 1700000000
            [TraceID] => 1
        )
)
*/

// Output the cause chain of the newest entry of a variable
$ids = IPS_GetTraceIDList(10018);
if (count($ids) > 0) {
    foreach (IPS_GetTraceList(end($ids)) as $entry) {
        echo $entry['Depth'] . ': ' . $entry['Sender'] . ' #' . $entry['ObjectID'] . PHP_EOL;
    }
}
Any questions?