-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Read files generated by perf on Linux -- -- This library is for parsing, representing in Haskell and pretty -- printing the data file output of the Linux perf command. The -- perf command provides performance profiling information for -- applications running under the Linux operating system. This -- information includes hardware performance counters and kernel -- tracepoints. -- -- Modern CPUs can provide information about the runtime behaviour of -- software through so-called hardware performance counters -- http://en.wikipedia.org/wiki/Hardware_performance_counter. -- Recent versions of the Linux kernel (since 2.6.31) provide a generic -- interface to low-level events for running processes. This includes -- access to hardware counters but also a wide array of software events -- such as page faults, scheduling activity and system calls. A userspace -- tool called perf is built on top of the kernel interface, which -- provides a convenient way to record and view events for running -- processes. -- -- The perf tool has many sub-commands which do a variety of -- things, but in general it has two main purposes: -- --
    --
  1. Recording events.
    2. --
  2. Displaying events.
    3. --
-- -- The perf record command records information about performance -- events in a file called (by default) perf.data. It is a -- binary file format which is basically a memory dump of the data -- structures used to record event information. The file has two main -- parts: -- --
    --
  1. A header which describes the layout of information in the file -- (section sizes, etcetera) and common information about events in the -- second part of the file (an encoding of event types and their -- names).
    2. --
  2. The payload of the file which is a sequence of event records.
    3. --
-- -- Each event field has a header which says what general type of event it -- is plus information about the size of its body. -- -- There are nine types of event: -- --
    --
  1. PERF_RECORD_MMAP: memory map event.
    2. --
  2. PERF_RECORD_LOST: an unknown event.
    3. --
  3. PERF_RECORD_COMM: maps a command name string to a process -- and thread ID.
    4. --
  4. PERF_RECORD_EXIT: process exit.
    5. --
  5. PERF_RECORD_THROTTLE:
    6. --
  6. PERF_RECORD_UNTHROTTLE:
    7. --
  7. PERF_RECORD_FORK: process creation.
    8. --
  8. PERF_RECORD_READ:
    9. --
  9. PERF_RECORD_SAMPLE: a sample of an actual hardware -- counter or a software event.
    10. --
-- -- The PERF_RECORD_SAMPLE events (samples) are the most -- interesting ones in terms of program profiling. The other events seem -- to be mostly useful for keeping track of process technicalities. -- Samples are timestamped with an unsigned 64 bit word, which records -- elapsed nanoseconds since some point in time (system running time, -- based on the kernel scheduler clock). Samples have themselves a type -- which is defined in the file header and linked to the sample by an -- integer identifier. -- -- Below is an example program which reads a perf.data file and -- prints out the number of events that it contains. -- -- 
--   module Main where
--   
--   import Profiling.Linux.Perf (readPerfData)
--   import Profiling.Linux.Perf.Types (PerfData (..))
--   import System.Environment (getArgs)
--   
--   main :: IO ()
--   main = do
--      args <- getArgs
--      case args of
--         [] -> return ()
--         (file:_) -> do
--            perfData <- readPerfData file
--            print $ length $ perfData_events perfData
--
@package linux-perf @version 0.3 -- | Pretty printing utilities. module Profiling.Linux.Perf.Pretty -- | Pretty printing interface. class Pretty a pretty :: Pretty a => a -> Doc -- | Render an instance of Pretty as a String. prettyString :: Pretty a => a -> String -- | Render an instance of Bits as a String. showBits :: Bits a => a -> String instance Pretty ByteString instance (Pretty a, Pretty b) => Pretty (a, b) instance Pretty Word64 instance Pretty Word32 instance Pretty Word16 instance Pretty Word8 instance Pretty a => Pretty (Maybe a) -- | Types for representing the parsed contents of a perf.data -- file output the perf record command on Linux (Linux -- performance counter information). -- -- There is an intentional close correspondence between the types in this -- module and the representation in the C implementation of perf. module Profiling.Linux.Perf.Types -- | Process ID. newtype PID PID :: Word32 -> PID pid :: PID -> Word32 -- | Thread ID. newtype TID TID :: Word32 -> TID tid :: TID -> Word32 -- | Event ID. Not really an identity. This number is used to link an event -- to an event type. Multiple events can have the same EventID, which -- means they all have the same event type. newtype EventID EventID :: Word64 -> EventID eventID :: EventID -> Word64 -- | Event type ID (magic unique number of an event type). newtype EventTypeID EventTypeID :: Word64 -> EventTypeID eventTypeID :: EventTypeID -> Word64 -- | A 64 bit measurement in bytes. For example the size of an object, or -- an offset. newtype ByteCount64 ByteCount64 :: Word64 -> ByteCount64 byteCount64 :: ByteCount64 -> Word64 -- | A 32 bit measurement in bytes. For example the size of an object, or -- an offset. newtype ByteCount32 ByteCount32 :: Word32 -> ByteCount32 byteCount32 :: ByteCount32 -> Word32 -- | A 16 bit measurement in bytes. For example the size of an object, or -- an offset. newtype ByteCount16 ByteCount16 :: Word16 -> ByteCount16 byteCount16 :: ByteCount16 -> Word16 -- | Measurement of time passed in nanoseconds since a given point. newtype TimeStamp TimeStamp :: Word64 -> TimeStamp timeStamp :: TimeStamp -> Word64 -- | Corresponds with the perf_file_section struct in <perf -- source>/util/header.h data FileSection FileSection :: ByteCount64 -> ByteCount64 -> FileSection -- | File offset to the section. sec_offset :: FileSection -> ByteCount64 -- | Size of the section in bytes. sec_size :: FileSection -> ByteCount64 -- | Corresponds with the perf_file_header struct in <perf -- source>/util/header.h data FileHeader FileHeader :: ByteCount64 -> ByteCount64 -> ByteCount64 -> ByteCount64 -> ByteCount64 -> ByteCount64 -> ByteCount64 -> ByteCount64 -> [Word32] -> FileHeader -- | Size of (this) header. fh_size :: FileHeader -> ByteCount64 -- | Size of one attribute section. fh_attr_size :: FileHeader -> ByteCount64 -- | File offset to the attribute section. fh_attrs_offset :: FileHeader -> ByteCount64 -- | Size of the attribute section in bytes. fh_attrs_size :: FileHeader -> ByteCount64 -- | File offset to the data section. fh_data_offset :: FileHeader -> ByteCount64 -- | Size of the data section in bytes. fh_data_size :: FileHeader -> ByteCount64 -- | File offset to the event section. fh_event_offset :: FileHeader -> ByteCount64 -- | Size of the event section in bytes. fh_event_size :: FileHeader -> ByteCount64 -- | Bitfield. fh_adds_features :: FileHeader -> [Word32] -- | Layout of event attribute and attribute ids. data FileAttr FileAttr :: EventAttr -> ByteCount64 -> ByteCount64 -> FileAttr -- | The attribute payload. fa_attr :: FileAttr -> EventAttr -- | File offset to the ids section. fa_ids_offset :: FileAttr -> ByteCount64 -- | Size of the ids section in bytes. fa_ids_size :: FileAttr -> ByteCount64 -- | A Single event record. data Event Event :: EventHeader -> EventPayload -> Event -- | Information about the structure of the event. ev_header :: Event -> EventHeader -- | The event data. ev_payload :: Event -> EventPayload -- | A bitfield in perf_event_header->misc. data EventCPUMode -- | 0 PERF_RECORD_CPUMODE_UNKNOWN :: EventCPUMode -- | 1 PERF_RECORD_MISC_KERNEL :: EventCPUMode -- | 2 PERF_RECORD_MISC_USER :: EventCPUMode -- | 3 PERF_RECORD_MISC_HYPERVISOR :: EventCPUMode -- | Corresponds with the perf_event_attr struct in -- include/linux/perf_event.h data EventAttr EventAttr :: EventSource -> ByteCount32 -> EventTypeID -> Word64 -> SampleTypeBitMap -> Word64 -> Word64 -> Word32 -> Word32 -> Word64 -> Word64 -> EventAttr -- | Major type: hardwaresoftwaretracepoint/etc. defined as enum -- perf_type_id in includelinuxperf_event.h ea_type :: EventAttr -> EventSource -- | Size of the attr structure, for fwd/bwd compat. ea_size :: EventAttr -> ByteCount32 -- | Link to .event id of perf trace event type. ea_config :: EventAttr -> EventTypeID -- | Number of events when a sample is generated if .freq is not set or -- frequency for sampling if .freq is set. ea_sample_period_or_freq :: EventAttr -> Word64 -- | Information about what is stored in the sampling record. ea_sample_type :: EventAttr -> SampleTypeBitMap ea_read_format :: EventAttr -> Word64 ea_flags :: EventAttr -> Word64 -- | Wakeup every n events or bytes before wakeup. ea_wakeup_events_or_watermark :: EventAttr -> Word32 ea_bp_type :: EventAttr -> Word32 ea_bp_addr_or_config1 :: EventAttr -> Word64 ea_bp_len_or_config2 :: EventAttr -> Word64 -- | Corresponds with the perf_event_header struct in <perf -- source>/util/perf_event.h data EventHeader EventHeader :: EventType -> Word16 -> ByteCount16 -> EventHeader eh_type :: EventHeader -> EventType eh_misc :: EventHeader -> Word16 eh_size :: EventHeader -> ByteCount16 data EventPayload CommEvent :: PID -> TID -> ByteString -> EventPayload -- | process id eventPayload_pid :: EventPayload -> PID -- | thread id eventPayload_tid :: EventPayload -> TID -- | name of the application eventPayload_CommName :: EventPayload -> ByteString MmapEvent :: PID -> TID -> Word64 -> Word64 -> Word64 -> ByteString -> EventPayload -- | process id eventPayload_pid :: EventPayload -> PID -- | thread id eventPayload_tid :: EventPayload -> TID -- | start of memory range eventPayload_MmapStart :: EventPayload -> Word64 -- | size of memory range eventPayload_MmapLen :: EventPayload -> Word64 -- | page offset eventPayload_MmapPgoff :: EventPayload -> Word64 -- | binary file using this range eventPayload_MmapFilename :: EventPayload -> ByteString ForkEvent :: PID -> PID -> TID -> TID -> TimeStamp -> EventPayload -- | process id eventPayload_pid :: EventPayload -> PID -- | parent proecess id eventPayload_ppid :: EventPayload -> PID -- | thread id eventPayload_tid :: EventPayload -> TID -- | parent thread id eventPayload_ptid :: EventPayload -> TID -- | timestamp eventPayload_time :: EventPayload -> TimeStamp ExitEvent :: PID -> PID -> TID -> TID -> TimeStamp -> EventPayload -- | process id eventPayload_pid :: EventPayload -> PID -- | parent proecess id eventPayload_ppid :: EventPayload -> PID -- | thread id eventPayload_tid :: EventPayload -> TID -- | parent thread id eventPayload_ptid :: EventPayload -> TID -- | timestamp eventPayload_time :: EventPayload -> TimeStamp LostEvent :: EventID -> Word64 -> EventPayload eventPayload_id :: EventPayload -> EventID eventPayload_Lost :: EventPayload -> Word64 ReadEvent :: PID -> TID -> Word64 -> Word64 -> Word64 -> EventID -> EventPayload -- | process id eventPayload_pid :: EventPayload -> PID -- | thread id eventPayload_tid :: EventPayload -> TID eventPayload_ReadValue :: EventPayload -> Word64 eventPayload_ReadTimeEnabled :: EventPayload -> Word64 eventPayload_ReadTimeRunning :: EventPayload -> Word64 eventPayload_id :: EventPayload -> EventID SampleEvent :: Maybe Word64 -> Maybe PID -> Maybe TID -> Maybe TimeStamp -> Maybe Word64 -> Maybe EventID -> Maybe Word64 -> Maybe Word32 -> Maybe Word64 -> EventPayload -- | Instruction pointer. eventPayload_SampleIP :: EventPayload -> Maybe Word64 -- | Process ID. eventPayload_SamplePID :: EventPayload -> Maybe PID -- | Thread ID. eventPayload_SampleTID :: EventPayload -> Maybe TID -- | Timestamp. eventPayload_SampleTime :: EventPayload -> Maybe TimeStamp eventPayload_SampleAddr :: EventPayload -> Maybe Word64 -- | Event ID. eventPayload_SampleID :: EventPayload -> Maybe EventID eventPayload_SampleStreamID :: EventPayload -> Maybe Word64 -- | CPU ID. eventPayload_SampleCPU :: EventPayload -> Maybe Word32 -- | Duration of sample. eventPayload_SamplePeriod :: EventPayload -> Maybe Word64 ThrottleEvent :: TimeStamp -> EventID -> Word64 -> EventPayload -- | timestamp eventPayload_time :: EventPayload -> TimeStamp eventPayload_id :: EventPayload -> EventID eventPayload_stream_id :: EventPayload -> Word64 UnThrottleEvent :: TimeStamp -> EventID -> Word64 -> EventPayload -- | timestamp eventPayload_time :: EventPayload -> TimeStamp eventPayload_id :: EventPayload -> EventID eventPayload_stream_id :: EventPayload -> Word64 -- | An unrecognised event was encountered. UnknownEvent :: EventPayload -- | Encoding of the perf_event_header->type. data EventType PERF_RECORD_MMAP :: EventType PERF_RECORD_LOST :: EventType PERF_RECORD_COMM :: EventType PERF_RECORD_EXIT :: EventType PERF_RECORD_THROTTLE :: EventType PERF_RECORD_UNTHROTTLE :: EventType PERF_RECORD_FORK :: EventType PERF_RECORD_READ :: EventType PERF_RECORD_SAMPLE :: EventType PERF_RECORD_UNKNOWN :: Int -> EventType -- | Information about what is stored in a sample event. data SampleFormat -- | 1U << 0 PERF_SAMPLE_IP :: SampleFormat -- | 1U << 1 PERF_SAMPLE_TID :: SampleFormat -- | 1U << 2 PERF_SAMPLE_TIME :: SampleFormat -- | 1U << 3 PERF_SAMPLE_ADDR :: SampleFormat -- | 1U << 4 PERF_SAMPLE_READ :: SampleFormat -- | 1U << 5 PERF_SAMPLE_CALLCHAIN :: SampleFormat -- | 1U << 6 PERF_SAMPLE_ID :: SampleFormat -- | 1U << 7 PERF_SAMPLE_CPU :: SampleFormat -- | 1U << 8 PERF_SAMPLE_PERIOD :: SampleFormat -- | 1U << 9 PERF_SAMPLE_STREAM_ID :: SampleFormat -- | 1U << 10 PERF_SAMPLE_RAW :: SampleFormat -- | Identity and printable name of an event type. data TraceEventType TraceEventType :: EventTypeID -> ByteString -> TraceEventType -- | This entry belongs to the perf event attr entry where .config has the -- same value as this id. te_event_id :: TraceEventType -> EventTypeID te_name :: TraceEventType -> ByteString -- | See struct perf_event_attr in linux/perf_event.h data EventAttrFlag -- | off by default Disabled :: EventAttrFlag -- | children inherit it Inherit :: EventAttrFlag -- | must always be on PMU Pinned :: EventAttrFlag -- | only group on PMU Exclusive :: EventAttrFlag -- | don't count user ExcludeUser :: EventAttrFlag -- | ditto kernel ExcludeKernel :: EventAttrFlag -- | ditto hypervisor ExcludeHV :: EventAttrFlag -- | don't count when idle ExcludeIdle :: EventAttrFlag -- | include mmap data Mmap :: EventAttrFlag -- | include comm data Comm :: EventAttrFlag -- | use freq, not period Freq :: EventAttrFlag -- | per task counts InheritStat :: EventAttrFlag -- | next exec enables EnableOnExec :: EventAttrFlag -- | trace fork/exit Task :: EventAttrFlag -- | wakeup_watermark WaterMark :: EventAttrFlag -- | precise_ip, See also PERF_RECORD_MISC_EXACT_IP ArbitrarySkid :: EventAttrFlag -- | precise_ip, See also PERF_RECORD_MISC_EXACT_IP ConstantSkid :: EventAttrFlag -- | precise_ip, See also PERF_RECORD_MISC_EXACT_IP RequestedZeroSkid :: EventAttrFlag -- | precise_ip, See also PERF_RECORD_MISC_EXACT_IP CompulsoryZeroSkid :: EventAttrFlag -- | non-exec mmap data MmapData :: EventAttrFlag -- | sample_type all events SampleIdAll :: EventAttrFlag -- | Corresponds with the enum perf_type_id in -- include/linux/perf_event.h data EventSource -- | 0 PerfTypeHardware :: EventSource -- | 1 PerfTypeSoftware :: EventSource -- | 2 PerfTypeTracePoint :: EventSource -- | 3 PerfTypeHwCache :: EventSource -- | 4 PerfTypeRaw :: EventSource -- | 5 PerfTypeBreakpoint :: EventSource PerfTypeUnknown :: EventSource -- | A bitmap encoding information about the content of sample events. newtype SampleTypeBitMap SampleTypeBitMap :: Word64 -> SampleTypeBitMap sampleTypeBitMap :: SampleTypeBitMap -> Word64 -- | Test if a given EventAttrFlag is set. testEventAttrFlag :: Word64 -> EventAttrFlag -> Bool -- | The various parts of the perf.data file collected together. data PerfData PerfData :: FileHeader -> [FileAttr] -> [[EventID]] -> [TraceEventType] -> [Event] -> PerfData -- | File header explains the structure of the file. perfData_fileHeader :: PerfData -> FileHeader -- | Common attributes of events. perfData_attrs :: PerfData -> [FileAttr] -- | Event identifiers to be associated with the event attributes. perfData_idss :: PerfData -> [[EventID]] -- | Event type information. perfData_types :: PerfData -> [TraceEventType] -- | The event payload. perfData_events :: PerfData -> [Event] instance Eq PID instance Ord PID instance Show PID instance Pretty PID instance Eq TID instance Ord TID instance Show TID instance Pretty TID instance Eq EventTypeID instance Ord EventTypeID instance Show EventTypeID instance Pretty EventTypeID instance Eq EventID instance Ord EventID instance Show EventID instance Pretty EventID instance Eq TimeStamp instance Ord TimeStamp instance Show TimeStamp instance Pretty TimeStamp instance Eq SampleTypeBitMap instance Show SampleTypeBitMap instance Pretty SampleTypeBitMap instance Eq ByteCount64 instance Ord ByteCount64 instance Show ByteCount64 instance Pretty ByteCount64 instance Enum ByteCount64 instance Integral ByteCount64 instance Real ByteCount64 instance Num ByteCount64 instance Eq ByteCount32 instance Ord ByteCount32 instance Show ByteCount32 instance Pretty ByteCount32 instance Enum ByteCount32 instance Integral ByteCount32 instance Real ByteCount32 instance Num ByteCount32 instance Eq ByteCount16 instance Ord ByteCount16 instance Show ByteCount16 instance Pretty ByteCount16 instance Enum ByteCount16 instance Integral ByteCount16 instance Real ByteCount16 instance Num ByteCount16 instance Eq EventType instance Show EventType instance Eq SampleFormat instance Enum SampleFormat instance Show SampleFormat instance Eq EventCPUMode instance Show EventCPUMode instance Eq EventAttrFlag instance Ord EventAttrFlag instance Enum EventAttrFlag instance Show EventAttrFlag instance Eq EventSource instance Ord EventSource instance Show EventSource instance Enum EventSource instance Show EventPayload instance Pretty EventPayload instance Pretty EventHeader instance Pretty TraceEventType instance Pretty FileAttr instance Pretty EventAttr instance Pretty EventSource instance Pretty EventAttrFlag instance Pretty FileHeader instance Pretty FileSection instance Pretty EventCPUMode instance Pretty SampleFormat instance Pretty EventType instance Enum EventType instance Pretty Event -- | A library to parse and pretty print the contents of perf.data -- file, the output of the perf record command on Linux (Linux -- performance counter information). module Profiling.Linux.Perf.Parse -- | Read the perf data FileHeader from the input file handle. readHeader :: Handle -> IO FileHeader -- | Read the perf event attributes from the input file handle. readAttributes :: Handle -> FileHeader -> IO [FileAttr] -- | Read the EventIDs from the input file handle. readAttributeIDs :: Handle -> FileAttr -> IO [EventID] -- | Read an EventHeader from the input file handle. readEventHeader :: Handle -> ByteCount64 -> IO EventHeader -- | Read an event record from the input file handle. readEvent :: Handle -> ByteCount64 -> SampleTypeBitMap -> IO Event -- | Read the event type information from the input file handle. readEventTypes :: Handle -> FileHeader -> IO [TraceEventType] -- | A higher-level interface to the perf data file parsing code. -- -- Below is an example program which reads and parses a perf.data file -- and then dumps the contents to standard output: -- -- 
--   module Main where
--   
--   import Profiling.Linux.Perf (readAndDisplay, OutputStyle (..))
--   import System.Environment (getArgs)
--   
--   main :: IO ()
--   main = do
--     args <- getArgs
--     case args of
--        [] -> return ()
--        (file:_) -> readAndDisplay Dump file
--
module Profiling.Linux.Perf -- | Associate events with their event types. Events are (usually) tagged -- with an EventID. Many events can share the same EventID. -- Each EventID is associated with exactly one event type, which -- includes the name of the event, an EventSource and an -- EventTypeID type TypeMap = Map EventID TypeInfo -- | Type information for of event. data TypeInfo TypeInfo :: String -> EventSource -> EventTypeID -> TypeInfo -- | Printable name of the event source. typeInfo_name :: TypeInfo -> String -- | Kind of the event source (hardware, software, tracepoint etc.). typeInfo_source :: TypeInfo -> EventSource -- | Unique number of this type of event. typeInfo_id :: TypeInfo -> EventTypeID -- | Style to use for printing the event data. data OutputStyle -- | Output full details of the data file preserving the original order of -- the events. Dump :: OutputStyle -- | Output command and sample events in time order with event type -- annotations. Trace :: OutputStyle -- | Read the contents of the perf.data file and render it on stdout in a -- specified style. readAndDisplay :: OutputStyle -> FilePath -> IO () -- | Read and parse the perf.data file into its constituent components. readPerfData :: FilePath -> IO PerfData -- | Render the components of the perf.data file under the specified style. -- Don't create a single big Doc or String to avoid -- stack overflows. Instead, lazily print events as they are rendered. display :: OutputStyle -> PerfData -> IO () -- | Build a map from EventIDs to their type information. makeTypeMap :: PerfData -> TypeMap -- | Sort a list of events in ascending time order. Events without a -- timestamp are treated as having a timestamp of 0, which places them at -- the start of the sorted output. sortEventsOnTime :: [Event] -> [Event]