TraceActor provides a stream of call/return packets to a client collecting a full trace. One TraceActor is provided per browser tab.
States for TraceActor:
- detached: No client attached
- idle: A client is attached, but no traces are being collected
- tracing: A client is attached, and at least one trace is being collected.
Debugger API listeners for frame entry and exit are attached when transitioning from idle to tracing and removed when transitioning from tracing to idle.
Indicates state transition from detached to idle.
{
to: TraceActorID,
type: "attach"
}
The traceTypes property is a list of available information types
that may be collected on frame entry and/or frame exit.
{
from: TraceActorID,
type: "attached",
traceTypes: [
"name",
"callsite",
"time",
"parameterNames",
"arguments",
"return",
"throw",
"yield",
...
]
}
Sent if not in the detached state.
{
from: TraceActorID,
error: "wrongState"
}
Indicates state transition from idle to detached. If a
detach request is received while in the tracing state,
TraceActor should stop all traces in progress before
detaching.
{
to: TraceActorID,
type: "detach"
}
{
from: TraceActorID,
type: "detached"
}
Sent if in the detached state.
{
from: TraceActorID,
error: "wrongState"
}
If TraceActor is in the idle state, startTrace causes a state
transition to the tracing state. If TraceActor is in the
tracing state, startTrace starts an additional trace.
The trace property indicates what types of traces are to be
collected. Available trace types are sent with the onAttach
response. The trace types that will be collected by the trace actor
(and sent in enteredFrame and exitedFrame packets) will be the
union of the types that were requested for all active traces.
The name property is optional, and if it is not provided, a
generated name will be used (e.g. Trace 1). If a trace with the
given name is already being collected, the client is expected to
discard the trace in progress and replace it with a new trace.
{
to: TraceActorID,
type: "startTrace",
trace: [
"name",
"callsite",
"time",
"parameterNames",
"arguments",
"return",
"throw",
"yield",
...
]
name: String // Optional
}
{
from: TraceActorID,
type: "startedTrace",
why: "requested",
name: String
}
Sent if in the detached state.
{
from: TraceActorID,
error: "wrongState"
}
Sent if any trace type in the trace property of a startTrace
request is unrecognized by the actor.
{
from: TraceActorID,
error: "noSuchTraceType"
}
If TraceActor is in the tracing state and has only one active
trace, a successful stopTrace call causes a state transition to the
idle state.
The name property is optional, and if it is not provided, the most
recently started trace will be stopped.
{
to: TraceActorID,
type: "stopTrace"
name: String // Optional
}
{
from: TraceActorID,
type: "stoppedTrace",
why: "requested",
name: String
}
Sent if not in the tracing state.
{
from: TraceActorID,
error: "wrongState"
}
Sent if no active trace with the given name exists.
{
from: TraceActorID,
error: "noSuchTrace"
}
Sent as a notification after a call to console.startTrace(). If no
name was provided as an argument to startTrace(), a generated name
will be used (e.g. Trace 1). The tracing property indicates what
trace types are to be collected for the trace (the console API may
provide some way of specifying which trace types to collect).
{
from: TraceActorID,
type: "startedTrace",
tracing: [
"name",
"callsite",
"time",
"parameterNames",
"arguments",
"return",
"throw",
"yield",
...
]
why: "console.startTrace",
name: String
}
Sent as a notification after a call to console.stopTrace().
{
from: TraceActorID,
type: "stoppedTrace",
why: "console.stopTrace",
name: String
}
Can also be sent if a detach request is received while in the
tracing state:
{
from: TraceActorID,
type: "stoppedTrace",
why: "detached",
name: String
}
Sent as a notification when TraceActor is in the tracing state and a stack frame is entered.
When entering a frame, TraceActor sends only one enteredFrame
packet, regardless of the number of traces currently being collected
(likewise when exiting a frame). It is the client's responsibility to
update all active traces with the information in the packet.
{
from: TraceActorID,
type: "enteredFrame",
sequence: Integer,
name: FunctionName,
callsite: SourceLocation,
time: msSinceTraceStarted,
parameterNames: ParameterNames,
arguments: {
values: [ValueGrip],
objectPool: [ObjectDescriptor]
}
}
The sequence property is a sequence number. The sequence number is
set to 0 when TraceActor transitions from the idle state to the
tracing state, and is incremented with every enteredFrame and
exitedFrame packet. If packets are received out of order, it is the
client's responsibility to queue unexpected packets and wait for the
next packet in the sequence.
The name, callsite, time, parameterNames, and arguments
properties are optional, and their presence is determined by the
trace property sent in the startTrace request.
The callsite property is a source location, as defined here:
https://wiki.mozilla.org/Remote_Debugging_Protocol#Source_Locations
For most functions, the parameterNames property is an array of
strings. If the function uses destructuring parameters, then the
array's elements reflect the structure of the parameters. See
https://wiki.mozilla.org/Debugger#Debugger.Object for details.
The arguments property consists of the actual argument values (in
values) and an array of object descriptors (in objectPool). A
value grip (used in values and in object descriptors) is either a
primitive value, a grip representing null or undefined, or an
object grip. Unlike grips sent by object actors, serialized object
grips contain only the index of the object's descriptor in the
objectPool.
values: [
true,
1,
"string",
{ type: "null" },
{ type: "undefined" },
{ type: "object", objectId: PoolIndex }
]
The objectPool is an array of object descriptors, which are similar
to the response an object actor sends in reply to a
prototypeAndProperties request. Unlike the object actor response,
the class, extensible, frozen, and sealed properties are
included in the object descriptor rather than the object grip.
objectPool: [
{
class: "Object",
extensible: true,
frozen: false,
sealed: false,
prototype: { type: "object", objectId: PoolIndex },
ownProperties: {
someProperty: {
enumerable: true,
configurable: true,
value: { type: "object", objectId: PoolIndex }
},
...
}
safeGetterValues: {}
},
...
]
Sent as a notification when TraceActor is in the tracing state and a stack frame is exited.
The time, return, throw, and yield properties are optional,
and their presence is determined by the trace property sent in the
startTrace request.
{
from: TraceActorID,
type: "exitedFrame",
sequence: Integer,
why: "return",
time: msSinceTraceStarted,
return: {
value: ValueGrip,
objectPool: [ObjectDescriptor]
}
}
If the frame was exited due to an exception or a generator yield, the
return property may be replaced with throw or yield, containing
the thrown exception or yielded value respectively. If the code was
terminated, as if by the "slow script" dialog box, no completion value
property will be present.
throw: {
value: ValueGrip,
objectPool: [ObjectDescriptor]
}
yield: {
value: ValueGrip,
objectPool: [ObjectDescriptor]
}
The why property indicates how the frame exited, containing
"return", "exception", "yield", or "terminated".