Update documentation (LLNL#291)

* Documentation update

* Update README [skip ci]

* Update config check service categories

README.md

@@ -5,8 +5,8 @@ Caliper: A Performance Analysis Toolbox in a Library
 [![Coverage](https://img.shields.io/codecov/c/github/LLNL/Caliper/master.svg)](https://codecov.io/gh/LLNL/Caliper)
 
 Caliper is a program instrumentation and performance measurement
-framework. It is designed as a performance analysis toolbox in a
-library, allowing one to bake performance analysis capabilities
+framework. It is a performance analysis toolbox in a library,
+allowing one to bake performance analysis capabilities
 directly into applications and activate them at runtime.
 
 Caliper can be used for lightweight always-on profiling or advanced
@@ -39,14 +39,11 @@ Documentation
 Extensive documentation is available here:
 https://llnl.github.io/Caliper/
 
-Usage examples of the C++ and C annotation interfaces are provided in
-the [examples](examples/apps) directory.
+Usage examples of the C++, C, and Fortran annotation and ConfigManager
+APIs are provided in the [examples](examples/apps) directory.
 
 See the "Getting started" section below for a brief tutorial.
 
-Example applications, configuration files, and a more extensive
-tutorial can be found [here](https://github.com/LLNL/caliper-examples).
-
 Building and installing
 ------------------------------------------
 
@@ -135,15 +132,14 @@ runtime (libcaliper.so), as shown in the example link command:
 
     g++ -o app app.o -L<path to caliper installation>/lib64 -lcaliper
 
-### Runtime configuration
+### Recording performance data
 
-Caliper's performance measurement and data collection functionality
-must be enabled and configured at runtime through Caliper's
-configuration API, configuration files, or environment variables. By
-default, Caliper will keep track of the current Caliper context
-provided by the annotation API calls (allowing third-party tools to
-access program context information), but won't run any performance
-measurement or data recording on its own.
+Performance measuremens can be controlled most conveniently via the
+ConfigManager API. The ConfigManager covers many common use cases,
+such as recording traces or printing time reports. For custom analysis
+tasks or when not using the ConfigManager API, Caliper can be configured
+manually by setting configuration variables via the environment or
+in config files.
 
 #### ConfigManager API
 
@@ -178,7 +174,7 @@ configs include
 Complete documentation on the ConfigManager configurations can be found
 [here](doc/ConfigManagerAPI.md).
 
-#### Configuring through environment variables
+#### Manual configuration through environment variables
 
 The ConfigManager API is not required to run Caliper - performance
 measurements can also be configured with environment variables or a config
@@ -189,7 +185,7 @@ profiles that can be activated with the
 microseconds) spent in each code path based on the nesting of
 annotated code regions:
 
-    $ CALI_CONFIG_PROFILE=runtime-report ./examples/apps/cali-basic-annotations
+    $ CALI_CONFIG_PROFILE=runtime-report ./examples/apps/cxx-example
     Path         Inclusive time (usec) Exclusive time (usec) Time %
     main                     38.000000             20.000000   52.6
       main loop               8.000000              8.000000   21.1
@@ -198,10 +194,11 @@ annotated code regions:
 The example shows Caliper output for the `runtime-report`
 configuration profile for the source-code annotation example above.
 
-As another example, the `serial-trace` configuration profile
-configures Caliper to record an event trace of each annotation event:
+For complete control, users can select and configure Caliper *services*
+manually. For example, this configuration records an event trace
+recording all enter and leave events for annotated code regions:
 
-    $ CALI_CONFIG_PROFILE=serial-trace ./examples/apps/cali-basic-annotations
+    $ CALI_SERVICES_ENABLE=event,recorder,timestamp,trace ./examples/apps/cxx-example
     == CALIPER: Registered event trigger service
     == CALIPER: Registered recorder service
     == CALIPER: Registered timestamp service
@@ -235,9 +232,6 @@ print the recorded trace data in a human-readable json format:
     },
     ...
 
-It is possible to create entirely custom configurations. This requires
-selecting a combination of Caliper *services* that implement specific
-functionality and configuring them for the task at hand.
 More information can be found in the [Caliper documentation](https://llnl.github.io/Caliper/).
 
 Authors

doc/sphinx/AnnotationAPI.rst

@@ -1,4 +1,4 @@
-Source-code Annotations
+Source-code annotations
 ================================
 
 Caliper provides source-code annotation APIs to mark and name code
@@ -205,7 +205,7 @@ follows:
 The ``byname`` variants refer to attribute keys by their name. If no
 attribute key with the given name exists, it will be created with
 default properties. The basic variants take an attribute ID, e.g.
-from :c:func:`cali_create_attribute()`.
+from :cpp:func:`cali_create_attribute()`.
 
 Example:
 

doc/sphinx/ConfigManagerAPI.rst

@@ -1,12 +1,251 @@
-Configuration Manager API
+Configuration manager API
 ===============================
 
-The configuration manager API is the principal component to configure
-Caliper performance measurements from within an application. 
-It provides access to various built-in measurement/reporting 
-configurations. 
+Caliper provides several built-in performance measurement and reporting
+configurations. These can be activated from within a program with the
+`ConfigManager` API using a short configuration string. Configuration
+strings can be hard-coded in the program or provided by the user in some
+form, e.g. as a command-line parameter or in the programs's configuration
+file.
+
+To access and control the built-in configurations, create a
+:cpp:class:`cali::ConfigManager` object. Add a configuration string with `add()`,
+start the requested configuration channels with `start()`, and trigger
+output with `flush()`:
+
+.. code-block:: c++
+
+   #include <caliper/cali-manager.h>
+
+   int main(int argc, char* argv[])
+   {
+      cali::ConfigManager mgr;
+
+      if (argc > 1)
+         mgr.add(argv[1]);
+      if (mgr.error())
+         std::cerr << "Config error: " << mgr.error_msg() << std::endl;
+      // ...
+      mgr.start(); // start requested performance measurement channels
+      // ... (program execution)
+      mgr.flush(); // write performance results
+   }
+
+
+ConfigManager Configuration String Syntax
+-----------------------------------------
+
+A configuration string for the `ConfigManager` class is a comma-separated list
+of *configs* and *parameters*.
+
+A *config* is the name of one of Caliper's built-in measurement configurations,
+e.g. `runtime-report` or `event-trace`. Multiple configs can be specified,
+separated by comma.
+
+Most configs have optional parameters, e.g. `output` to name an output file.
+Parameters can be specified as a list of key-value pairs in parantheses after the
+config name, e.g. ``runtime-report(output=report.txt,io.bytes=true)``. For boolean
+parameters, only the key needs to be added to enable it; for example,
+`io.bytes` is equal to `io.bytes=true`.
+
+Parameters can also be listed separately in the config string, outside of parentheses.
+In that case, the parameter applies to *all* configs, whereas parameters inside
+parentheses only apply to the  config where they are listed. For example, in
+``runtime-report(io.bytes),spot,mem.highwatermark``, the `mem.highwatermark` option
+will be active in both the runtime-report and spot config, whereas `io.bytes`
+will only be active for runtime-report. Configs and parameters can be listed in
+any order.
+
+Here is a more complex example::
+
+    runtime-report(output=stdout),profile.cuda,mem.highwatermark,event-trace(output=trace.cali,trace.io)
+
+This will print a runtime profile to stdout, including CUDA API calls and memory
+high-water marks in the profile, and write an event trace with region begin/end and I/O
+operations into the trace.cali file.
+
+Built-in configs
+-------------------------------
+
+The following list describes the ConfigManager's built-in configs and their
+parameters. Note that depending on the Caliper build configuration, not all
+configs or options may be available in a particular Caliper installation.
+
+event-trace
+   Record a trace of region enter/exit events in .cali format. Options:
+
+   event.timestamps
+      Record event timestamps
+   output
+      Output location ('stdout', 'stderr', or filename)
+   trace.io
+      Trace I/O events
+   trace.mpi
+      Trace I/O events
+
+hatchet-region-profile
+   Record a region time profile for processing with hatchet. Options:
+
+   adiak.import_categories
+      Adiak import categories. Comma-separated list of integers.
+   io.bytes
+      Report I/O bytes written and read
+   io.bytes.read
+      Report I/O bytes read
+   io.bytes.written
+      Report I/O bytes written
+   io.read.bandwidth
+      Report I/O read bandwidth
+   io.write.bandwidth
+      Report I/O write bandwidth
+   mem.highwatermark
+      Record memory high-water mark for regions
+   output
+      Output location ('stdout', 'stderr', or filename)
+   output.format
+      Output format ('hatchet', 'cali', 'json')
+   profile.cuda
+      Profile CUDA API functions
+   profile.mpi
+      Profile MPI functions
+   topdown-counters.all
+      Raw counter values for Intel top-down analysis (all levels)
+   topdown-counters.toplevel
+      Raw counter values for Intel top-down analysis (top level)
+   topdown.all
+      Top-down analysis for Intel CPUs (all levels)
+   topdown.toplevel
+      Top-down analysis for Intel CPUs (top level)
+   use.mpi
+      Merge results into a single output stream in MPI programs
+
+hatchet-sample-profile
+   Record a sampling profile for processing with hatchet. Options:
+
+   adiak.import_categories
+      Adiak import categories. Comma-separated list of integers.
+   lookup.module
+      Lookup source module (.so/.exe)
+   lookup.sourceloc
+      Lookup source location (file+line)
+   output
+      Output location ('stdout', 'stderr', or filename)
+   output.format
+      Output format ('hatchet', 'cali', 'json')
+   sample.callpath
+      Perform call-stack unwinding
+   sample.frequency
+      Sampling frequency in Hz. Default: 200
+   sample.threads
+      Profile all threads.
+   use.mpi
+      Merge results into a single output stream in MPI programs
+
+loop-report
+   Print summary and time-series information for loops. Options:
+
+   aggregate_across_ranks
+      Aggregate results across MPI ranks
+   io.bytes
+      Report I/O bytes written and read
+   io.bytes.read
+      Report I/O bytes read
+   io.bytes.written
+      Report I/O bytes written
+   io.read.bandwidth
+      Report I/O read bandwidth
+   io.write.bandwidth
+      Report I/O write bandwidth
+   iteration_interval
+      Measure every N loop iterations
+   mem.highwatermark
+      Record memory high-water mark for regions
+   output
+      Output location ('stdout', 'stderr', or filename)
+   summary
+      Print loop summary
+   target_loops
+      List of loops to target. Default: any top-level loop.
+   time_interval
+      Measure after t seconds
+   timeseries
+      Print time series
+   timeseries.maxrows
+      Max number of rows in timeseries display. Set to 0 to show all. Default: 20.
+   topdown.all
+      Top-down analysis for Intel CPUs (all levels)
+   topdown.toplevel
+      Top-down analysis for Intel CPUs (top level)
+
+mpi-report
+   Print time spent in MPI functions
+
+runtime-report
+   Print a time profile for annotated regions. Options:
+
+   aggregate_across_ranks
+      Aggregate results across MPI ranks
+   calc.inclusive
+      Report inclusive instead of exclusive times
+   io.bytes
+      Report I/O bytes written and read
+   io.bytes.read
+      Report I/O bytes read
+   io.bytes.written
+      Report I/O bytes written
+   io.read.bandwidth
+      Report I/O read bandwidth
+   io.write.bandwidth
+      Report I/O write bandwidth
+   max_column_width
+      Maximum column width in the tree display
+   mem.highwatermark
+      Record memory high-water mark for regions
+   output
+      Output location ('stdout', 'stderr', or filename)
+   profile.cuda
+      Profile CUDA API functions
+   profile.mpi
+      Profile MPI functions
+   topdown.all
+      Top-down analysis for Intel CPUs (all levels)
+   topdown.toplevel
+      Top-down analysis for Intel CPUs (top level)
+
+spot
+   Record a time profile for the Spot web visualization framework. Options:
+
+   adiak.import_categories
+      Adiak import categories. Comma-separated list of integers.
+   aggregate_across_ranks
+      Aggregate results across MPI ranks
+   io.bytes
+      Report I/O bytes written and read
+   io.bytes.read
+      Report I/O bytes read
+   io.bytes.written
+      Report I/O bytes written
+   io.read.bandwidth
+      Report I/O read bandwidth
+   io.write.bandwidth
+      Report I/O write bandwidth
+   mem.highwatermark
+      Record memory high-water mark for regions
+   output
+      Output location ('stdout', 'stderr', or filename)
+   profile.cuda
+      Profile CUDA API functions
+   profile.mpi
+      Profile MPI functions
+   topdown-counters.all
+      Raw counter values for Intel top-down analysis (all levels)
+   topdown-counters.toplevel
+      Raw counter values for Intel top-down analysis (top level)
+   topdown.all
+      Top-down analysis for Intel CPUs (all levels)
+   topdown.toplevel
+      Top-down analysis for Intel CPUs (top level)
 
-See :cpp:class:`cali::ConfigManager`.
 
 API Reference
 -------------------------------

doc/sphinx/DeveloperGuide.rst

@@ -1,4 +1,4 @@
-Developer Guide
+Developer guide
 ================================
 
 This section describes internal APIs for Caliper service developers.