Skip to content

Runtime Tracing Package

The Runtime Tracing package exposes the runtime's event tracing infrastructure to Pony programs. Tracing records scheduler, actor, and GC events as Chrome Trace Event JSON, either to a file or to an in-memory flight recorder that dumps on crash.

Categories control which kinds of events the runtime records. They are configured at startup via --ponytracingcategories and can be changed at runtime through this package. The three category operations are:

  • enable_categories — add the listed categories to the active set.
  • disable_categories — remove the listed categories from the active set.
  • set_categories — replace the active set with exactly the listed categories.

Each category is a primitive passed in an array:

RuntimeTracing.enable_categories(
  auth, [SchedulerTracing; ActorBehaviorTracing])

The available categories are: SchedulerTracing, SchedulerMessagingTracing, ActorTracing, ActorBehaviorTracing, ActorGCTracing, ActorStateChangeTracing, SystematicTestingTracing, SystematicTestingDetailsTracing, RuntimeLifecycleTracing, SchedulerStealingTracing, and CycleDetectorTracing.

Actor event categories (ActorTracing, ActorBehaviorTracing, etc.) trace all actors. CycleDetectorTracing enables actor events for the cycle detector only, without enabling them for every actor.

Example

use "runtime_tracing"

actor Main
  new create(env: Env) =>
    let auth = RuntimeTracingAuth(env.root)

    // Turn on scheduler and actor behavior tracing at runtime.
    match RuntimeTracing.enable_categories(
      auth, [SchedulerTracing; ActorBehaviorTracing])
    | TracingOk => env.out.print("tracing enabled")
    | TracingNotAvailable => env.out.print("not on a scheduler thread")
    | TracingLogFileError => env.out.print("could not open trace file")
    end

    // Later, disable all categories.
    RuntimeTracing.set_categories(auth, [])

Public Types