flyology_bench API reference

Description

Maximum supported registered identities in one recording session.

Abandoned

function Abandoned (Result : Recorded_Measurement) return Natural

Number of spans finalized without Finish.

Parameters

Result: Recorded snapshot.

Return value

Abandoned span count.

Attribution

function Attribution
  (Result : Recorded_Measurement;
   Axis   : Metric_Axis) return Metric_Attribution

Return attribution quality for an axis.

Parameters

Result: Recorded snapshot.
Axis: Metric axis.

Return value

Boundary and ownership quality for Axis.

Begin_Sample

procedure Begin_Sample
  (Object : in out Recorder;
   Item   : Benchmark;
   Value  : in out Span)

Start a span. The benchmark must belong to a running recorder.

Parameters

Object: Running recorder.
Item: Registered identity owned by Object.
Value: Reusable inactive span receiving starting snapshots.

Raised exceptions

Invalid_Benchmark: Item does not belong to Object.
Recording_Not_Started: Object is not running.
Span_Already_Active: Value already marks an active span.

Benchmark

type Benchmark is private;

Stable, opaque identity registered before a session starts. It avoids string lookup and allocation in request paths.

Benchmark_Capacity

subtype Benchmark_Capacity is Positive range 1 .. 256;

Maximum supported registered identities in one recording session.

Benchmarks

function Benchmarks (Object : Recorder) return Natural

Number of registered benchmarks.

Parameters

Object: Recorder to inspect.

Return value

Registered identity count.

Compare_Independent

procedure Compare_Independent
  (Reference : Recorded_Measurement;
   Contender : Recorded_Measurement;
   Result    : out Recorded_Comparison;
   Practical_Threshold_Percent : Long_Float := 1.0;
   Random_Seed : Long_Long_Integer := 1)

Compare independently collected distributions. Unlike Compare, this does not assume adjacent or correlated sample pairs.

Parameters

Reference: Independently collected baseline distribution.
Contender: Independently collected candidate distribution.
Result: Independent bootstrap comparison.
Practical_Threshold_Percent: Relative practical-effect threshold.
Random_Seed: Deterministic bootstrap seed.

Raised exceptions

Constraint_Error: Practical_Threshold_Percent is negative.

Compare_Metric

function Compare_Metric
  (Result : Recorded_Comparison;
   Axis   : Metric_Axis) return Metric_Comparison_Result

Return one independently resampled metric comparison.

Parameters

Result: Independent comparison.
Axis: Metric axis.

Return value

Available or unavailable metric comparison.

Configuration

type Configuration is record
   Metrics              : Metric_Set := Process_Resource_Metrics;
   Scheduler_Probe      : Flyology_Scheduler_Probe := null;
   Retention            : Retention_Policy := Reservoir;
   Random_Seed          : Long_Long_Integer := 1;
   Practical_Threshold_Percent : Long_Float := 1.0;
end record;

Recording-session policy. Registration and allocation happen before Start; Begin_Sample and Finish perform no Ada heap allocation.

Record fields

Metrics: Axes captured around each application-supplied span.
Scheduler_Probe: Optional cumulative Flyology scheduler source.
Retention: Bounded sample retention policy.
Random_Seed: Seed used by reservoir selection and bootstrapping.
Practical_Threshold_Percent: Smallest relative change used for an independent-comparison verdict.

Contender_Metric_Status

function Contender_Metric_Status
  (Result : Recorded_Comparison;
   Axis   : Metric_Axis) return Metric_Availability

Return the contender collection status retained by the comparison.

Parameters

Result: Independent comparison.
Axis: Metric axis.

Return value

Contender status.

Contender_Name

function Contender_Name (Result : Recorded_Comparison) return String

Return the contender identity.

Parameters

Result: Independent comparison.

Return value

Contender name.

Default_Configuration

Default_Configuration : constant Configuration := (others => <>);

Default policy for externally recorded spans.

Dropped

function Dropped (Result : Recorded_Measurement) return Natural

Number of observations omitted from retained raw storage.

Parameters

Result: Recorded snapshot.

Return value

Observed minus retained count.

Finish

procedure Finish
  (Value   : in out Span;
   Outcome : Sample_Outcome := Success)

Finish a span and retain or aggregate its measurements. End probes run before bounded-store synchronization, keeping recorder storage work out of the observed wall-time interval.

Parameters

Value: Active span to finish.
Outcome: Application result counted for this span.

Raised exceptions

Span_Already_Finished: Value is not active.

In_Flight

function In_Flight (Result : Recorded_Measurement) return Natural

Number of spans still active when the snapshot was captured.

Parameters

Result: Recorded snapshot.

Return value

Active span count.

Invalid_Benchmark

Invalid_Benchmark         : exception;

Raised when a handle does not belong to the supplied recorder.

Metric_Sample

function Metric_Sample
  (Result : Recorded_Measurement;
   Axis   : Metric_Axis;
   Index  : Positive) return Long_Float

Return one retained metric value in Metric_Unit units.

Parameters

Result: Recorded snapshot.
Axis: Requested metric axis.
Index: One-based valid sample index for Axis.

Return value

Retained sample value.

Raised exceptions

Constraint_Error: Axis is unavailable or Index is out of range.

Metric_Samples

function Metric_Samples
  (Result : Recorded_Measurement;
   Axis   : Metric_Axis) return Natural

Return valid retained value count for an axis.

Parameters

Result: Recorded snapshot.
Axis: Metric axis.

Return value

Valid retained values for Axis.

Metric_Statistics

function Metric_Statistics
  (Result : Recorded_Measurement;
   Axis   : Metric_Axis) return Metric_Summary

Return one axis summary over its valid individual-span samples.

Parameters

Result: Recorded snapshot.
Axis: Requested metric axis.

Return value

Summary over valid retained samples.

Metric_Status

function Metric_Status
  (Result : Recorded_Measurement;
   Axis   : Metric_Axis) return Metric_Availability

Return collection status for an axis. Metric_Collected means every retained span has a value; Metric_Partially_Collected means only a subset does.

Parameters

Result: Recorded snapshot.
Axis: Metric axis.

Return value

Collected, unavailable, or not-requested status.

Name

function Name (Item : Benchmark) return String

Return a stable name for a registered benchmark.

Parameters

Item: Registered identity.

Return value

Human-readable registered name.

Name

function Name (Result : Recorded_Measurement) return String

Return the recorded identity.

Parameters

Result: Recorded snapshot.

Return value

Human-readable registered name.

Observation_Id

function Observation_Id
  (Result : Recorded_Measurement;
   Index  : Positive) return Natural

Return the monotonic observation number of one retained span. Reservoir storage does not imply observation order; use this value as its identity.

Parameters

Result: Recorded snapshot.
Index: One-based retained row index.

Return value

Observation number assigned when the span finished.

Raised exceptions

Constraint_Error: Index is out of range.

Observed

function Observed (Result : Recorded_Measurement) return Natural

Total completed spans observed for one benchmark, including samples not retained by the selected bounded policy.

Parameters

Result: Recorded snapshot.

Return value

Completed observation count.

Outcome_At

function Outcome_At
  (Result : Recorded_Measurement;
   Index  : Positive) return Sample_Outcome

Return the application outcome attached to one retained span.

Parameters

Result: Recorded snapshot.
Index: One-based retained row index.

Return value

Recorded outcome.

Raised exceptions

Constraint_Error: Index is out of range.

Outcomes

function Outcomes
  (Result  : Recorded_Measurement;
   Outcome : Sample_Outcome) return Natural

Number of finished spans for one outcome.

Parameters

Result: Recorded snapshot.
Outcome: Outcome to count.

Return value

Completed spans with Outcome.

Recorded_Comparison

type Recorded_Comparison is private;

Independent-sample comparison of two recorded measurements.

Recorded_Measurement

type Recorded_Measurement is private;

Deep snapshot of retained individual-span data.

Recorder

type Recorder
  (Maximum_Benchmarks : Benchmark_Capacity;
   Retained_Samples   : Retained_Capacity) is limited private;

Owns registrations, bounded stores, and session-wide telemetry. The recorder must outlive every Benchmark and Span obtained from it.

Record fields

Maximum_Benchmarks: Maximum number of identities registered before Start.
Retained_Samples: Bounded raw sample capacity for each identity.

Recording_Already_Started

Recording_Already_Started : exception;

Raised when a one-shot session or its dashboard is started twice.

Recording_Not_Started

Recording_Not_Started     : exception;

Raised when Begin_Sample is called outside a running session.

Reference_Metric_Status

function Reference_Metric_Status
  (Result : Recorded_Comparison;
   Axis   : Metric_Axis) return Metric_Availability

Return the reference collection status retained by the comparison.

Parameters

Result: Independent comparison.
Axis: Metric axis.

Return value

Reference status.

Reference_Name

function Reference_Name (Result : Recorded_Comparison) return String

Return the reference identity.

Parameters

Result: Independent comparison.

Return value

Reference name.

Register

procedure Register
  (Object : in out Recorder;
   Name   : String;
   Item   : out Benchmark)

Parameters

Object: Recorder that owns the identity.
Name: Stable human-readable identity, truncated to 96 characters.
Item: Returned hot-path handle.

Raised exceptions

Registration_Closed: Registration is already frozen.
Too_Many_Benchmarks: Capacity has been reached.

Registration_Closed

Registration_Closed       : exception;

Raised when registration is attempted after Start.

Relative_Change_Confidence_High

function Relative_Change_Confidence_High
  (Result : Recorded_Comparison) return Long_Float

Return the upper relative-change endpoint.

Parameters

Result: Independent comparison.

Return value

Upper 95-percent confidence endpoint in percent.

Raised exceptions

Constraint_Error: Wall comparison is unavailable.

Relative_Change_Confidence_Low

function Relative_Change_Confidence_Low
  (Result : Recorded_Comparison) return Long_Float

Return the lower relative-change endpoint.

Parameters

Result: Independent comparison.

Return value

Lower 95-percent confidence endpoint in percent.

Raised exceptions

Constraint_Error: Wall comparison is unavailable.

Relative_Change_Percent

function Relative_Change_Percent
  (Result : Recorded_Comparison) return Long_Float

Return contender median change relative to reference.

Parameters

Result: Independent comparison.

Return value

Percent change, negative when contender wall time is lower.

Raised exceptions

Constraint_Error: Wall comparison is unavailable.

Retained

function Retained (Result : Recorded_Measurement) return Natural

Number of retained individual spans.

Parameters

Result: Recorded snapshot.

Return value

Retained raw observation count.

Retained_Capacity

subtype Retained_Capacity is Positive range 10 .. 100_000;

Maximum retained observations for each registered identity.

Retention_Policy

type Retention_Policy is (Reservoir, First_N, Latest_N);

Policy used after a benchmark has observed more samples than it can retain. Aggregate counters always cover every finished span.

Enumeration literals

Reservoir: Keep a bounded pseudorandom sample of the complete run.
First_N: Keep the first Retained_Samples observations.
Latest_N: Keep the most recent Retained_Samples observations.

Sample_Metric_Status

function Sample_Metric_Status
  (Result : Recorded_Measurement;
   Index  : Positive;
   Axis   : Metric_Axis) return Metric_Availability

Return collection status for one axis of one retained span.

Parameters

Result: Recorded snapshot.
Index: One-based retained row index.
Axis: Metric axis.

Return value

Per-span collection status.

Raised exceptions

Constraint_Error: Index is out of range.

Sample_Metric_Value

function Sample_Metric_Value
  (Result : Recorded_Measurement;
   Index  : Positive;
   Axis   : Metric_Axis) return Long_Float

Return one axis value from one retained span without losing cross-axis alignment.

Parameters

Result: Recorded snapshot.
Index: One-based retained row index.
Axis: Metric axis.

Return value

Per-span value in Metric_Unit units.

Raised exceptions

Constraint_Error: Index is out of range or Axis has no value.

Sample_Outcome

type Sample_Outcome is (Success, Failure, Timeout, Cancelled);

Result attached to one completed span.

Enumeration literals

Success: The operation completed normally.
Failure: The operation raised or returned an error.
Timeout: The operation exceeded an application deadline.
Cancelled: The caller cancelled the operation.

Scope_Changed_Samples

function Scope_Changed_Samples
  (Result : Recorded_Measurement;
   Axis   : Metric_Axis) return Natural

Return samples excluded because their native execution scope changed.

Parameters

Result: Recorded snapshot.
Axis: Thread-scoped metric axis.

Return value

Excluded scope-changing sample count.

Session_Elapsed

function Session_Elapsed (Result : Recorded_Measurement) return Duration

Elapsed wall time covered by the recording session snapshot.

Parameters

Result: Recorded snapshot.

Return value

Session wall time through Stop or Snapshot.

Snapshot

procedure Snapshot
  (Object : Recorder;
   Item   : Benchmark;
   Result : out Recorded_Measurement)

Copy the currently retained data for one benchmark. Snapshot can be called while recording; its values form one coherent store snapshot.

Parameters

Object: Recorder that owns Item.
Item: Registered identity to copy.
Result: Deep result snapshot.

Raised exceptions

Invalid_Benchmark: Item does not belong to Object.

Span

type Span is limited private;

One active measurement boundary. A span can be finished exactly once. Finalizing an unfinished span increments the abandoned count and never records a successful sample.

Span_Already_Active

Span_Already_Active       : exception;

Raised when Begin_Sample receives an already active span.

Span_Already_Finished

Span_Already_Finished     : exception;

Raised when Finish receives a span that is not active.

Speedup

function Speedup (Result : Recorded_Comparison) return Long_Float

Return reference median divided by contender median.

Parameters

Result: Independent comparison.

Return value

Speedup, greater than one when the contender is faster.

Raised exceptions

Constraint_Error: Wall comparison is unavailable.

Speedup_Confidence_High

function Speedup_Confidence_High
  (Result : Recorded_Comparison) return Long_Float

Return the upper bootstrap speedup endpoint.

Parameters

Result: Independent comparison.

Return value

Upper 95-percent confidence endpoint.

Raised exceptions

Constraint_Error: Wall comparison is unavailable.

Speedup_Confidence_Low

function Speedup_Confidence_Low
  (Result : Recorded_Comparison) return Long_Float

Return the lower bootstrap speedup endpoint.

Parameters

Result: Independent comparison.

Return value

Lower 95-percent confidence endpoint.

Raised exceptions

Constraint_Error: Wall comparison is unavailable.

Start

procedure Start
  (Object : in out Recorder;
   Config : Configuration := Default_Configuration)

Freeze registration and begin accepting spans.

Parameters

Object: Recorder to start.
Config: Frozen recording and metric policy.

Raised exceptions

Recording_Already_Started: The one-shot session already ran.
Invalid_Benchmark: No benchmark identity was registered.

Start_Live_Terminal

procedure Start_Live_Terminal
  (Object           : in out Recorder;
   Refresh_Interval : Duration := 0.250;
   ANSI             : Boolean := True)

Start an ANSI dashboard on standard output. The display refreshes in place until Stop_Live_Terminal is called; it is not an event log.

Parameters

Object: Recorder to observe.
Refresh_Interval: Delay between complete redraws.
ANSI: Whether to emit color and cursor-control sequences.

Raised exceptions

Recording_Already_Started: A dashboard is already active.

Stop

procedure Stop (Object : in out Recorder)

Stop accepting new spans. Already active spans may still finish; their count remains visible until they do.

Parameters

Object: Recorder to stop.

Stop_Live_Terminal

procedure Stop_Live_Terminal (Object : in out Recorder)

Stop the dashboard, wait for its task, and leave the cursor below the final display.

Parameters

Object: Recorder whose dashboard should stop.

Too_Many_Benchmarks

Too_Many_Benchmarks       : exception;

Raised when registration exceeds Maximum_Benchmarks.

Unavailable_Metric_Samples

function Unavailable_Metric_Samples
  (Result : Recorded_Measurement;
   Axis   : Metric_Axis) return Natural

Return retained samples without a valid value for an axis, including scope changes and probe failures.

Parameters

Result: Recorded snapshot.
Axis: Metric axis.

Return value

Retained samples lacking Axis.

Verdict

function Verdict
  (Result : Recorded_Comparison) return Comparison_Verdict

Return the practical independent-comparison verdict.

Parameters

Result: Independent comparison.

Return value

Faster, equivalent, or inconclusive verdict.

Wall_Comparison_Available

function Wall_Comparison_Available
  (Result : Recorded_Comparison) return Boolean

Report whether wall-derived speedup and relative-change values exist.

Parameters

Result: Independent comparison.

Return value

True when both sides supplied positive, complete wall samples.