CHANGELOG.md

Changelog

All Notable changes to bakame/stackwatch will be documented in this file.

Next - Qandala - 2026-XX-XX

Added

• BC BREAK: Rename stack_cdump to stack_call_dump
• BC BREAK: Rename stack_bdump to stack_bench_dump
• BC BREAK: Rename stack_rdump to stack_report_dump
• BC BREAK: Rename stack_cdd to stack_call_dd
• BC BREAK: Rename stack_bdd to stack_bench_dd
• BC BREAK: Rename stack_rdd to stack_report_dd
• BC BREAK: Rename Stack::dumpCall to Stack::callDump
• BC BREAK: Rename Stack::ddCall to Stack::callDd
• BC BREAK: Rename Stack::dumpReport to Stack::reportDump
• BC BREAK: Rename Stack::ddReport to Stack::reportDd
• BC BREAK: Rename Stack::benchmark to Stack::bench
• BC BREAK: Rename Stack::dumpBenchmark to Stack::benchDump
• BC BREAK: Rename Stack::ddBenchmark to Stack::benchDd

Fixed

• Call Location calculation to include the correct call start path.

Deprecated

• None

Remove

• None

0.16.1 - Pointe-Noire - 2026-02-07

Added

• None

Fixed

• Version class
• Simplify PSR-3 usage (remove nullable calls)

Deprecated

• None

Remove

• None

0.16.0 - Pointe-Noire - 2026-02-07

Added

• PerformanceAssertions to align with AggregatedMetrics usage and generation.
• Report::iterations() method is added.
• StackWatchException
• NoMetricSelected exceptions

Fixed

• BC BREAK: improve Report generation validation and adds missing Report::iterations() method
• AggregatedMetrics::dd and Statistics::dd improved implementation
• BC BREAK: global functions are namespaced
• Improve Github actions
• BC BREAK: exceptions are now all inheriting from a base StackWatchException

Deprecated

• None

Remove

• MetricsAssertions trait replaced by the PerformanceAssertions trait
• BC BREAK: Enums can no longer be profiled using the CLI instance as it was making no sense.

0.15.0 - Ouagadougou - 2025-09-09

Added

• BC BREAK: Rename stack to stack_call
• BC BREAK: Rename stack_dump to stack_cdump
• BC BREAK: Rename stack_dd to stack_cdd
• BC BREAK: Rename stack_metrics to stack_bench
• BC BREAK: Rename stack_mdump to stack_bdump
• BC BREAK: Rename stack_mdd to stack_bdd
• BC BREAK: Rename Stack::execute to Stack::call
• BC BREAK: Rename Stack::metrics to Stack::benchmark
• BC BREAK: Rename Stack::dumpMetrics to Stack::dumpBenchmark
• BC BREAK: Rename Stack::ddMetrics to Stack::ddBenchmark
• Added AggregatedMetrics to distinguish raw and calculated metrics
• Added Report::row to make the Report public API consistent
• Added Report::column to have a single source of truth for statistics generation
• Added OtlExporter to export data to an Open Telemetry server
• Added MetricType Enum to list possible metrics supported by the package
• Added Profiler missing aggregated related methods.
• Added MetricsAssertions missing aggregation methods preset
• Added CallbackDumper to simplify dd implementation
• Added the Renderer interface
• Added the StackMetadata renderer to enable rendering the stack_* metadata

Fixed

• BC BREAK: Statistics no longer exposes its main unit it now exposes its type using the MetricType enum.
• Timeline::dump and Timeline::dd can take an optional filter callable.
• ViewExporter no longer needs or requires the Renderer which is removed
• BC BREAK: Move all the classes related to export in their own namespace Bakame\Stackwatch\Exporter

Deprecated

• None

Remove

• Removed all Metrics static method related to aggregated data. use Report::metrics() instead.
• Removed Metrics::add method
• Removed the internal Renderer class
• BC BREAK: Remove access to Report properties (they are made private to improve the public API)

0.14.0 - Nouakchott - 2025-09-05

Added

• PHPUnit assertions helper trait MetricsAssertions to help profile testing using PHPUnit Framework
• Added stack, stack_watch, stack_report, stack_dump, stack_dd, stack_metrics, stack_mdump and stack_mdd to profile, dump a human-readable result into the console or the web browser using global functions to ease DX.
• Added ViewExporter and Renderer to allow viewing the log in browser or in the CLI
• Added dump() and dd() methods to Profiler, Timeline, SpanAggregator, Snapshot, Metrics, Span, Report
• Added Metrics::sum, Metrics::range,Metrics::minimum,Metrics::maximun,Metrics::median, Metrics::aggregate
• Adding the AggregationType Enum to improve Stack::metrics, the Profile Attribute and the Metrics usage.
• BC BREAK: Summary is renamed Span.
• CallLocation class to allow recording where the package Snapshot was called from #8
• CallRange class to allow manipulating location range within the Summary class.
• Environment::toHuman and Environment::human methods
• Metrics::yieldFrom to lazily yield Metrics from other objects (Report, Timeline, Profiler, Span and Metrics)
• Added withers method on the Input
• Added Input::toArguments to ease constructing the CLI command out of the Input instance.
• Added Input::fromArray, Input::toArray and Input now implements the JsonSerializable interface
• --dry-run option to stackwatch command to list profiling targets without performing the profile
• --log option to stackwatch command to specify the logfile where error logs are being stored
• --file-suffix to restrict files to be profiled based on their suffix.
• --method-visibiloty to restrict methods to be profiled based on their visibility
• BC BREAK: Visibility is renamed Display
• BC BREAK: State is renamed Feature
• BC BREAK: Input::TABLE_FORMAT is renamed Input::TEXT_FORMAT
• Added a Translator class to improve human-readable key translation.
• Added Profiler::dump and Profiler::dd to profile, dump a human-readable result into the console or the web browser
• Added toHuman() method to return a human-readable version of toArray
• Added human() method to return the human-redable version of a single property.
• Added Snapshot relation method compareTo and its aliases isBefore* isAfter* and isAtSameTime using the Snapshot::hrtime property
• BC BREAK: Profiler class is split into two classes Stack and Profiler

Fixed

• UnitOfWork internal code improvement.
• BC BREAK: Snapshot::forHuman properties key have been updated to remove JSON like string representation.
• BC BREAK: Snapshot::cpu property is replaced by 2 properties Snapshot::cpuUserTime and Snapshot::cpuSystemTime.
• LabelGenerator::generate now also accepts the hyphen (-) character.
• Adding support for Timeline on Metrics::sum and Metrics::average static methods.
• BC BREAK: Fix Report and Environment keys used for toArray and forHuman
• BC BREAK: Fix Statistics::count is not Statistics::iterations keys used for toArray and forHuman
• BC BREAK: Fix Metrics calculation
• BC BREAK: the Profile attribute default to showing the full detailed metrics.

Deprecated

• None

Removed

• BC BREAK: Summary is removed and replaced by Span.
• BC BREAK: forHuman() method is removed and replaced by 2 methods toHuman() and human().
• BC BREAK: the constants attached to the Profile attribute use the AggregateMode enum instead.
• BC BREAK: Removed open telemetry exporter

0.13.0 - Marrakesh - 2025-08-14

Added

• --tags option to the CLI command to filter profile that needs to be run based on the tags property of the #[Profile] attribute.
• --memory-limit option to the CLI command to control the memroy limit of the main process.
• UnitSpacing Enum to control the space between value and unit when using the format related methods of MemoryUnit and DurationUnit.
• Visibility and State Enums to improve Input option flags properties.

Fixed

• BC BREAK: Timeline::delta default to creating the delta between the from and the next snapshot before it was with the last snapshot if no to label was given.
• BC BREAK: Input boolean properties are replaced by discret Enum

Deprecated

• None

Removed

• BC BREAK: Marker class renamed Timeline

0.12.0 - Luanda - 2025-08-11

Added

• --depth argument and --no-recursion flag to control recursion on directories.
• --isolation flag to handle in isolation each file.

Fixed

• BC BREAK: command line format options table replace the default option cli
• BC BREAK: Changed Bakama\Stachwatcher\Marker::summary method name to Bakama\Stachwatcher\Marker::summarize
• Internal improvement, Lazy evaluation is now done in the UnitOfWork

Deprecated

• None

Removed

• None

0.11.0 - Kampala - 2025-08-03

Added

• BC BREAK: Changed namespace from Bakame\Aide\Profiler to Bakama\Stachwatcher
• Statistics class
• Report class and the Profiler::report method.
• ConsoleExporter::exportMetrics
• ConsoleExporter::exportStatistics
• ConsoleExporter::exportReport
• JsonExporter
• The Stackwatcher command to ease profiling using command line

Fixed

• None

Deprecated

• None

Removed

• BC BREAK: ConsoleTableExporter renamed ConsoleExporter and moved under the Exporter namespace
• BC BREAK: Profiler::executionTime removed use Profiler::metrics instead
• BC BREAK: Profiler::cpuTime removed use Profiler::metrics instead
• BC BREAK: Profiler::memoryUsage removed use Profiler::metrics instead
• BC BREAK: Profiler::peakMemoryUsage removed use Profiler::metrics instead
• BC BREAK: Profiler::realMemoryUsage removed use Profiler::metrics instead
• BC BREAK: Profiler::realPeakMemoryUsage removed use Profiler::metrics instead
• BC BREAK: Marker::executionTime removed use Marker::metrics instead
• BC BREAK: Marker::cpuTime removed use Marker::metrics instead
• BC BREAK: Marker::memoryUsage removed use Marker::metrics instead
• BC BREAK: Marker::peakMemoryUsage removed use Marker::metrics instead
• BC BREAK: Marker::realMemoryUsage removed use Marker::metrics instead
• BC BREAK: Marker::realPeakMemoryUsage removed use Marker::metrics instead
• BC BREAK: ProfiledResult is renamed Result

0.10.0 - Johannesburg - 2025-07-17

Added

• Marker::complete and Marker::isComplete
• Profiler::hasSummaries
• Profiler::filter
• Snapshot::fromArray
• Metrics::fromArray
• Summary::fromArray
• LabelGenerator::withLength label length can be configured
• MemoryUnit::convertFrom and MemoryUnit::convertTo
• DurationUnit::convertFrom and DurationUnit::convertTo
• The static methods from the Profiler now can warm up before recording the metrics.

Fixed

• BC BREAK: ProfilingResult::result is renamed ProfilingResult::returnValue
• BC BREAK: ProfilingResult::ProfilingData is renamed ProfilingResult::summary
• BC BREAK: ProfilingResult is renamed ProfiledResult
• BC BREAK: ProfilingData is renamed Summary
• BC BREAK: Label is renamed LabelGenerator
• BC BREAK: Exporter::exportProfilingData is renamed Exporter::exportSummary
• BC BREAK: Snapshot::toArray and Snapshot::jsonSerialize representation simplified
• BC BREAK: Summary::toArray and Summary::jsonSerialize representation simplified
• BC BREAK: Summary::__constructsignature changed
• BC BREAK: Profiler::toArray and Profiler::jsonSerialize representation simplified
• BC BREAK: Marker::toArray and Marker::jsonSerialize representation simplified
• BC BREAK: Marker::delta removed the 3rd argument
• BC BREAK: Marker::summary throws when no summary can be generated
• BC BREAK: Marker::finish is renamed Marker::take
• Snapshot::cpu keys presence is validated on instantiation

Deprecated

• None

Removed

• None

0.9.0 - Ibadan - 2025-07-09

Added

• Added Metrics::forHuman to ease getting human-readable metrics representations.
• Added Snapshot::forHuman to ease getting human-readable metrics representations.
• Added Environment OS Platform related methods.
• Added Marker to provide an alternative way to profile your code.
• Added Label to decouple label generation from both Marker and Profiler.
• Added Exporter::exportMarker method to the interface.
• Added Profiler::run with Profiler::__invoke becoming its alias
• Added Marker::identifier and Profiler::identifierto ease identify each instance uniquely

Fixed

• BC BREAK: Profiler::last is renamed Profiler::latest to be consistent with Marker::latest
• BC BREAK: Profiler::runWithLabel is renamed Profiler::profile

Deprecated

• None

Removed

• None

0.8.0 - Harare - 2025-07-07

Added

• Added Environment::rawMemoryLimit to keep the original value if it cannot be properly parsed.

Fixed

• BC BREAK: Environment::memoryLimit is a nullable int
• BC BREAK: Renamed Metrics::stats to Metrics::toArray
• BC BREAK: Renamed Snapshot::stats to Snapshot::toArray
• BC BREAK: Renamed ProfilingData::stats to ProfilingData::toArray
• BC BREAK: Renamed Environment::stats to Environment::toArray

Deprecated

• None

Removed

• None

0.7.1 - Gaborone - 2025-07-06

Added

• None

Fixed

• Metrics::cpuTime calculation

Deprecated

• None

Removed

• None

0.7.0 - Gaborone - 2025-07-05

Added

• Profiler::average
• Environment class
• ConsoleTableExporter::exportEnvironment to visually show the environment settings
• ConsoleTableExporter::exportProfiler also provide the average as a summary

Fixed

• Exporter::exportProfiler now takes a second parameter to filter using the label.
• Metrics::average, fix bug in the calculation.

Deprecated

• None

Removed

• None

0.6.0 - Fezzan - 2025-07-03

Added

• DurationUnit replaces TimeUnit Enum.
• Adding Exporter::exportSnapshot method.

Fixed

• BC BREAK: simplify ConsoleTableExporter memory and time unit display
• BC BREAK: rewrite and simplify MemoryUnit and DurationUnit Enum
• BC BREAK: Snapshot::executionTime is renamed Snapshot::hrtime.
• BC BREAK: Metrics::avg is renamed Metrics::average.

Deprecated

• None

Removed

• BC BREAK: TimeUnit is removed in favor of DurationUnit Enum

0.5.0 - Enugu - 2025-07-01

Added

• All Profiler static methods can have a logger attached to them
• MemoryUnit and TimeUnit Enum to ease metrics values conversion.

Fixed

• None

Deprecated

• None

Removed

• BC BREAK: renamed CliExporter as ConsoleTableExporter

0.4.0 - Durban - 2025-06-29

Added

• Metrics::avg supports ProfilingData instances.
• Metrics::add public method.

Fixed

• library packaging by removing development related files from downloads.
• BC BREAK: normalize duration related metrics to be expressed in nanoseconds.
• BC BREAK: normalize memory related metrics to be expressed in bytes.
• BC BREAK: Adding missing field in Metrics::stats returned array.

Deprecated

• None

Removed

• BC BREAK: ProfilingResult::profile static method removed
• BC BREAK: ProfilingData::randomLabel static method removed

0.3.0 - Cairo - 2025-06-29

Added

• Profiler::first, Profiler::last, Profiler::nth
• Metrics
• Profiler metrics related static methods.
• Profiler::execute static method.

Fixed

• None

Deprecated

• None

Removed

• BC BREAK: The Renderer interface is removed
• BC BREAK: CliTableRenderer renamed CliExporter
• BC BREAK: CliTableRenderer implements the Exporter interface
• BC BREAK: Profiler::lastProfile replaced by Profiler::last
• BC BREAK: Profiler::get returns the last Profile for a specific label before it was returning the first one.
• BC BREAK: Profile::metrics returns a Metrics object before the metrics where attached directly to the profile.
• BC BREAK: The Metrics::executionTime is now calculated using hrtime instead of microtime and returns the value in nanoseconds
• BC BREAK: The Profile class is now a readonly value object, the methods showing the progress of the profile generation are removed.
• BC BREAK: Profile renamed ProfilingData
• BC BREAK: ProfileResult::value renamed ProfileResult::result
• BC BREAK: ProfileResult::profile renamed ProfileResult::profilingData

0.2.0 - Bamako - 2025-06-27

Added

• ProfilingException as the exception marker
• UnableToProfile and InvalidProfileState exceptions
• OpenTelemetryExporter to enable exporting the Profiler

Fixed

• None

Deprecated

• None

Removed

• None

0.1.0 - Addis Ababa - 2025-06-26

Initial release!