NAME

DashProfiler::UserGuide - a user guide for the DashProfiler modules

INTRODUCTION

The DashProfiler modules provide an efficient, simple, flexible, and powerful way to collect aggregate timing (performance) information for your code.

CONCEPTS

DashProfiler::Core

The core of DashProfiler are DashProfiler::Core objects, naturally.

                         DashProfiler::Core

DashProfiler

The DashProfiler module provides a by-name interface to DashProfiler::Core objects to avoid needing to manage object references yourself. Most DashProfiler::Core instance methods have corresponding DashProfiler static methods that take a profiler name as the first argument.

                             DashProfiler
                                  |
                                  v
                         DashProfiler::Core

DBI::Profile

Behind the scenes, DashProfiler::Core uses DBI::Profile to efficiently aggregate timing samples.

                             DashProfiler
                                  |
                                  v
                         DashProfiler::Core  -->  DBI::Profile

DBI::Profile aggregates timing samples into a tree structure.

By default DashProfiler::Core arranges for the samples to be aggregated into a tree with two levels. We refer to these as context1 and context2.

You provide values for these that make the most sense for you and your application. For example, context1 might a type of network service and context2 might be the specific host name being used to provide that service.

DashProfiler::Sample

To add timing samples you need to use a Sampler. A Sampler is a code reference that when called creates a new DashProfiler::Sample object and returns a reference to it. Samplers are factories for creating samples. The Sampler code reference is customized (curried) to contain the value for context1 to be used for the created DashProfiler::Sample.

Samplers are created using the prepare() method of DashProfiler::Core or DashProfiler (which is just a by-name wrapper for DashProfiler::Core).

                             DashProfiler
                                  |
                                  v
           .-----------  DashProfiler::Core  -->  DBI::Profile
           v                      ^
  sampler code ref -.             |
  sampler code ref ---> DashProfiler::Sample
  sampler code ref -'

Each time you call the Sampler code reference you pass it a value for context2 to be used for this sample and it returns a new DashProfiler::Sample object containing the relevant information, including the exact time it was created.

When that DashProfiler::Sample object is destroyed, typically by going out of scope, it adds a timing sample to all the DBI::Profile objects attached to the Core it's associated with. The timing is from object creation to object destruction.

DashProfiler::Import

The DashProfiler::Import module lets you create and import customized Sampler code references at load-time as if they were ordinary functions.

 DashProfiler::Import  <---  DashProfiler
         |                        |
         |                        |
         |                        v
         |               DashProfiler::Core  -->  DBI::Profile
         v                        ^
  sampler function -.             |
  sampler function ---> DashProfiler::Sample
  sampler function -'

DashProfiler::Auto

The DashProfiler::Auto module gives you a simple way to start using DashProfiler. It creates a DashProfiler called 'auto' with a useful default configuration. It also uses DashProfiler::Import to import an auto_profiler() sampler function pre-configured with the name of the source file it's imported into.

Where next?

Experimenting with DashProfiler::Auto is a good place to start.