timify 0.0.6 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c471402324f5322ef254103bd678d05f6097326f65c3ad91f58d8ccc0801934
-  data.tar.gz: 0e32ff0d342fbad59f3f5ae536777f6e34f6d29a88269ed02d83dc333f2f0478
+  metadata.gz: 1903dbb0ac271c259becf4d7c99ccfaed2be1604f2279762e1544213d93fa1ff
+  data.tar.gz: 8cb993a3168f88f4ae6c9d2b5fb1d1a4ac7548d4e425cc44b91646321a637e58
 SHA512:
-  metadata.gz: c0e9c8732bb4c026fdea3be12f52a1c1249a8bafc3e19c4c999b01552c944264b7f6a463bbcce230e248e91f1954ac14564dc2a99fbcbffb9acea5a3517f3357
-  data.tar.gz: d789d1f6fa0c804fe5ad98ef53e6242b94cdc840522e1506d39581afcc56dd5de01685538e34e77008ae2c5c56cd4ca5dbec23f4fae3ad7c9f454dcc7b51a261
+  metadata.gz: 5a1516b808e8933021f8028f0edb2bd50419d6765959ae8c09b62254cac941fd1b68d5b0850e4c3809e80115bb7be0b3fd7f61554180b105eda69eddaab40c0e
+  data.tar.gz: 769d2406bd385599226d69007bc47c67e17c7a942fd65590582b847fdd7cf3cb54115b9699b1019a0ff762fedc2112ed8cfa847bc12b190b8f6a637f6b0377e2

data/.yardopts

@@ -1,5 +1,9 @@
 --readme README.md
---title 'timify - Easily calculates the time running (elapsed time) from one location to another inside your code and reports statistics.'
+--title 'timify - Calculate elapsed time between points in your code and report statistics.'
 --charset utf-8
 --markup markdown
-'lib/**/*.rb' - '*.md' - 'LICENSE'
+lib/**/*.rb
+-
+README.md
+CHANGELOG.md
+LICENSE

data/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+## 1.0.0 - 2026-09-23
+
+### Added
+
+- `Timify#measure` and `Timify.measure` time a block. Nested measures and `add` calls inside a block form a span tree: `inclusive` is the whole block and `secs` is the time not already taken by its children.
+- `Timify.trace` yields a timer and returns a `Trace` with both the block's value and the timer.
+- `Timify.enabled` / `Timify.enabled?` is a process-wide off switch. `TIMIFY_DISABLE` (`1`, `true`, or `on`) sets the default when the class loads.
+- `totals` includes `tree`, `grouped_tree`, `wall_time`, and `inclusive`, `p50`, `p95`, and `p99` on each locations, labels, and ranges entry. The printed summary shows the tree, p95, and inclusive time when it differs from self time. Flat sections are ordered slowest first. `totals(group: true)` also prints a grouped span tree.
+- `on_slow` runs callbacks when a mark or a block crosses a threshold.
+- `on_share` runs callbacks when a child span takes at least a given share of its parent's elapsed time so far.
+- `Timify[:name]` reuses a quiet timer from anywhere in the process. `Timify.clear!` drops that registry.
+- Each locations, labels, and ranges entry includes `min`, `max`, and `avg`.
+- `Timify#reset` clears recorded segments and starts the clock again.
+- `output:` sends printed lines to any object that responds to `puts`, or to a Logger via `info`.
+- RSpec suite, YARD documentation, and a GitHub Actions build on Ruby 3.2, 3.3, 3.4, and 4.0.
+
+### Fixed
+
+- `add :database` no longer raises `NoMethodError`. Symbol and string labels that read the same are grouped together.
+- `show: false` suppresses the initialization line as well as later output.
+- `status` defaults to `:on`.
+- Time spent while `status` is `:off` is no longer charged to the next `add`. `measure` still runs its block while paused, and records nothing.
+- `totals` keeps returning collected data while the timer is paused.
+- Call sites come from `caller_locations` instead of a regular expression over `caller`. Paths under the working directory are relative, and the method name is included.
+- Elapsed time uses a monotonic clock, so a wall-clock step cannot produce a negative duration.
+- Label, location, and range counts are stored separately.
+- Each thread keeps its own cursor and span stack. Shared totals are updated under a mutex.
+
+### Changed
+
+- Requires Ruby 3.2 or newer.
+- The version constant is `Timify::VERSION`.
+- There are still no runtime dependencies. `totals(json: true)` continues to use the standard-library `json`.
+- `total_time` is the sum of self time. Parallel threads can make it larger than `wall_time`.
+- Library code is split under `lib/timify/` (`span`, `trace`, `registry`, `recording`, `report`) with a short public shell in `lib/timify.rb`.
+
+## 0.0.6 - 2021-05-27
+
+- Last release published before 1.0.0. Earlier changes are in the GitHub history.

data/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2017 Mario Ruiz
+Copyright (c) 2017-2026 Mario Ruiz
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,15 +1,23 @@
 # Timify
 
 [![Gem Version](https://badge.fury.io/rb/timify.svg)](https://rubygems.org/gems/timify)
+[![CI](https://github.com/MarioRuiz/timify/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/MarioRuiz/timify/actions/workflows/ci.yml)
+[![Coverage Status](https://coveralls.io/repos/github/MarioRuiz/timify/badge.svg?branch=master)](https://coveralls.io/github/MarioRuiz/timify?branch=master)
+![Gem](https://img.shields.io/gem/dt/timify)
+![GitHub commit activity](https://img.shields.io/github/commit-activity/y/MarioRuiz/timify)
+![GitHub last commit](https://img.shields.io/github/last-commit/MarioRuiz/timify)
+![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/MarioRuiz/timify)
 
-Easily calculates the time running (elapsed time) from one location to another inside your code and reports statistics. It helps you improve your code and find out which part of your code is consuming more time.
+Timify measures elapsed time from one point in your Ruby code to another and reports it by call site, label, span tree, and the jump between call sites. Use it to see which part of a piece of code is taking the time.
+
+Requires Ruby 3.2 or newer. The gem has no runtime dependencies.
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'timify'
+gem "timify"
 ```
 
 And then execute:
@@ -22,166 +30,273 @@ Or install it yourself as:
 
 ## Usage
 
-### initialize
-You need to supply a name for your Timify instance. 
-You can have all the Timify instances you want at the same time.
+The walkthrough below times a small "create user" path: open a timer, mark steps, nest spans, share the timer across call sites, then read the report.
+
+### Create a timer
+
 ```ruby
-t = Timify.new :create_user
-t.show = false
-t.min_time_to_show = 0.5
+require "logger"
+
+timer = Timify.new(
+  :create_user,
+  show: true,
+  min_time_to_show: 0.3,
+  output: Logger.new($stdout)
+)
 ```
-min_time_to_show: minimum time to show the elapsed time when calling 'add' method
 
-show: print out results on screen
+* `show` prints the initialization line, each recorded segment, and the summary from `totals`. It defaults to `true`. Set it to `false` and the timer stays silent while it keeps recording.
+* `min_time_to_show` is the shortest segment, in seconds, that gets printed. Shorter segments are still recorded. It defaults to `0`.
+* `output` is where those lines go. An IO receives `puts`. A Logger, or anything else that responds to `info` and not `puts`, receives `info`. It defaults to `$stdout`.
+* `status` is `:on` by default. Set it to `:off` to pause, and back to `:on` to resume.
 
-you can supply those parameters also:
+You can also set the options after construction:
 
 ```ruby
-t = Timify.new :create_user, show: true, min_time_to_show: 0.3
+timer = Timify.new(:create_user)
+timer.show = false
+timer.min_time_to_show = 0.5
 ```
 
-The scopes of the instances can be even global so you can measure the elapsed times between different classes, methods... on your code.
+### Mark steps with `add`
 
-You can disable the timify counter whenever you want using the status attritute that admits :on or :off, by default is set to :on
+`add` records the time since the previous mark (creation, reset, end of the last `add`/`measure`, or resume) and returns that segment as a Float number of seconds. Pass an optional label to group those segments. A symbol and a string that read the same, such as `:database` and `"database"`, are one group. `nil` and a blank string are ignored.
 
 ```ruby
-t.status = :off
+timer = Timify.new(:create_user, show: false)
+timer.add
+sleep 0.01
+database_seconds = timer.add(:database)
+timer.add(:mail) if database_seconds > 0.2
+```
+
+The first `add` has no range. Each later `add` records the jump from the previous call site to the current one.
+
+A printed segment looks like this. Paths under the working directory are relative, and the method name is included when present. The percentage is that call site's share of the self time recorded so far. The two numbers are the timer's total self seconds, then this segment's self seconds. `(New Max)` appears when this segment is the longest one so far. A 1.0 second `:database` segment followed by a 0.5 second `:mail` segment prints:
+
+```text
+<create_user><database>(New Max): app/create_user.rb:10 in create (100%): 1.0; 1.0
+<create_user><mail>: app/create_user.rb:20 in create (33%): 1.5; 0.5
 ```
 
-### add
+### Nested `measure`
+
+`measure` times the given block and returns the block's value. Nested `measure` and `add` calls form a span tree. A parent span's inclusive time is the whole block; its self time (`secs`) is what the children did not already take. When time has passed since the previous mark, that gap is stored first as an unlabeled segment (printed as `(gap)`), and the block is stored next. A later `add` does not count the block again.
 
-Adds a new point to count the elapsed time. It will count from the last 'add' call or Timify creation in case of the first 'add'.
+`add` and `measure` share one timeline. A mark made inside the block keeps its own slice, and `measure` records only the remainder, so the same seconds are not stored twice. The block itself is not a range. If the block raises, the time until the exception is still recorded and the exception propagates. While the timer is paused, the block runs and nothing new is recorded.
+
+```ruby
+timer = Timify.new(:create_user, show: false)
+timer.measure(:request) do
+  timer.measure(:database) { :saved }
+  timer.add(:mail)
+end
+```
+
+With clocks that open `request` at 0, open `database` at 0.25 (after a 0.25 gap), close `database` at 0.75, and close `request` at 1.0, the labels report `request` as 0.25 self / 1.0 inclusive and `database` as 0.5 self / 0.5 inclusive. The tree children under `request` are the gap and `database`.
+
+`Timify.measure` builds a timer, yields it, and returns it when the block completes. It does not return the block's value.
+
+```ruby
+timer = Timify.measure(:create_user, show: false) do |job|
+  job.measure(:database) { :saved }
+  job.add(:mail)
+end
 
-You can supply a label that will summarize all the ones with the same label
+timer.totals
+```
 
-The output of this method will be the time elapsed in seconds (float).
+### `Timify.trace`
 
-Examples:
+`Timify.trace` is the same setup as `Timify.measure`, but returns a `Timify::Trace` that keeps both the block's value and the timer. Options are the same keyword args as `Timify.new`. If the block raises, the exception propagates and no `Trace` is returned.
 
 ```ruby
-t=Timify.new :example
-t.add; run_sqls; t.add :database
-t.add
-#some processes
-t.add
-#some processes
-send_email_alert(t.totals[:message]) if t.add > 0.2
-#some processes
-do_log(t.totals[:message]) if t.add > 0.5
+trace = Timify.trace(:create_user, show: false) do |timer|
+  timer.measure(:database) { :saved }
+end
+
+trace.value  # => :saved
+trace.timer  # => the Timify instance
+trace.totals # => same as trace.timer.totals
 ```
 
-### totals
+`Timify.measure`, `Timify.trace`, and instance `measure` raise `ArgumentError` when no block is given.
 
-Returns all data for this instance
+### Reuse a named timer
 
-In case json parameter supplied as true, the output will be in json format instead of a hash.
+`Timify[:name]` returns a quiet process-wide timer (`show: false` on first create) so two distant call sites can contribute to the same report. `Timify.clear!` drops that registry.
 
-The output hash contains:
+```ruby
+def load_row
+  Timify[:create_user].measure(:database) { :row }
+end
+
+def send_mail
+  Timify[:create_user].add(:mail)
+end
+
+load_row
+send_mail
+Timify[:create_user].totals
+Timify.clear!
+```
 
-    name: (String) name given for this instance'
+### Pause recording
 
-    total_time: (float) total elapsed time from initialization to last 'add' call
+`status` is `:on` by default. Set it to `:off` to pause, and back to `:on` to resume. Paused time is not charged to the next segment. The block still runs. `totals` still returns what was recorded before the pause.
 
-    started: (Time)
+```ruby
+timer = Timify.new(:create_user, show: false)
+timer.add(:setup)
 
-    finished: (Time)
+timer.status = :off
+result = timer.measure(:skipped) { :still_runs } # => :still_runs, nothing recorded
+timer.add(:also_skipped)                         # => 0.0
 
-    message: (String) a printable friendly message giving all information
+timer.status = :on
+timer.add(:mail) # charges only time since resume, not the pause
+```
 
-    locations, labels, ranges: (Hash) the resultant hash contains:
+### Turn Timify off for the whole process
 
-        secs: (float) number of seconds
+`Timify.enabled` is a process-wide switch. When it is `false`, every timer is a no-op: `add` returns `0.0` and records nothing, `measure` still runs its block and returns the value but records nothing and does not print, and `new` skips the init line. `totals` still returns whatever was recorded before the switch. `Timify.enabled?` returns the current flag.
 
-        percent: (integer) percentage in reference to the total time
+The default comes from the environment variable `TIMIFY_DISABLE` when the class loads. Values `1`, `true`, and `on` (case insensitive) disable recording. Setting `Timify.enabled = true` afterwards overrides the env var for the rest of the process. The default is `true` when the variable is unset.
 
-        count: (integer) number of times
+```ruby
+# shell: TIMIFY_DISABLE=1 bundle exec ruby app.rb
+# or in Ruby, after the gem has loaded:
+Timify.enabled = false
+timer = Timify.new(:create_user)              # no init line
+timer.measure(:database) { :saved }           # => :saved, nothing recorded
+timer.totals                                  # empty report
+
+Timify.enabled = true
+timer.add(:mail)                              # recording resumes
+```
 
-    locations: (Hash) All summary data by location where was called
+### React to slow or dominant spans
 
-    labels: (Hash) All summary data by label given on 'add' method
+`on_slow` registers a callback that runs when a segment is at least the given number of seconds long. For `add`, the segment length is compared. For `measure`, the block's inclusive time is compared. Several callbacks can be registered. They run after the segment is recorded, outside the timer mutex.
 
-    ranges: (Hash) All summary data by ranges where was called, from last 'add' call to current 'add' call
+```ruby
+timer = Timify.new(:create_user, show: false)
+timer.on_slow(0.5) do |event|
+  warn "#{event.name} #{event.label} took #{event.inclusive}s at #{event.location}"
+end
+
+timer.measure(:database) { :row }
+```
+
+`on_share` registers a callback that runs when a child span's inclusive time is at least `ratio` of the parent's elapsed time so far (`ratio` is a Float from `0` to `1` inclusive). It fires for labeled `measure` and `add` children, not for root spans or unlabeled gap spans. Parent elapsed is the time from the parent's start to this moment, so a child that already dominates the parent so far still fires even though the parent has not closed. Several callbacks can be registered and are kept across `reset`, same as `on_slow`. They run outside the timer mutex.
 
+The event is a `Timify::Event` with the usual fields plus `share` (Float) and `parent_label`. For `on_slow` events those two fields are `nil`.
 
-Example of output:
 ```ruby
-{  :name=>:add_customer_wrong, 
-   :total_time=>4.461446, 
-   :started=>2017-11-06 16:10:53 +0000, 
-   :finished=>2017-11-06 16:10:57 +0000, 
-   :locations=>{
-      "/add_customer.rb:509"=>{:secs=>0.0, :percent=>0, :count=>1}, 
-	  "/add_customer.rb:529"=>{:secs=>0.008001, :percent=>0, :count=>1}, 
-	  "/add_customer.rb:532"=>{:secs=>0.212021, :percent=>5, :count=>1}, 
-	  "/add_customer.rb:569"=>{:secs=>0.006001, :percent=>0, :count=>1}, 
-	  "/add_customer.rb:581"=>{:secs=>0.446045, :percent=>10, :count=>1}, 
-	  "/add_customer.rb:583"=>{:secs=>3.789378, :percent=>85, :count=>1}, 
-	  "/add_customer.rb:585"=>{:secs=>0.0, :percent=>0, :count=>1}, 
-	  "/add_customer.rb:587"=>{:secs=>0.0, :percent=>0, :count=>1}, 
-	  "/add_customer.rb:595"=>{:secs=>0.0, :percent=>0, :count=>1}, 
-	  "/add_customer.rb:603"=>{:secs=>0.0, :percent=>0, :count=>1}, 
-	  "/add_customer.rb:612"=>{:secs=>0.0, :percent=>0, :count=>1}, 
-	  "/add_customer.rb:617"=>{:secs=>0.0, :percent=>0, :count=>1}
-	}, 
-	:labels=>{
-		:database_access=>{:secs=>4,447444, :percent=>99, :count=>3},
-		:checkouts=>{:secs=>0.0, :percent=>0, :count=>2},
-	}, 
-	:ranges=>{
-	  "/add_customer.rb:509 - /add_customer.rb:529"=>{:secs=>0.008001, :percent=>0, :count=>1}, 
-	  "/add_customer.rb:529 - /add_customer.rb:532"=>{:secs=>0.212021, :percent=>5, :count=>1}, 
-	  "/add_customer.rb:532 - /add_customer.rb:569"=>{:secs=>0.006001, :percent=>0, :count=>1}, 
-	  "/add_customer.rb:569 - /add_customer.rb:581"=>{:secs=>0.446045, :percent=>10, :count=>1}, 
-	  "/add_customer.rb:581 - /add_customer.rb:583"=>{:secs=>3.789378, :percent=>85, :count=>1}, 
-	  "/add_customer.rb:583 - /add_customer.rb:585"=>{:secs=>0.0, :percent=>0, :count=>1}, 
-	  "/add_customer.rb:585 - /add_customer.rb:587"=>{:secs=>0.0, :percent=>0, :count=>1}, 
-	  "/add_customer.rb:587 - /add_customer.rb:595"=>{:secs=>0.0, :percent=>0, :count=>1}, 
-	  "/add_customer.rb:595 - /add_customer.rb:603"=>{:secs=>0.0, :percent=>0, :count=>1}, 
-	  "/add_customer.rb:603 - /add_customer.rb:612"=>{:secs=>0.0, :percent=>0, :count=>1}, 
-	  "/add_customer.rb:612 - /add_customer.rb:617"=>{:secs=>0.0, :percent=>0, :count=>1}
-	}, 
-	:message=>"
-	
-		Total time <add_customer_wrong>:4.46
-		Total time by location:
-			/add_customer.rb:509: 0.0 (0%) #1
-			/add_customer.rb:529: 0.01 (0%) #1
-			/add_customer.rb:532: 0.21 (5%) #1
-			/add_customer.rb:569: 0.01 (0%) #1
-			/add_customer.rb:581: 0.45 (10%) #1
-			/add_customer.rb:583: 3.79 (85%) #1
-			/add_customer.rb:585: 0.0 (0%) #1
-			/add_customer.rb:587: 0.0 (0%) #1
-			/add_customer.rb:595: 0.0 (0%) #1
-			/add_customer.rb:603: 0.0 (0%) #1
-			/add_customer.rb:612: 0.0 (0%) #1
-			/add_customer.rb:617: 0.0 (0%) #1
-		Total time by label:
-			database_access: 4.45 (99%) #3
-			checkouts: 0.0 (0%) #2
-		Total time by range:
-			/add_customer.rb:509 - /add_customer.rb:529: 0.01 (0%) #1
-			/add_customer.rb:529 - /add_customer.rb:532: 0.21 (5%) #1
-			/add_customer.rb:532 - /add_customer.rb:569: 0.01 (0%) #1
-			/add_customer.rb:569 - /add_customer.rb:581: 0.45 (10%) #1
-			/add_customer.rb:581 - /add_customer.rb:583: 3.79 (85%) #1
-			/add_customer.rb:583 - /add_customer.rb:585: 0.0 (0%) #1
-			/add_customer.rb:585 - /add_customer.rb:587: 0.0 (0%) #1
-			/add_customer.rb:587 - /add_customer.rb:595: 0.0 (0%) #1
-			/add_customer.rb:595 - /add_customer.rb:603: 0.0 (0%) #1
-			/add_customer.rb:603 - /add_customer.rb:612: 0.0 (0%) #1
-			/add_customer.rb:612 - /add_customer.rb:617: 0.0 (0%) #1
-	"
-}
+timer = Timify.new(:create_user, show: false)
+timer.on_share(0.5) do |event|
+  warn "#{event.label} took #{(event.share * 100).round}% of #{event.parent_label}"
+end
+
+# Parent opens at 0, database closes at 0.8, parent closes at 1.0 → share 0.8, fires.
+timer.measure(:request) do
+  timer.measure(:database) { :row }
+end
 ```
 
+### Read the report with `totals`
 
-## Contributing
+`totals` returns a Hash. `secs` is self time (what this span or bucket spent itself). `inclusive` is wall time covered by that span including children. Flat sections (`locations`, `labels`, `ranges`) are ordered slowest-first by self time.
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/marioruiz/timify.
+`totals(group: true)` also prints a `Grouped spans:` section after the chronological Spans section; the default `group: false` does not. `grouped_tree` is always in the hash either way: sibling nodes with the same label are merged recursively (sums `secs` and `inclusive`, sets `count`, keeps the first location, groups children the same way). Nil labels (gaps) merge with other nil labels. Order of first appearance is preserved.
 
+`totals(json: true)` returns the same report as a JSON string and still prints the summary when `show` is true. In JSON, hash keys and a symbol `name` are strings, and `started` and `finished` are time strings.
 
-## License
+The hash contains:
+
+* `name` — the name passed to `new`
+* `total_time` — sum of self time recorded so far, excluding paused time. Parallel threads can make this larger than `wall_time`.
+* `wall_time` — monotonic time from the start to the latest mark, minus pauses
+* `started` — wall-clock `Time` when the timer was created or last reset
+* `finished` — wall-clock `Time` of the latest recorded segment. It equals `started` until the first segment.
+* `tree` — chronological top-level spans. Each node has `label`, `location`, `secs`, `inclusive`, and `children`.
+* `grouped_tree` — merged sibling labels as described above
+* `message` — the printable summary
+* `locations` — one entry for each relative (or absolute) `path:line in method` where `add` or `measure` was called
+* `labels` — one entry for each label
+* `ranges` — one entry for each jump from one call site to the next. A `measure` block is not itself a range; the approach up to that call is, once a previous call site exists.
 
-The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+Each of `locations`, `labels`, and `ranges` contains `secs`, `inclusive`, `percent`, `count`, `min`, `max`, `avg`, `p50`, `p95`, `p99`, and optionally `samples_truncated` when more than 10_000 samples were seen for that bucket.
+
+Elapsed time uses a monotonic clock. `started` and `finished` stay wall-clock times. Each thread keeps its own cursor and span stack; shared totals are updated under a mutex.
+
+After two `add` calls that took 1.0 seconds and then 0.5 seconds:
+
+```ruby
+report = timer.totals
+report[:total_time]  # => 1.5
+report[:labels].keys # => ["database", "mail"]  (slowest first)
+report[:labels]["database"] # => { secs: 1.0, inclusive: 1.0, percent: 67, count: 1, ... }
+```
+
+`message` is the text `totals` prints when `show` is true:
+
+```text
+Total time <create_user>:1.5 wall 1.5
+Spans:
+	database inclusive 1.0 self 1.0
+	mail inclusive 0.5 self 0.5
+Total time by location:
+	app/create_user.rb:10 in create: 1.0 (67%) #1 min 1.0 max 1.0 avg 1.0 p95 1.0
+	app/create_user.rb:20 in create: 0.5 (33%) #1 min 0.5 max 0.5 avg 0.5 p95 0.5
+
+Total time by label:
+	database: 1.0 (67%) #1 min 1.0 max 1.0 avg 1.0 p95 1.0
+	mail: 0.5 (33%) #1 min 0.5 max 0.5 avg 0.5 p95 0.5
+
+Total time by range:
+	app/create_user.rb:10 in create - app/create_user.rb:20 in create: 0.5 (33%) #1 min 0.5 max 0.5 avg 0.5 p95 0.5
+```
+
+When inclusive time differs from self time, bucket lines append ` inclusive N`.
+
+Two sibling `measure(:database)` calls that took 0.3 seconds and 0.2 seconds keep two nodes in `tree` and one merged node in `grouped_tree`:
+
+```ruby
+report = timer.totals(group: true)
+report[:tree].size            # => 2
+report[:grouped_tree].first   # => { label: "database", ..., secs: 0.5, inclusive: 0.5, count: 2, children: [] }
+# message includes "Grouped spans:" then "database inclusive 0.5 self 0.5 #2"
+
+json = timer.totals(json: true) # => JSON string of the same report
+```
+
+### Start over with `reset`
+
+`reset` drops every recorded segment and starts the clock again. The name, `show`, `min_time_to_show`, `output`, `on_slow`, and `on_share` callbacks stay as they are. A paused timer is left running.
+
+```ruby
+timer = Timify.new(:create_user, show: false)
+timer.add(:database)
+timer.reset
+timer.totals[:total_time] # => 0.0
+timer.add(:mail)          # new clock from reset
+```
+
+## Development
+
+```sh
+bundle install
+bundle exec rake
+bundle exec yard
+```
+
+`rake` runs the RSpec suite. Development dependencies are Rake, RSpec, and YARD. CI runs that suite on Ruby 3.2, 3.3, 3.4, and 4.0.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/MarioRuiz/timify.
+
+## License
 
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).