DBI::ProfileData - manipulate DBI::ProfileDumper data dumps

- NAME
- SYNOPSIS
- DESCRIPTION
- METHODS
- AUTHOR
- COPYRIGHT AND LICENSE

# NAME

DBI::ProfileData - manipulate DBI::ProfileDumper data dumps

# SYNOPSIS

The easiest way to use this module is through the dbiprof frontend (see dbiprof for details):

      dbiprof --number 15 --sort count

This module can also be used to roll your own profile analysis:

      # load data from dbi.prof
      $prof = DBI::ProfileData->new(File => "dbi.prof");

      # get a count of the records in the data set
      $count = $prof->count();

      # sort by longest overall time
      $prof->sort(field => "longest");

      # sort by longest overall time, least to greatest
      $prof->sort(field => "longest", reverse => 1);

      # exclude records with key2 eq 'disconnect'
      $prof->exclude(key2 => 'disconnect');

      # exclude records with key1 matching /^UPDATE/i
      $prof->exclude(key1 => qr/^UPDATE/i);

      # remove all records except those where key1 matches /^SELECT/i
      $prof->match(key1 => qr/^SELECT/i);

      # produce a formatted report with the given number of items
      $report = $prof->report(number => 10);

      # clone the profile data set
      $clone = $prof->clone();

      # get access to hash of header values
      $header = $prof->header();

      # get access to sorted array of nodes
      $nodes = $prof->nodes();

      # format a single node in the same style as report()
      $text = $prof->format($nodes->[0]);

      # get access to Data hash in DBI::Profile format
      $Data = $prof->Data();

# DESCRIPTION

This module offers the ability to read, manipulate and format DBI::ProfileDumper profile data.

Conceptually, a profile consists of a series of records, or nodes, each of each has a set of statistics and set of keys. Each record must have a unique set of keys, but there is no requirement that every record have the same number of keys.

# METHODS

The following methods are supported by DBI::ProfileData objects.

$prof = DBI::ProfileData->new(File => ``dbi.prof'')
$prof = DBI::ProfileData->new(Files => [ ``dbi.prof.1'', ``dbi.prof.2'' ])
  Creates a a new DBI::ProfileData object. Takes either a single file through the File option or a list of Files in an array ref. If multiple files are specified then the header data from the first file is used.

$copy = $prof->clone();
  Clone a profile data set creating a new object.

$header = $prof->header();
  Returns a reference to a hash of header values. These are the key value pairs included in the header section of the DBI::ProfileDumper data format. For example:

        $header = {
                    Path    => '[ DBIprofile_Statement, DBIprofile_MethodName ]',
                    Program => 't/42profile_data.t',
                  };

  Note that modifying this hash will modify the header data stored inside the profile object.

$nodes = $prof->`nodes()`
  Returns a reference the sorted nodes array. Each element in the array is a single record in the data set. The first seven elements are the same as the elements provided by DBI::Profile. After that each key is in a separate element. For example:

       $nodes = [
                  [
                    2,                      # 0, count
                    0.0312958955764771,     # 1, total duration
                    0.000490069389343262,   # 2, first duration
                    0.000176072120666504,   # 3, shortest duration
                    0.00140702724456787,    # 4, longest duration
                    1023115819.83019,       # 5, time of first event
                    1023115819.86576,       # 6, time of last event
                    'SELECT foo FROM bar'   # 7, key1
                    'execute'               # 8, key2
                                            # 6+N, keyN
                  ],
                                            # ...
                ];

  Note that modifying this array will modify the node data stored inside the profile object.

$count = $prof->`count()`
  Returns the number of items in the profile data set.

$prof->sort(field => ``field'')
$prof->sort(field => ``field'', reverse => 1)
  Sorts data by the given field. Available fields are:

        longest
        total
        count
        shortest

  The default sort is greatest to smallest, which is the opposite of the normal Perl meaning. This, however, matches the expected behavior of the dbiprof frontend.

$count = $prof->exclude(key2 => ``disconnect'')
$count = $prof->exclude(key2 => ``disconnect'', case_sensitive => 1)
$count = $prof->exclude(key1 => qr/^SELECT/i)
  Removes records from the data set that match the given string or regular expression. This method modifies the data in a permanent fashion - use `clone()` first to maintain the original data after exclude(). Returns the number of nodes left in the profile data set.

$count = $prof->match(key2 => ``disconnect'')
$count = $prof->match(key2 => ``disconnect'', case_sensitive => 1)
$count = $prof->match(key1 => qr/^SELECT/i)
  Removes records from the data set that do not match the given string or regular expression. This method modifies the data in a permanent fashion - use `clone()` first to maintain the original data after match(). Returns the number of nodes left in the profile data set.

$Data = $prof->`Data()`
  Returns the same Data hash structure as seen in DBI::Profile. This structure is not sorted. The `nodes()` structure probably makes more sense for most analysis.

$text = $prof->format($nodes->[0])
  Formats a single node into a human-readable block of text.

$text = $prof->report(number => 10)
  Produces a report with the given number of items.

# AUTHOR

Sam Tregar <sam@tregar.com>

# COPYRIGHT AND LICENSE

Copyright (C) 2002 Sam Tregar

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

DBI::ProfileData - manipulate DBI::ProfileDumper data dumps