Class: TraceRecorder

lib/core/trace/recorder.TraceRecorder(optionsopt)

Records one session's causal trace.

Constructor

new TraceRecorder(optionsopt)

Parameters:
Name Type Attributes Description
options object <optional>

Recorder options.

Properties
Name Type Attributes Description
id string <optional>

An explicit trace id. Generated when omitted.
maxNodes number <optional>

Ring-buffer capacity.
redact Array:.<string:> <optional>

Redaction patterns.
meta object <optional>

Free-form metadata about the session.
Source:

Members

componentCount

How many distinct components appear in the trace.

Source:

createdAt :string

Type:
  • string
Source:

determinism :string

Type:
  • string
Source:

dropped :number

Type:
  • number
Source:

globals :Object

Non-deterministic global values in the order application code observed them, so replay can hand back the same sequence.

Type:
  • Object
Source:

id :string

Type:
  • string
Source:

index :Map:.<number:, object:>

Open nodes by id, so TraceRecorder#annotate can find a node the buffer may since have dropped.

Type:
  • Map:.<number:, object:>
Source:

isDeterministic

Whether this recording is currently believed to be replayable.

"Believed" is doing real work in that sentence: this reflects only the escapes the runtime could observe. Replay verifies the claim independently by comparing what it observes against what was recorded.

Source:

maxNodes :number

Type:
  • number
Source:

meta :object

Type:
  • object
Source:

nextId :number

Type:
  • number
Source:

nodes :Array:.<object:>

The ring buffer. Kept as a plain array that is spliced in one block when it overflows, rather than a circular index: traces are read far more often than they overflow, and a linear array keeps every reader simple.

Type:
  • Array:.<object:>
Source:

phase :string

Type:
  • string
Source:

reasons :Map:.<string:, string:>

Type:
  • Map:.<string:, string:>
Source:

redactor :Redactor

Type:
  • Redactor
Source:

seq :number

Type:
  • number
Source:

startedAt :number

Type:
  • number
Source:

Methods

annotate(id, fields)

Merges fields into a node that is still in the buffer.

Parameters:
Name Type Description
id number

The node id.
fields object

Fields to merge.
Source:

arm() → {TraceRecorder}

Switches from application startup to recording user interaction.

Until this is called, state writes with no recorded cause are treated as the application initialising itself rather than as non-determinism.

Source:
Returns:

This recorder.

Type
TraceRecorder

capture(value, pathopt) → {any}

Captures a value under this recorder's redaction and bounds.

Parameters:
Name Type Attributes Description
value any

The value.
path string <optional>

The property path, for redaction matching.
Source:
Returns:

A JSON-representable capture.

Type
any

markNonDeterministic(reason, detailopt)

Downgrades the trace to best-effort.

Reasons are de-duplicated by kind: a session that made a thousand unattributed writes should say so once, with an example.

Parameters:
Name Type Attributes Description
reason string

A NonDeterminismReason.
detail string <optional>

Context for the developer.
Source:

push(type, data, parent) → {object}

Appends a node.

Parameters:
Name Type Description
type string

A TraceNodeType.
data object

Type-specific fields.
parent number | null

The causal parent id.
Source:
Returns:

The stored node.

Type
object

recordGlobal(kind, value) → {number}

Records a non-deterministic global value the sandbox handed to application code, so replay can hand back the same one.

Parameters:
Name Type Description
kind 'now' | 'random'

Which source produced it.
value number

The value.
Source:
Returns:

The same value, so callers can record inline.

Type
number

serialize(indentopt) → {string}

Serializes the trace to a JSON string.

Parameters:
Name Type Attributes Default Description
indent number <optional>
 0

Indentation passed to JSON.stringify.
Source:
Returns:
Type
string

stop() → {TraceRecorder}

Ends the recording.

Source:
Returns:

This recorder.

Type
TraceRecorder

toJSON() → {object}

Produces the serializable trace.

Source:
Returns:

A trace matching TRACE_VERSION.

Type
object