« Back to Product

Documentation

Send feedback!

IPS_GetTraces

 array IPS_GetTraces (int $ObjectID)

Parameters

ObjectID

ID of the object whose traces are to be returned

Returns

An array of trace entries. The order of the entries is not guaranteed. 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

Warning

This function is intended for internal use only and may change or be removed at any time without notice.

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 all kept entries of the object ObjectID together with all entries of their cause chains (parents, grandparents, … up to the start of the chain). Entries that occur in several chains are only contained once. The result is a flat list; the tree structure can be rebuilt using TraceID, ParentID and ChildIDs. The result therefore corresponds to IPS_GetTraceList for every ID from IPS_GetTraceIDList. For an object without traces an empty array is returned. If 1 is passed as ObjectID, the chains of all kept entries are returned.

Warning

The function is intended to be called through the JSON-RPC interface, e.g. for the display in the console. It is not available in PHP scripts ("This function is not available for PHP") – there the result can be determined with IPS_GetTraceIDList and IPS_GetTraceList.

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 "...".

Warning

If a chain is deeper than 100 entries, the kernel assumes an endless loop (e.g. an event that writes its own trigger variable) and aborts the operation with "Insight trace depth exceeded 100. Assuming an endless loop. Aborting. Reverse Chain: …".

Example

$rpc = new JSONRPC("http://user:password@127.0.0.1:3777/api/");
print_r($rpc->IPS_GetTraces(10018));

/* 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
        )
    [1] => Array
        (
            [ChildIDs] => Array
            (
            )
            [Data] => Array
            (
                [OldValue] => 5
                [Value] => 7
                [VariableID] => 10018
            )
            [Depth] => 1
            [ExecutionUser] => @admin
            [ObjectID] => 10018
            [ParentID] => 0
            [Sender] => Variable
            [TimeStamp] => 1700000000
            [TraceID] => 2
        )
)
*/
Any questions?