---
name: "Test2::Harness::Auditor::TimeTracker"
section: "3pm"
platform: "linux"
package: "libtest2-harness-perl"
version: "1.000158-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Test2::Harness::Auditor::TimeTracker"
---

# Test2::Harness::Auditor::TimeTracker(3pm)

Module that tracks timing data while an event stream is processed.

## NAME

Test2::Harness::Auditor::TimeTracker - Module that tracks timing data while an event stream is processed.

## DESCRIPTION

The timetracker module tracks timing data of an event stream. All events for a given job should be run through a timetracker, which can then give data on how long the test took in each of several stages.

- startup - Time from launch to first test event.

  - events - Time spent generating test events.

  - cleanup - Time from last test event to test exit.

  - total - Total time.

  ## SYNOPSIS

```
    use Test2::Harness::Auditor::TimeTracker;
    my $tracker = Test2::Harness::Auditor::TimeTracker->new();
    my $assert_count = 0;
    for my $event (@events) {
        my $facet_data = $events->facet_data;
        $assert_count++ if $facet_data->{assert};
        $tracker->process($event, $facet_data, $assert_count);
    }
    print $tracker->summary;
    # Startup: 0.00708s | Events: 0.00000s | Cleanup: 0.10390s | Total: 0.11098s
```

## METHODS

- $tracker-\>process($event, $facet\_data, $assert\_count)

  - $tracker-\>process($event, undef, $assert\_count)

  TimeTracker builds its state from multiple events, each event should be processed by this method.

  The second argument is optional, if no facet\_data is provided it will pull the facet\_data from the event itself. This is mainly a micro-optimization to avoid calling the `facet_data()` method on the event multiple times if you have already called it.

- $bool = $tracker-\>**useful()**

  Returns true if there is any useful data to display.

- $totals = $tracker-\>**totals()**

  Returns the totals like this:

  ```
      {
          # Raw numbers
          startup => ...,
          events  => ...,
          cleanup => ...,
          total   => ...,
          # Human friendly versions
          h_startup => ...,
          h_events  => ...,
          h_cleanup => ...,
          h_total   => ...,
      }
  ```

- $source = $tracker-\>**source()**

  This method returns the data from which the totals are derived.

  ```
      {
          start => ...,    # timestamp of the job starting
          stop  => ...,    # timestamp of the job ending
          first => ...,    # timestamp of the first non-harness event
          last  => ...,    # timestamp of the last non-harness event
          # These are event_id's of the events that provided the above stamps.
          start_id    => ...,
          stop_id     => ...,
          first_id    => ...,
          last_id     => ...,
          complete_id => ...,
      }
  ```

- $data = $tracker-\>data\_dump

  This dumps the totals and source data:

  ```
      {
          totals => $tracker->totals,
          source => $tracker->source,
      }
  ```

- $string = $tracker-\>summary

  This produces a summary string of the totals data:

  ```
      Startup: 0.00708s | Events: 0.00000s | Cleanup: 0.10390s | Total: 0.11098s
  ```

  Fields that have no data will be ommited from the string.

- $table = $tracker-\>table

  Returns this structure that is good for use in Term::Table.

  ```
      {
          header => ["Phase", "Time", "Raw", "Explanation"],
          rows   => [
              ['startup', $human_readible, $raw, "Time from launch to first test event."],
              ['events',  $human_radible,  $raw, 'Time spent generating test events.'],
              ['cleanup', $human_radible,  $raw, 'Time from last test event to test exit.'],
              ['total',   $human_radible,  $raw, 'Total time.'],
          ],
      }
  ```

- @items = $tracker-\>**job\_fields()**

  This is used to obtain extra data to attach to the job completion event.

## SOURCE

The source code repository for Test2-Harness can be found at *http://github.com/Test-More/Test2-Harness/*.

## MAINTAINERS

- Chad Granum \<exodist@cpan.org\>

  ## AUTHORS

- Chad Granum \<exodist@cpan.org\>

  ## COPYRIGHT

Copyright 2020 Chad Granum \<exodist7@gmail.com\>.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See *http://dev.perl.org/licenses/*