timemory 3.3.0
Modular C++ Toolkit for Performance Analysis and Logging. Profiling API and Tools for C, C++, CUDA, Fortran, and Python. The C++ template API is essentially a framework to creating tools: it is designed to provide a unifying interface for recording various performance measurements alongside data logging and interfaces to other tools.
timemory

Timing + Memory + Hardware Counter Utilities for C / C++ / CUDA / Python

Build Status Build status codecov

timemory on GitHub (Source code)

timemory General Documentation (ReadTheDocs)

timemory Source Code Documentation (Doxygen)

timemory Testing Dashboard (CDash)

timemory Tutorials

timemory Wiki

GitHub git clone https://github.com/NERSC/timemory.git
PyPi pip install timemory
Spack spack install timemory
conda-forge conda install -c conda-forge timemory
Conda Recipe Conda Downloads Conda Version Conda Platforms

Purpose

The goal of timemory is to create an open-source performance measurement and analyis package with modular and reusable components which can be used to adapt to any existing C/C++ performance measurement and analysis API and is arbitrarily extendable by users within their application. Timemory is not just another profiling tool, it is a profling toolkit which streamlines building custom profiling tools through modularity and then utilizes the toolkit to provides several pre-built tools.

In other words, timemory provides many pre-built tools, libraries, and interfaces but, due to it's modularity, codes can re-use only individual pieces – such as the classes for measuring different timing intervals, memory usage, and hardware counters – without the timemory "runtime management".

Building and Installing

Timemory uses a standard CMake installation. Several installation examples can be found in the Wiki. See the installation documentation for detailed information on the CMake options.

Documentation

The full documentation is available at timemory.readthedocs.io. Detailed source documentation is provided in the doygen section of the full documentation. Tutorials are available in the github.com/NERSC/timemory-tutorials.

Overview

The primary objective of the timemory is the development of a common framework for binding together software monitoring code (i.e. performance analysis, debugging, logging) into a compact and highly-efficient interface.

Timemory arose out of the need for a universal adapator kit for the various APIs provided several existing tools and a straight-forward and intuitive method for creating new tools. Timemory makes it possible to bundle together deterministic performance measurements, statistical performance measurements (i.e. sampling), debug messages, data logging, and data validation into the same interface for custom application-specific software monitoring interfaces, easily building tools like time, netstat, instrumentation profilers, sampling profilers, and writing implementations for MPI-P, MPI-T, OMPT, KokkosP, etc. Furthermore, timemory can forward its markers to several third-party profilers such as LIKWID, Caliper, TAU, gperftools, Perfetto, VTune, Allinea-MAP, CrayPAT, Nsight-Systems, Nsight-Compute, and NVProf.

Timemory provides a front-end C/C++/Fortran API and Python API which allows arbitrary selection of 50+ different components from timers to hardware counters to interfaces with third-party tools. This is all built generically from the toolkit API with type-safe bundles of tools such as: component_tuple<wall_clock, papi_vector, nvtx_marker, user_bundle> where wall_clock is a wall-clock timer, papi_vector is a handle for hardware counters, nvxt_marker creates notations in the NVIDIA CUDA profilers, and user_bundle is a generic component which downstream users can insert more components into at runtime.

Performance measurement components written with timemory are arbitrarily scalable up to any number of threads and processes and fully support intermixing different measurements at different locations within the program – this uniquely enables timemory to be deployed to collect performance data at scale in HPC because highly detailed collection can occur at specific locations within the program where ubiquitous collection would simulatenously degrade performance significantly and require a prohibitive amount of memory.

Timemory can be used as a backend to bundle instrumentation and sampling tools together, support serialization to JSON/XML, and provide statistics among other uses. It can also be utilized as a front-end to invoke custom instrumentation and sampling tools. Timemory uses the abstract term "component" for a structure which encapsulates some performance analysis operation. The structure might encapsulate function calls to another tool, record timestamps for timing, log values provided by the application, provide a operator for replacing a function in the code dynamically, audit the incoming arguments and/or outgoing return value from function, or just provide stubs which can be overloaded by the linker.

Visualization and Analysis

The native output format of timemory is JSON and text; other output formats such as XML are also supported. The text format is intended to be human readable. The JSON data is intended for analysis and comes in two flavors: hierarchical and flat. Basic plotting capabilities are available via timemory-plotting but users are highly encouraged to use hatchet for analyzing the heirarchical JSON data in pandas dataframes. Hatchet supports filtering, unions, addition, subtractions, output to dot and flamegraph formats, and an interactive Jupyter notebook. At present, timemory supports 45+ metric types for analysis in Hatchet.

Categories

There are 4 primary categories in timemory: components, operations, bundlers, and storage. Components provide the specifics of how to perform a particular behavior, operations provide the scaffold for requesting that a component perform an operation in complex scenarios, bundlers group components into a single generic handle, and storage manages data collection over the lifetime of the application. When all four categories are combined, timemory effectively resembles a standard performance analysis tool which passively collects data and provides reports and analysis at the termination of the application. Timemory, however, makes it very easy to subtract storage from the equation and, in doing so, transforms timemory into a toolkit for customized data collection.

  1. Components
    • Individual classes which encapsulate one or more measurement, analysis, logging, or third-party library action(s)
    • Any data specific to one instance of performing the action is stored within the instance of the class
    • Any configuration data specific to that type is typically stored within static member functions which return a reference to the configuration data
    • These classes are designed to support direct usage within other tools, libraries, etc.
    • Examples include:
  2. Operations
    • Templated classes whose primary purpose is to provide the implementation for performing some action on a component, e.g. tim::operation::start<wall_clock> will attempt to call the start() member function on a wall_clock component instance
    • Default implementations generally have one or two public functions: a constructor and/or a function call operator
      • These generally accept any/all arguments and use SFINAE to determine whether the operation can be performed with or without the given arguments (i.e. does wall_clock have a store(int) function? store()?)
    • Operations are (generally) not directly utilized by the user and are typically optimized out of the binary
    • Examples include:
  3. Bundlers
    • Provide a generic handle for multiple components
    • Member functions generally accept any/all arguments and use operations classes to correctly to handle differences between different capabilities of the components it is bundling
    • Examples include:
    • Various flavors provide different implicit behaviors and allocate memory differently
      • auto_tuple starts all components when constructed and stops all components when destructed whereas component_tuple requires an explicit start
      • component_tuple allocates all components on the stack and components are "always on" whereas component_list allocates components on the heap and thus components can be activated/deactivated at runtime
      • lightweight_tuple does not implicitly perform any expensive actions, such as call-stack tracking in "Storage"
  4. Storage
    • Provides persistent storage for multiple instances of components over the lifetime of a thread in the application
    • Responsible for maintaining the hierarchy and order of component measurements, i.e. call-stack tracking
    • Responsible for combining component data from multiple threads and/or processes and outputting the results

NOTE: tim::lightweight_tuple is the recommended bundle for those seeking to use timemory as a toolkit for implementing custom tools and interfaces

Features

  • C++ Template API
    • Modular and fully-customizable
    • Adheres to C++ standard template library paradigm of "you don't pay for what you don't use"
    • Simplifies and facilitates creation and implementation of performance measurement tools
      • Create your own instrumentation profiler
      • Create your own instrumentation library
      • Create your own sampling profiler
      • Create your own sampling library
      • Create your own execution wrappers
      • Supplement timemory-provided tools with your own custom component(s)
      • Thread-safe data aggregation
      • Aggregate collection over multiple processes (MPI and UPC++ support)
      • Serialization to text, JSON, XML
    • Components are composable with other components
    • Variadic component bundlers which maintain complete type-safety
      • Components can be bundled together into a single handle without abstractions
    • Components can store data in any valid C++ data type
    • Components can return data in any valid C++ data type
  • C / C++ / CUDA / Fortran Library API
    • Straight-forward collection of functions and macros for creating built-in performance analysis to your code
    • Component collection can be arbitrarily inter-mixed
      • E.g. collect "A" and "B" in one region, "A" and "C" in another region
    • Component collection can be dynamically manipulated at runtime
      • E.g. add/remove "A" at any point, on any thread, on any process
  • Python API
    • Decorators and context-managers for functions or regions in code
    • Python function profiling
    • Python line-by-line profiling
    • Every component in timemory-avail is provided as a stand-alone Python class
      • Provide low-overhead measurements for building your own Python profiling tools
  • Python Analysis via pandas
  • Command-line Tools
    • timemory-avail
      • Provides available components, settings, and hardware counters
      • Quick API reference tool
    • timem (UNIX)
      • Extended version of UNIX time command-line tool that includes additional information on memory usage, context switches, and hardware counters
      • Support collecting hardware counters (Linux-only, requires PAPI)
    • timemory-run (Linux)
      • Dynamic instrumentation profiling tool
      • Supports runtime instrumentation and binary re-writing
    • timemory-nvml
      • Data collection similar to nvidia-smi
    • timemory-python-profiler
      • Python function profiler supporting all timemory components
      • from timemory.profiler import Profile
    • timemory-python-trace
      • Python line-by-line profiler supporting all timemory components
      • from timemory.trace import Trace
    • timemory-python-line-profiler
      • Python line-by-line profiler based on line-profiler package
      • Extended to use components: cpu-clock, memory-usage, context-switches, etc. (all components which collect scalar values)
      • from timemory.line_profiler import LineProfiler
  • Instrumentation Libraries
    • timemory-mpip: MPI Profiling Library (Linux-only)
    • timemory-ncclp: NCCL Profiling Library (Linux-only)
    • timemory-ompt: OpenMP Profiling Library
    • timemory-compiler-instrument: Compiler instrumentation Library
    • kokkos-connector: Kokkos Profiling Libraries

Samples

Various macros are defined for C in source/timemory/compat/timemory_c.h and source/timemory/variadic/macros.hpp. Numerous samples of their usage can be found in the examples.

Sample C++ Template API

namespace comp = tim::component;
using namespace tim;
// specific set of components
using specific_t = component_tuple<comp::wall_clock, comp::cpu_clock>;
using generic_t = component_tuple<comp::user_global_bundle>;
int
main(int argc, char** argv)
{
// configure default settings
// initialize with cmd-line
// add argparse support
// create a region "main"
specific_t m{ "main" };
m.start();
m.stop();
// pause and resume collection globally
settings::enabled() = false;
specific_t h{ "hidden" };
h.start().stop();
// Add peak_rss component to specific_t
mpl::push_back_t<specific_t, comp::peak_rss> wprss{ "with peak_rss" };
// create region collecting only peak_rss
component_tuple<comp::peak_rss> oprss{ "only peak_rss" };
// convert component_tuple to a type that starts/stops upon construction/destruction
{
scope::config _scope{};
if(true) _scope += scope::flat{};
if(false) _scope += scope::timeline{};
convert_t<specific_t, auto_tuple<>> scoped{ "scoped start/stop + flat", _scope };
// will yield auto_tuple<comp::wall_clock, comp::cpu_clock>
}
// configure the generic bundle via set of strings
runtime::configure<comp::user_global_bundle>({ "wall_clock", "peak_rss" });
// configure the generic bundle via set of enumeration ids
runtime::configure<comp::user_global_bundle>({ TIMEMORY_WALL_CLOCK, TIMEMORY_CPU_CLOCK });
// configure the generic bundle via component instances
comp::user_global_bundle::configure<comp::page_rss, comp::papi_vector>();
generic_t g{ "generic", quirk::config<quirk::auto_start>{} };
g.stop();
// Output the results
return 0;
}
#define TIMEMORY_CPU_CLOCK
Definition: enum.h:410
#define TIMEMORY_WALL_CLOCK
Definition: enum.h:632
Definition: kokkosp.cpp:39
flat_profile
Definition: settings.cpp:1797
void timemory_finalize()
finalization of the specified types
timemory_argparse(argc, argv)
void timemory_init(Args &&... _args)
Definition: config.hpp:49
char ** argv
Definition: config.cpp:55
timing_units
Definition: settings.cpp:1650

Sample C / C++ Library API

int
main(int argc, char** argv)
{
// configure settings
int overwrite = 0;
int update_settings = 1;
// default to flat-profile
timemory_set_environ("TIMEMORY_FLAT_PROFILE", "ON", overwrite, update_settings);
// force timing units
overwrite = 1;
timemory_set_environ("TIMEMORY_TIMING_UNITS", "msec", overwrite, update_settings);
// initialize with cmd-line
// check if inited, init with name
// define the default set of components
timemory_set_default("wall_clock, cpu_clock");
// create a region "main"
// pause and resume collection globally
// Add/remove component(s) to the current set of components
// get an identifier for a region and end it
uint64_t idx = timemory_get_begin_record("indexed");
// assign an existing identifier for a region
timemory_begin_record("indexed/2", &idx);
// create region collecting a specific set of data
timemory_begin_record_types("types", &idx, "peak_rss");
// replace current set of components and then restore previous set
// Output the results
return 0;
}
#define TIMEMORY_PEAK_RSS
Definition: enum.h:539
#define TIMEMORY_COMPONENTS_END
Definition: enum.h:155
void timemory_pause(void)
Turn off timemory collection.
Definition: library.cpp:313
void timemory_push_components_enum(int types,...)
Replace the current set of components with a new set of components with the set of enumerations provi...
Definition: library.cpp:377
void timemory_set_environ(const char *evar, const char *eval, int over, int parse)
Definition: library.cpp:335
void timemory_push_region(const char *name)
Definition: library.cpp:573
void timemory_end_record(uint64_t id)
Definition: library.cpp:557
void timemory_begin_record_enum(const char *name, uint64_t *id,...)
Similar to timemory_begin_record but accepts a specific enumerated set of components,...
Definition: library.cpp:450
void timemory_pop_components(void)
Inverse of the last timemory_push_components or timemory_push_components_enum call....
Definition: library.cpp:399
void timemory_add_components(const char *_component_string)
Add some components to the current set of components being collected Any components which are current...
Definition: library.cpp:348
void timemory_pop_region(const char *name)
Definition: library.cpp:587
bool timemory_library_is_initialized(void)
Returns whether the library is initialized or not.
Definition: library.cpp:195
void timemory_resume(void)
Turn on timemory collection.
Definition: library.cpp:318
void timemory_init_library(int argc, char **argv)
Initializes timemory. Not strictly necessary but highly recommended.
Definition: library.cpp:212
void timemory_remove_components(const char *_component_string)
Remove some components to the current set of components being collected. Any components which are not...
Definition: library.cpp:358
void timemory_push_components(const char *_component_string)
Replace the current set of components with a new set of components.
Definition: library.cpp:368
void timemory_named_init_library(char *name)
Definition: library.cpp:200
void timemory_begin_record_types(const char *name, uint64_t *id, const char *ctypes)
Similar to timemory_begin_record but accepts a specific set of components as a string.
Definition: library.cpp:429
uint64_t timemory_get_begin_record(const char *name)
Variant to timemory_begin_record which returns a unique integer.
Definition: library.cpp:482
void timemory_set_default(const char *_component_string)
Pass in a default set of components to use. Will be overridden by TIMEMORY_COMPONENTS environment var...
Definition: library.cpp:322
void timemory_begin_record(const char *name, uint64_t *id)
Definition: library.cpp:409
void timemory_finalize_library(void)
Finalizes timemory. Output will be generated. Any attempt to store data within timemory storage is un...
Definition: library.cpp:253

Sample Fortran API

program fortran_example
use timemory
use iso_c_binding, only : c_int64_t
implicit none
integer(C_INT64_T) :: idx
! initialize with explicit name
call timemory_init_library("ex-fortran")
! initialize with name extracted from get_command_argument(0, ...)
! call timemory_init_library("")
! define the default set of components
call timemory_set_default("wall_clock, cpu_clock")
! Start region "main"
call timemory_push_region("main")
! Add peak_rss to the current set of components
call timemory_add_components("peak_rss")
! Nested region "inner" nested under "main"
call timemory_push_region("inner")
! End the "inner" region
call timemory_pop_region("inner")
! remove peak_rss
call timemory_remove_components("peak_rss")
! begin a region and get an identifier
idx = timemory_get_begin_record("indexed")
! replace current set of components
call timemory_push_components("page_rss")
! Nested region "inner" with only page_rss components
call timemory_push_region("inner (pushed)")
! Stop "inner" region with only page_rss components
call timemory_pop_region("inner (pushed)")
! restore previous set of components
! end the "indexed" region
! End "main"
call timemory_pop_region("main")
! Output the results
end program fortran_example

Sample Python API

Decorator

from timemory.bundle import marker
@marker(["cpu_clock", "peak_rss"])
def foo():
pass

Context Manager

from timemory.profiler import profile
def bar():
with profile(["wall_clock", "cpu_util"]):
foo()

Individual Components

from timemory.component import WallClock
def spam():
wc = WallClock("spam")
wc.start()
bar()
wc.stop()
data = wc.get()
print(data)
void print(std::ostream &os, Args &&... args)
Definition: functional.cpp:159

Argparse Support

import argparse
parser = argparse.ArgumentParser("example")
# ...
timemory.add_arguments(parser)
args = parser.parse_args()

Component Storage

from timemory.storage import WallClockStorage
# data for current rank
data = WallClockStorage.get()
# combined data on rank zero but all ranks must call it
dmp_data = WallClockStorage.dmp_get()

Versioning

Timemory originated as a very simple tool for recording timing and memory measurements (hence the name) in C, C++, and Python and only supported three modes prior to the 3.0.0 release: a fixed set of timers, a pair of memory measurements, and the combination of the two. Prior to the 3.0.0 release, timemory was almost completely rewritten from scratch with the sole exceptions of some C/C++ macro, e.g. TIMEMORY_AUTO_TIMER, and some Python decorators and context-manager, e.g. timemory.util.auto_timer, whose behavior were able to be fully replicated in the new release. Thus, while it may appear that timemory is a mature project at v3.0+, it is essentially still in it's first major release.

Citing timemory

To reference timemory in a publication, please cite the following paper:

  • Madsen, J.R. et al. (2020) Timemory: Modular Performance Analysis for HPC. In: Sadayappan P., Chamberlain B., Juckeland G., Ltaief H. (eds) High Performance Computing. ISC High Performance 2020. Lecture Notes in Computer Science, vol 12151. Springer, Cham

Additional Information

For more information, refer to the documentation.