Tracing

Inherits from Object

Sealed

Tracing — Actor observability, trace context, and performance telemetry.

Provides class methods for controlling trace capture, setting application-level trace context, querying aggregate stats, analyzing performance bottlenecks, and checking actor/VM health. All methods are class-side — Tracing has no instances.

Trace context (setContext:/context/clearContext) propagates automatically across actor boundaries, so workflow IDs and request metadata flow through actor call chains without manual threading.

Aggregate stats (call counts, durations) are always-on with negligible overhead (~150ns/call). Detailed trace events require explicit enable/disable.

Examples

// Set application-level trace context
Tracing setContext: #{#workflowId => "wf-123"}
// => nil
Tracing context
// => _

// Always-on aggregates — no setup needed
Tracing stats
// => _

// Enable trace capture for detailed events
Tracing enable
// => nil
Tracing isEnabled
// => true

// Query traces
Tracing traces
// => _

// Analysis
Tracing slowMethods: 5
// => _

// Clean up
Tracing clearContext
// => nil
Tracing disable
// => nil
Tracing clear
// => nil

Class Methods

setContext: ctx Sealed source

Set application-level trace context that propagates across actor calls. Merges with any existing context. Use for workflow correlation IDs, request IDs, or any application-level metadata you want in traces and logs.

Examples

Tracing setContext: #{#workflowId => "wf-123", #workflowType => "OrderWorkflow"}
// => nil

context Sealed source

Get the current application-level trace context. Returns an empty dictionary when no context has been set.

Examples

Tracing context
// => _

clearContext Sealed source

Clear the application-level trace context. Removes all trace context keys from the process and logger metadata.

Examples

Tracing clearContext
// => nil

enable Sealed source

Start capturing trace events (aggregates are always on).

Examples

Tracing enable
// => nil

disable Sealed source

Stop capturing trace events.

Examples

Tracing disable
// => nil

isEnabled Sealed source

Check whether trace capture is active.

Examples

Tracing isEnabled
// => _

clear Sealed source

Clear all trace events and aggregate stats.

Examples

Tracing clear
// => nil

traces Sealed source

All captured trace events (up to buffer limit), newest first. Returns [] when not enabled.

Examples

Tracing traces
// => _

tracesFor: actor Sealed source

Trace events for a specific actor.

Examples

// Tracing tracesFor: myCounter
// => _

tracesFor: actor selector: sel Sealed source

Trace events for a specific actor + method.

Examples

// Tracing tracesFor: myCounter selector: #increment
// => _

stats Sealed source

Per-actor, per-method aggregate stats (always available, even without tracing).

Examples

Tracing stats
// => _

statsFor: actor Sealed source

Aggregate stats for a specific actor. Returns #{} for unknown actors.

Examples

// Tracing statsFor: myCounter
// => _

slowMethods: limit Sealed source

Top N methods by average duration (descending).

Examples

Tracing slowMethods: 10
// => _

hotMethods: limit Sealed source

Top N methods by call count (descending).

Examples

Tracing hotMethods: 10
// => _

errorMethods: limit Sealed source

Top N methods by error + timeout rate (descending).

Examples

Tracing errorMethods: 5
// => _

bottlenecks: limit Sealed source

Top N actors by message queue length — live snapshot.

Examples

Tracing bottlenecks: 5
// => _

healthFor: actor Sealed source

Live process info: queue depth, memory, reductions, status. Returns status=dead for dead actors.

Examples

// Tracing healthFor: myCounter
// => _

systemHealth Sealed source

VM overview: scheduler count, memory breakdown, process count, run queue lengths.

Examples

Tracing systemHealth
// => _

maxEvents Sealed source

Current ring buffer capacity.

Examples

Tracing maxEvents
// => _

maxEvents: size Sealed source

Set ring buffer capacity.

Examples

Tracing maxEvents: 50000
// => nil

Inherited Methods

From Object

class

Return the class of the receiver.

Examples

42 class              // => Integer
"hello" class         // => String

isNil

Test if the receiver is nil. Returns false for all objects except nil.

Examples

42 isNil              // => false
nil isNil             // => true

notNil

Test if the receiver is not nil. Returns true for all objects except nil.

Examples

42 notNil             // => true
nil notNil            // => false

ifNil: _nilBlock

If the receiver is nil, evaluate nilBlock. Otherwise return self.

Examples

42 ifNil: [0]         // => 42
nil ifNil: [0]        // => 0

ifNotNil: notNilBlock

If the receiver is not nil, evaluate notNilBlock with self.

Examples

42 ifNotNil: [:v | v + 1]   // => 43
nil ifNotNil: [:v | v + 1]  // => nil

ifNil: _nilBlock ifNotNil: notNilBlock

If nil, evaluate nilBlock; otherwise evaluate notNilBlock with self.

Examples

42 ifNil: [0] ifNotNil: [:v | v + 1]    // => 43
nil ifNil: [0] ifNotNil: [:v | v + 1]   // => 0

ifNotNil: notNilBlock ifNil: _nilBlock

If not nil, evaluate notNilBlock with self; otherwise evaluate nilBlock.

Examples

42 ifNotNil: [:v | v + 1] ifNil: [0]    // => 43
nil ifNotNil: [:v | v + 1] ifNil: [0]   // => 0

printString

Return a developer-readable string representation.

Default implementation returns "a ClassName". Subclasses such as Integer, String, and List override this to return richer output.

Examples

42 printString            // => "42"

displayString

Return a user-facing string representation for display purposes.

Default implementation delegates to printString. Subclasses such as String and Symbol override this to return a more readable form without developer annotations (e.g. no surrounding quotes or # prefix).

Examples

42 displayString             // => "42"

inspect

Inspect the receiver.

Examples

42 inspect             // => "42"

yourself Sealed

Return the receiver itself. Useful for cascading side effects.

Examples

42 yourself            // => 42

hash

Return a hash value for the receiver.

Examples

42 hash

respondsTo: selector Sealed

Test if the receiver responds to the given selector.

Examples

42 respondsTo: #abs    // => true

fieldNames Sealed

Return the names of fields.

Examples

42 fieldNames             // => #()

fieldAt: name Sealed

Return the value of the named field.

Examples

object fieldAt: #name

fieldAt: name put: value Sealed

Set the value of the named field (returns new state).

Examples

object fieldAt: #name put: "Alice"

perform: selector Sealed

Send a unary message dynamically.

Examples

42 perform: #abs       // => 42

perform: selector withArguments: args Sealed

Send a message dynamically with arguments.

Examples

3 perform: #max: withArguments: #(5)   // => 5

subclassResponsibility

Raise an error indicating this method must be overridden by a subclass.

Examples

self subclassResponsibility

notImplemented

Raise an error indicating this method has not yet been implemented.

Use this for work-in-progress stubs. Distinct from subclassResponsibility, which signals an interface contract violation.

Examples

self notImplemented

show: aValue

Send aValue to the current transcript without a trailing newline.

Nil-safe: does nothing when no transcript is set (batch compile, tests).

Examples

42 show: "value: "

showCr: aValue

Send aValue to the current transcript followed by a newline.

Nil-safe: does nothing when no transcript is set (batch compile, tests).

Examples

42 showCr: "hello world"

isKindOf: aClass

Test if the receiver is an instance of aClass or any of its subclasses.

Examples

42 isKindOf: Integer    // => true
42 isKindOf: Object     // => true
#foo isKindOf: Symbol   // => true
#foo isKindOf: String   // => false

error: message

Raise an error with the given message.

Examples

self error: "something went wrong"

From ProtoObject

== other

Test value equality (Erlang ==).

Examples

42 == 42           // => true
"abc" == "abc"     // => true

/= other

Test value inequality (negation of ==).

Examples

1 /= 2             // => true
42 /= 42           // => false

class

Return the class of the receiver.

Examples

42 class            // => Integer
"hello" class       // => String

doesNotUnderstand: selector args: arguments

Handle messages the receiver does not understand. Override for custom dispatch.

Examples

42 unknownMessage   // => ERROR: does_not_understand

perform: selector withArguments: arguments

Send a message dynamically with an arguments list.

Examples

42 perform: #abs withArguments: #()   // => 42

performLocally: selector withArguments: arguments

Execute a class method in the caller's process, bypassing gen_server dispatch.

The caller takes responsibility for knowing the method does not mutate class state. Useful for long-running class methods that would otherwise block the class object's gen_server.

Limitations: only resolves methods defined directly on the target class module (does not walk the superclass chain). Class variables and self are not available to the method (nil and #{} are passed).

Examples

MyClass performLocally: #run:ctx: withArguments: #(input, ctx)

perform: selector withArguments: arguments timeout: timeoutMs

Send a message dynamically with an arguments list and explicit timeout.

The timeout (in milliseconds or #infinity) applies to the gen_server:call when the receiver is an actor. For value types, timeout is ignored.

Examples

actor perform: #query withArguments: #(sql) timeout: 30000