Safe Haskell	Safe-Inferred

Profiling.Heap.Types

Contents

Profile data structure
Query interface
Streaming interface

Description

This module defines the commonly used data structures and basic types of the heap profiling framework.

Profiling information is a sequence of time-stamped samples, therefore the ideal data structure should have an efficient snoc operation. Also, it should make it easy to extract an interval given by a start and an end time. On top of the raw data, we also want to access some statistics as efficiently as possible.

We can separate two phases: looking at the profile during execution and later. In the first case we might not want statistics, just live monitoring, while we probably want to analyse archived profiles more deeply. Therefore, it makes sense to define two separate data structures for these two purposes, and give them a common interface for extracting the necessary data. The simple case is covered by the Profile type defined here, while a more complex structure providing fast off-line queries is defined in the Profiling.Heap.Stats module.

Synopsis

Documentation

type CostCentreId = Int Source

Cost centres are identified by integers for simplicity (so we can use IntMap).

type CostCentreName = ByteString Source

At this level cost centre names have no internal structure that we would care about. While in some cases they reflect the call hierarchy, we are not splitting them at this point, because all kinds of names can appear here.

type Time = Double Source

Time is measured in seconds.

type Cost = Int64 Source

Costs are measured in bytes.

type ProfileSample = [(CostCentreId, Cost)]Source

A sampling point is simply a list of cost centres with the associated cost. There is no need for a fancy data structure here, since we normally process every value in this collection, and it's usually not big either, only holding a few dozen entries at most.

Profile data structure

data Profile Source

A raw heap profile that's easy to grow further, therefore it is used during loading.

Constructors

Profile
Fields prSamples :: ![(Time, ProfileSample)] Samples in decreasing time order (latest first). prNames :: !(IntMap CostCentreName) A map from cost centre ids to names. prNamesInv :: !(Trie CostCentreId) A map from cost centre names to ids. prJob :: !String Information about the job (command line). prDate :: !String Job start time and date.

Instances

Eq Profile
Show Profile
ProfileQuery Profile

emptyProfile :: Profile Source

An initial Profile structure that can be used in accumulations.

Query interface

class ProfileQuery p whereSource

The ProfileQuery class contains all kinds of reading operations. The minimal definition consists of job, date, ccNames and samples. All the statistics have default implementations, which are mostly okay for a single query, but they are generally highly inefficient.

Methods

job :: p -> String Source

Job information (command line).

date :: p -> String Source

Job start time.

ccNames :: p -> IntMap CostCentreName Source

Cost centre id to name mapping.

ccName :: p -> Int -> CostCentreName Source

Find cost centre name by id.

samples :: p -> [(Time, ProfileSample)]Source

The measurements in a list ordered by time.

samplesIvl :: p -> Time -> Time -> [(Time, ProfileSample)]Source

The samples between two given times.

minTime :: p -> Time Source

The time of the first sample.

maxTime :: p -> Time Source

The time of the last sample.

maxCost :: p -> Cost Source

The highest individual cost at any time.

maxCostTotal :: p -> Cost Source

The highest total cost at any time.

maxCostIvl :: p -> Time -> Time -> Cost Source

The highest individual cost in the interval.

maxCostTotalIvl :: p -> Time -> Time -> Cost Source

The highest total cost in the interval.

integral :: p -> ProfileSample Source

The total cost of each cost centre. Not a time integral; samples are simply summed.

integralIvl :: p -> Time -> Time -> ProfileSample Source

The total cost of each cost centre in the interval.

Instances

ProfileQuery Profile
ProfileQuery ProfileWithStats

Streaming interface

type ProfileSink = SinkInput -> IO ()Source

We might not want to hold on to all the past output, just do some stream processing. We can achieve this using a callback function that's invoked whenever a new profile sample is available. The type of this function can be ProfileSink. Besides the actual costs, it is also necessary to send over the names that belong to the short cost centre identifiers as well as the fact that no more data will come. The SinkInput type expresses these possibilities.

data SinkInput Source

Constructors

SinkSample !Time !ProfileSample	A snapshot of costs at a given time.
SinkId !CostCentreId !CostCentreName	The name behind a cost centre id used in the samples.
SinkStop	Indication that no more data will come.

Instances

Eq SinkInput
Show SinkInput