instrument_flight_recorder (instrument v1.0.0)

Flight recorder for low-overhead message tracing.

This module captures message passing events at VM level with minimal overhead, correlating them with OpenTelemetry spans via trace_id labels.

Uses erlang:trace with a custom erl_tracer NIF that distributes events across a pool of workers, avoiding the single-process bottleneck of seq_trace.

Example Usage

  %% Flight recorder starts enabled by default
  instrument_tracer:with_span(<<"request">>, fun() ->
    %% All message passing captured with trace_id label
    gen_server:call(some_server, request),
    another_process ! message
  end),
 
  %% On error or slow request, dump the trace
  TraceId = instrument_tracer:trace_id(),
  Events = instrument_flight_recorder:get_trace(TraceId).

Summary

Functions

clear()

Clears all events from the buffer.

code_change(OldVsn, State, Extra)

disable()

Disables the flight recorder. Stops the worker pool. Buffer is retained.

dump_all()

Gets all events in the buffer.

dump_trace(TraceId)

Gets and clears all events for a trace ID.

enable()

Enables the flight recorder. Starts the worker pool and enables tracing.

get_trace(TraceId)

Gets all events for a trace ID. Returns events as a list of {Timestamp, Event} tuples.

handle_call(Request, From, State)

handle_cast(Msg, State)

handle_info(Info, State)

init(Args)

is_enabled()

Checks if the flight recorder is enabled.

mark(Name)

Adds a custom marker event with current trace context.

mark(Name, Meta)

Adds a custom marker event with metadata.

set_buffer_size(Size)

Sets the buffer size (for testing). Takes effect immediately.

start_link()

Starts the flight recorder with default options.

start_link(Args)

Starts the flight recorder with options.

stats()

Returns statistics about the flight recorder.

terminate(Reason, State)

tracer_state(TraceId)

Gets the tracer state for use with erlang:trace.