linuxperf API¶

class linuxperf.analysis.FlameGraphWindow(timeline_window: TimelineWindow, pid: int, tid: int)¶

Bases: Window

get_analysable() → Analysable¶: Return the Analysable object associated with the window.

get_constr_args() → list¶: Return the arguments required to construct the window.

get_data()¶: Return the data stored by the window.

get_dependencies() → list¶: Return the Window objects on which this window depends.

get_init_data()¶: Return the initialisation data required by the window.

get_module() → Module¶: Return the Module object associated with the window.

get_session() → Session¶: Return the performance analysis session associated with the window.

get_type() → str¶: Return the type identifier of the window. On the client side in JavaScript, this must match the return value of getType() in the corresponding module class and be recognised by getWindowClass().

class linuxperf.analysis.LinuxperfModule(session_id: Identifier, entity: str, node: str)¶

Bases: Module

get_callchain_mappings(event_type=None)¶

Get a dictionary mapping compressed callchain names of a given event type to a two-element array [<full symbol name>, <library/executable name>].

If event_type is None (by default), a wrapper dictionary is returned for all available event types with the following structure:

{
  "<event type>": <result of get_callchain_mappings("<event type>")>
}

If event_type is “syscall”, a dictionary for compressed callchain names captured during thread/process tree profiling is returned.

If event_type is invalid or does not exist, None is returned.

get_flame_graph(pid, tid, compress_threshold, region=None)¶

Get a flame graph of the thread/process with a given PID and TID to be rendered by d3-flame-graph, taking into account to collapse blocks taking less than a specified share of total samples.

Parameters:

pid (int) – PID of a thread/process.
tid (int) – TID of a thread/process.
compress_threshold (float) – A compression threshold. For example, if its value is 0.10, blocks taking less than 10% of total samples will be collapsed.

get_flame_graph_window(pid: int, tid: int)¶

Get a FlameGraphWindow object (an adaptystanalyser.Window subclass) corresponding to a flame graph of a thread/process with the given PID and TID. This can be used e.g. to save a single window arrangement with a given flame graph and share it with others programmatically (use Window.save_arrgmt() and Window.get_arrgmt_url() for this).

If no valid value of PID and/or TID is provided, None is returned.

Parameters:

pid (int) – PID of a thread/process.
tid (int) – TID of a thread/process.

get_general_analysis(analysis_type)¶

Get general analysis data of a specified type. If the type does not exist or the corresponding data could not be read, None is returned.

Currently-supported general analysis types:

“roofline”: cache-aware roofline benchmark analysis of a machine produced by the CARM Tool by INESC-ID (https://github.com/champ-hub/carm-roofline). The return value is a dictionary with the following structure:

{
  "type": "roofline",
  "l1": <L1 cache size in bytes>,
  "l2": <L2 cache size in bytes>,
  "l3": <L3 cache size in bytes>,
  "models": <array of roofline models>
}

Each element of the array of roofline models has the following structure (for all references to --<option>, go to https://github.com/champ-hub/carm-roofline#how-to-use-cli):

{
  "isa": "<instruction set architecture: see --isa for the
           possible values>",
  "precision": "<floating-point precision: see --precision
                 for the format>",
  "threads": "<number of threads>",
  "loads": "<number of loads>",
  "stores": "<number of stores>",
  "interleaved": "<whether cores belong to interleaved NUMA domains:
                   the value is either Yes or No, see --interleaved
                   for more details>",
  "dram_bytes": "<number of DRAM bytes>",
  "fp_inst": "<floating-point instruction used: see --inst for
               the format>",
  "l1": {
    "gbps": "<L1 performance in GB/s>",
    "instpc"; "<L1 instructions per cycle>"
  },
  "l2": {
    "gbps": "<L2 performance in GB/s>",
    "instpc": "<L2 instructions per cycle>"
  },
  "l3": {
    "gbps": "<L3 performance in GB/s>",
    "instpc": "<L3 instructions per cycle>"
  },
  "dram": {
    "gbps": "<DRAM performance in GB/s>",
    "instpc": "<DRAM instructions per cycle>"
  },
  "fp": {
    "gflops": "<floating-point performance in GFLOPS>",
    "instpc": "<floating-point instructions per cycle>"
  },
  "fp_fma": {
    "gflops": "<floating-point FMA performance in GFLOPS>",
    "instpc": "<floating-point FMA instructions per cycle>"
  }
}

Parameters:: analysis_type (str) – Type of a general analysis which data should be returned for.

get_json_tree()¶

Get a JSON object string representing the thread/process tree.

The returned object is the root, which describes the very first process detected along with its children. The object has the following keys:

id: the unique identifier of a thread/process in form of “<PID>_<TID>”.
start_time: the timestamp of the moment when the thread/process was effectively started, in milliseconds.
runtime: the number of milliseconds the thread/process was running for.
sampled_time: the number of milliseconds the thread/process was running for, as sampled by “perf”.
name: the process name.
pid_tid: the PID and TID pair string in form of “<PID>/<TID>”.
off_cpu: the list of intervals when the thread/process was off-CPU. Each interval is in form of (a, b), where a is the start time of an off-CPU interval and b is the length of such interval.
start_callchain: the callchain spawning the thread/process.
metrics: the JSON object mapping extra per-thread profiling metrics (in addition to on-CPU/off-CPU activity) to their website titles and their type (i.e. flame-graph-related or not flame-graph-related). An example object is {"page-faults": {"title": "Page faults", "flame_graph": true}}. The structure can also be empty.
general_metrics: the JSON object mapping general profiling metrics to their website titles and other auxiliary data (e.g. {"roofline": {"title": "Roofline model", ...}). This is set only for the root and it can be empty.
src: the return value of get_sources(), see its documentation for the details. This is set only for the root.
src_index: the return value of get_source_index(), see its documentation for the details. This is set only for the root.
children: the list of all threads/processes spawned by the thread/process. Each element has the same structure as the root except for elements indicated as “set only for the root”.
roofline: the JSON object with information necessary for interpreting roofline profiling results. The structure is as follows: {"cpu_type": "<CPU type, e.g. Intel_x86>", "ai_keys": [<events for calculating arithmetic intensity>], "instr_keys": [<events for calculating FLOPS etc.>]}. This is set only for the root and it can be empty.

get_name()¶: Return the name of the module.

get_source_code(filename)¶

Get a source code stored in the module results under a specified name.

Parameters:: filename (str) – Name of a source code to be obtained. It must come from get_source_index().

get_source_index()¶: Get the dictionary mapping source code paths from get_sources() to shortened filenames that should be provided to get_source_code(). It can be empty.

get_sources()¶

Get the dictionary mapping library/executable offsets to lines within source code files. It can be empty.

The structure is as follows:

{
  "<library/executable path>": {
    "<hex offset>": {
      "file": "<path>",
      "line": <number>
    }
  }
}

Use get_source_code() along with get_source_index() to obtain a source code corresponding to <path>.

get_thread_tree() → Tree¶

Get a treelib.Tree object representing the thread/process tree.

Each node corresponds to a thread/process: its identifier is equal to the TID and its tag is in form of ["<thread/process name>", "<PID>/<TID>", <exact start time in ns>, <exact runtime in ns>].

get_timeline_window()¶: Get a TimelineWindow object (an adaptystanalyser.Window subclass) corresponding to the timeline view of all threads/processes captured during a linuxperf performance analysis session. This can be used e.g. to save a single window arrangement with the timeline and share it with others programmatically (use Window.save_arrgmt() and Window.get_arrgmt_url() for this).

process_post_request(data)¶: Please see the REST API documentation of the linuxperf module for the structure of POST requests here.

class linuxperf.analysis.TimelineWindow(session: Session, module: Module)¶

Bases: Window

get_analysable() → Analysable¶: Return the Analysable object associated with the window.

get_constr_args() → list¶: Return the arguments required to construct the window.

get_data()¶: Return the data stored by the window.

get_dependencies() → list¶: Return the Window objects on which this window depends.

get_init_data()¶: Return the initialisation data required by the window.

get_module() → Module¶: Return the Module object associated with the window.

get_session() → Session¶: Return the performance analysis session associated with the window.

get_type() → str¶: Return the type identifier of the window. On the client side in JavaScript, this must match the return value of getType() in the corresponding module class and be recognised by getWindowClass().

linuxperf API¶

adaptyst-analyser-linuxperf

Navigation

Related Topics