From a2180ffec2a2dc2fa245952cf2d2371f06d39b2d Mon Sep 17 00:00:00 2001 From: David Boehme Date: Sat, 7 Nov 2015 18:57:19 -0800 Subject: [PATCH] Documentation update --- README.md | 30 +++++++++++++----------------- doc/services.rst | 19 +++++++++++++++---- src/caliper/Caliper.h | 2 +- 3 files changed, 29 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index cde932e91..cd992864d 100644 --- a/README.md +++ b/README.md @@ -141,18 +141,10 @@ program context combined with measurement data. When snapshots are taken, what is included in them, and how they are processed depends on the Caliper runtime configuration. It is thus important to configure the runtime correctly when running a Caliper-instrumented program. - -Much of Caliper's functionality is provided by optional service -modules. By default, Caliper does not enable any optional services -(and therefore doesn't do much). Use the `CALI_SERVICES_ENABLE` -variable to select services. For example, enable the `event`, -`recorder` and `timestamp` services to create a simple time-series -trace for the example program above: - - $ export CALI_SERVICES_ENABLE=event:recorder:timestamp - -You can achieve the same effect by selecting the `serial-trace` -built-in profile: +For common use cases, Caliper provides built-in configuration profiles +as starting points. For example, the `serial-trace` profile will +record a time-stamped event trace. You can select a profile with the +`CALI_CONFIG_PROFILE` environment variable: $ export CALI_CONFIG_PROFILE=serial-trace @@ -165,7 +157,7 @@ Then run the program: == CALIPER: Wrote 36 records. == CALIPER: Finished -The recorder service will write the time-series trace to a `.cali` +With this profile, Caliper will write a time-series trace to a `.cali` file in the current working directory. Use the `cali-query` tool to filter, aggregate, or print traces: @@ -204,9 +196,9 @@ Here is a list of commonly used variables: informational output, 2 for more verbose output, or 0 to disable output except for critical error messages. Default 1. -* `CALI_SERVICES_ENABLE=(service1:service2:...)` List of Caliper service modules to enable, - separated by `:`. Default: not set, no service modules enabled. See - below for a list of Caliper services. +* `CALI_SERVICES_ENABLE=(service1:service2:...)` List of Caliper service + modules to enable, separated by `:`. Default: not set, no service modules + enabled. See below for a list of Caliper services. ### List of Caliper services @@ -216,6 +208,9 @@ capabilities. The flexible combination and configuration of these services allows you to quickly assemble recording solutions for a wide range of usage scenarios. +Many of the services provide additional configuration options. Refer to +the service documentation to learn more. + You can enable the services required for your measurement with the `CALI_SERVICES_ENABLE` configuration variable @@ -236,7 +231,8 @@ The following services are available: A thread environment manager such as the `pthread` service creates separate per-thread contexts in a multi-threaded program. * `papi` Records PAPI hardware counters. -* `recorder` Writes context trace data. +* `recorder` Writes data to disk +* `trace` Creates a trace of snapshots * `timestamp` The timestamp service adds a time offset, timestamp, or duration to context records. diff --git a/doc/services.rst b/doc/services.rst index 2a2b5b749..2a7c49f70 100644 --- a/doc/services.rst +++ b/doc/services.rst @@ -180,9 +180,9 @@ recommended to enable the `pthread` service. Recorder -------------------------------- -The recorder service writes context snapshots into a context trace file. +The recorder service writes Caliper I/O records into a file. -By default, the recorder service stores context records in an +By default, the recorder service stores records in an in-memory buffer to avoid application performance perturbance because of I/O. You can configure the buffer sizes and determine whether they are allowed to grow. You can also set the directory and filename that @@ -226,8 +226,8 @@ Configuration ................................ CALI_TIMER_DURATION=(true|false) - Include duration (in microseconds) of the context epoch in context - snapshots. Default: true + Measure duration (in microseconds) of the context epoch (i.e., the time + between two consecutive context snapshots). Default: true CALI_TIMER_OFFSET=(true|false) Include the time offset (time since program start, in microseconds) @@ -236,4 +236,15 @@ CALI_TIMER_OFFSET=(true|false) CALI_TIMER_TIMESTAMP=(true|false) Include absolute timestamp (time since UNIX epoch, in seconds) with each context snapshot. + +CALI_TIMER_PHASE_DURATION + Measure the duration of begin/end, set/set, or set/end phases. The + event service with event trigger information generation needs to be + enabled for this feature. +Trace +-------------------------------- + +The trace service creates an I/O record for each snapshot. With the +`recorder` sercice enabled, this will create a snapshot trace file. + diff --git a/src/caliper/Caliper.h b/src/caliper/Caliper.h index e6e93eaaa..35662914b 100644 --- a/src/caliper/Caliper.h +++ b/src/caliper/Caliper.h @@ -1,5 +1,5 @@ /** - * @file caliper.h + * @file Caliper.h * Initialization function and global data declaration */