package

github.com/crystal-lang/perf-tools

main / published Mar 10, 2026 / repository

An assortment of tools to track resources in Crystal applications

perf-tools

An assortment of tools to track resources in Crystal applications.

Usage

To log the number of allocations, objects, their sizes, or their linking graph:

require "perf_tools/mem_prof"

PerfTools::MemProf.log_object_counts(STDOUT)
PerfTools::MemProf.log_object_sizes(STDOUT)
PerfTools::MemProf.log_allocations(STDOUT)
PerfTools::MemProf.pretty_log_allocations(STDOUT)
PerfTools::MemProf.pretty_log_object_graph(STDOUT)

To log all fibers:

require "perf_tools/fiber_trace"

PerfTools::FiberTrace.log_fibers(STDOUT)
PerfTools::FiberTrace.pretty_log_fibers(STDOUT)

To print the runtime status of execution contexts and fibers:

require "perf_tools/scheduler_trace"

PerfTools::SchedulerTrace.print_runtime_status
PerfTools::SchedulerTrace.every(5.seconds)
PerfTools::SchedulerTrace.on(Signal::USR1, details: true)

And for a full runtime status, with the yield stack of suspended fibers:

require "perf_tools/fiber_trace"
require "perf_tools/scheduler_trace"

PerfTools::SchedulerTrace.print_runtime_status(details: true)

Check each tool's instructions for more information.

Installation

Add this to your application's shard.yml:

development_dependencies:
  perf_tools:
    github: crystal-lang/perf-tools

Contributing

  1. Fork it ( https://github.com/crystal-lang/perf-tools/fork )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request

API

  • ArgumentError

    Raised when the arguments are wrong and there isn't a more specific Exception class.

  • Array(T)

    An Array is an ordered, integer-indexed collection of objects of type T.

  • Box(T)

    A Box allows turning any object to a Void* and back.

  • Channel(T)

    A Channel enables concurrent communication between fibers.

  • Deque(T)

    A Deque ("double-ended queue") is a collection of objects of type T that behaves much like an Array.

  • Dir

    Objects of class Dir are directory streams representing directories in the underlying file system.

  • DivisionByZeroError

    Raised when attempting to divide an integer by 0.

  • Exception

    Represents errors that occur during application execution.

  • File

    A File instance represents a file entry in the local file system and allows using it as an IO.

  • GC
  • Hash(K, V)

    A Hash represents a collection of key-value mappings, similar to a dictionary.

  • IO

    The IO class is the basis for all input and output in Crystal.

  • IndexError

    Raised when the given index is invalid.

  • InvalidByteSequenceError
  • KeyError

    Raised when the specified key is not found.

  • NilAssertionError

    Raised when a not_nil! assertion fails.

  • NotImplementedError

    Raised when a method is not implemented.

  • Object

    Object is the base type of all Crystal objects.

  • OverflowError

    Raised when the result of an arithmetic operation is outside of the range that can be represented within the given operands types.

  • PerfTools

    An assortment of tools to track resources in Crystal applications.

  • PrettyPrint

    This class implements a pretty printing algorithm.

  • Process
  • Reference

    Reference is the base class of classes you define in your program.

  • Regex

    A Regex represents a regular expression, a pattern that describes the contents of strings.

  • RuntimeError

    Raised when there is an internal runtime error

  • String

    A String represents an immutable sequence of UTF-8 characters.

  • TypeCastError

    Raised when the type cast failed.