Implement annotation levels (#540)

* Implement annotation levels

* Add branch filter

* Update documentation

Author: daboehme

doc/sphinx/RegionFiltering.rst

@@ -11,6 +11,9 @@ include_regions
 exclude_regions
     Skip measurements for regions with the given pattern.
 
+include_branches
+    Only take measurements for regions inside a given branch.
+
 The options take a list of region patterns. There are three pattern types:
 
 match
@@ -67,11 +70,26 @@ region - `mainloop` in this case - which is why we still see measurement values
 for the `mainloop` region here. However, these do not represent the actual time
 spent in `mainloop`.
 
+With the `include_branches` option, we can limit measurements to a specific
+branch and its sub-regions, e.g. the `mainloop` branch::
+
+    $ CALI_CONFIG="runtime-report,include_branches=mainloop" ./examples/apps/cxx-example
+    Path       Min time/rank Max time/rank Avg time/rank Time %
+    main            0.000457      0.000457      0.000457 37.527884
+      mainloop      0.000108      0.000108      0.000108  8.882529
+        foo         0.000653      0.000653      0.000653 53.589588
+
+This limits measurement to the `mainloop` region and all its sub-regions.
+Again, measurement values taken when entering the `mainloop` region are
+assigned to its enclosing region (`main` in this case), but don't necessarily
+reflect the actual time spent there.
+
 We can use a pattern like `startswith(main)` to include `main` and `mainloop`.
-Be careful to wrap the option values in quotes to prevent them from being 
+Be careful to wrap the option values in quotes to prevent them from being
 misinterpreted by the config parser::
 
     $ CALI_CONFIG="runtime-report,include_regions=\"startswith(main)\"" ./examples/apps/cxx-example
     Path       Min time/rank Max time/rank Avg time/rank Time %
     main            0.000112      0.000112      0.000112  5.177994
       mainloop      0.000773      0.000773      0.000773 35.737402
+

include/caliper/cali.h

@@ -373,6 +373,23 @@ cali_begin_region(const char* name);
 void
 cali_end_region(const char* name);
 
+/**
+ * \brief Begin phase region \a name
+ *
+ * A phase marks high-level, long(er)-running code regions. While regular
+ * regions use the "region" attribute with annotation level 0, phase regions
+ * use the "phase" attribute with annotation level 4. Otherwise phases behave
+ * identical to regular Caliper regions.
+ */
+void
+cali_begin_phase(const char* name);
+
+/**
+ * \brief End phase region \a name
+ */
+void
+cali_end_phase(const char* name);
+
 /**
  * \brief Begin region where the value for \a attr is `true` on the blackboard.
  */

include/caliper/cali_macros.h

@@ -203,6 +203,18 @@ extern cali_id_t cali_annotation_attr_id;
 #define CALI_MARK_END(name) \
     cali_end_region(name)
 
+/// \brief Mark begin of a phase region
+///
+/// A phase marks high-level, long(er)-running code regions. While regular
+/// regions use the "region" attribute with annotation level 0, phase regions
+/// use the "phase" attribute with annotation level 4. Otherwise phases behave
+/// identical to regular Caliper regions.
+#define CALI_MARK_PHASE_BEGIN(name) \
+    cali_begin_phase(name)
+
+/// \brief Mark end of a phase region
+#define CALI_MARK_PHASE_END(name) \
+    cali_end_phase(name)
 /**
  * \} (group)
  */

include/caliper/common/Attribute.h

@@ -78,6 +78,9 @@ class Attribute
     bool is_global() const {
         return properties() & CALI_ATTR_GLOBAL;
     }
+    int  level() const {
+        return (properties() & CALI_ATTR_LEVEL_MASK) >> 16;
+    }
 
     static Attribute make_attribute(Node* node);
 

include/caliper/common/cali_types.h

@@ -123,10 +123,33 @@ typedef enum {
    * \a aggregate service. This flag replaces the previous
    * \a class.aggregatable meta-attribute.
    */
-   CALI_ATTR_AGGREGATABLE =  2048
+   CALI_ATTR_AGGREGATABLE =  2048,
+
+   /**
+    * \brief Annotation level 1
+    *
+    * Annotation levels can be used to describe and set the granularity of
+    * region annotations. Level 0 is the finest level, level 7 is the
+    * coarsest.
+    */
+   CALI_ATTR_LEVEL_1      = 0x10000,
+   /** \brief Annotation level 2 */
+   CALI_ATTR_LEVEL_2      = 0x20000,
+   /** \brief Annotation level 3 */
+   CALI_ATTR_LEVEL_3      = 0x30000,
+   /** \brief Annotation level 4 */
+   CALI_ATTR_LEVEL_4      = 0x40000,
+   /** \brief Annotation level 5 */
+   CALI_ATTR_LEVEL_5      = 0x50000,
+   /** \brief Annotation level 6 */
+   CALI_ATTR_LEVEL_6      = 0x60000,
+   /** \brief Annotation level 7 */
+   CALI_ATTR_LEVEL_7      = 0x70000
 } cali_attr_properties;
 
+#define CALI_ATTR_LEVEL_0    0x0
 #define CALI_ATTR_SCOPE_MASK 60
+#define CALI_ATTR_LEVEL_MASK 0x70000
 
 /**
  * \brief  Provides descriptive string of given attribute property flags, separated with ':'

src/caliper/api.cpp

@@ -17,6 +17,7 @@ cali_id_t cali_subscription_event_attr_id  = CALI_INV_ID;
 
 cali_id_t cali_loop_attr_id   = CALI_INV_ID;
 cali_id_t cali_region_attr_id = CALI_INV_ID;
+cali_id_t cali_phase_attr_id  = CALI_INV_ID;
 
 cali_id_t cali_alloc_fn_attr_id                 = CALI_INV_ID;
 cali_id_t cali_alloc_label_attr_id              = CALI_INV_ID;
@@ -36,6 +37,7 @@ namespace cali
     Attribute subscription_event_attr;
 
     Attribute region_attr;
+    Attribute phase_attr;
     Attribute loop_attr;
 
     void init_attribute_classes(Caliper* c) {
@@ -61,8 +63,11 @@ namespace cali
             c->create_attribute("loop", CALI_TYPE_STRING, CALI_ATTR_NESTED);
         region_attr =
             c->create_attribute("region", CALI_TYPE_STRING, CALI_ATTR_NESTED);
+        phase_attr =
+            c->create_attribute("phase", CALI_TYPE_STRING, CALI_ATTR_NESTED | CALI_ATTR_LEVEL_4);
 
         cali_region_attr_id = region_attr.id();
+        cali_phase_attr_id = phase_attr.id();
         cali_loop_attr_id = loop_attr.id();
     }
 }

src/caliper/cali.cpp

@@ -30,6 +30,7 @@ namespace cali
 {
 
 extern Attribute region_attr;
+extern Attribute phase_attr;
 
 }
 
@@ -385,9 +386,21 @@ void
 cali_end_region(const char* name)
 {
     Caliper c;
-    Variant v_n(name);
+    c.end_with_value_check(cali::region_attr, Variant(name));
+}
 
-    c.end_with_value_check(cali::region_attr, v_n);
+void
+cali_begin_phase(const char* name)
+{
+    Caliper c;
+    c.begin(cali::phase_attr, Variant(name));
+}
+
+void
+cali_end_phase(const char* name)
+{
+    Caliper c;
+    c.end_with_value_check(cali::phase_attr, Variant(name));
 }
 
 void

src/caliper/controllers/controllers.cpp

@@ -263,6 +263,20 @@ const char* builtin_option_specs = R"json(
       }
      ]
     },
+    {
+     "name"        : "level",
+     "type"        : "string",
+     "description" : "Minimum region level that triggers snapshots",
+     "category"    : "event",
+     "config"      : { "CALI_EVENT_REGION_LEVEL": "{}" }
+    },
+    {
+     "name"        : "include_branches",
+     "type"        : "string",
+     "description" : "Only take snapshots for branches with the given region names.",
+     "category"    : "event",
+     "config"      : { "CALI_EVENT_INCLUDE_BRANCHES": "{}" }
+    },
     {
      "name"        : "include_regions",
      "type"        : "string",

src/caliper/test/test_attribute.cpp

@@ -57,7 +57,7 @@ TEST(AttributeAPITest, ValidAttribute) {
     std::vector<std::string> props;
     util::split(std::string(buf), ':',  std::back_inserter(props));
 
-    std::vector<std::string> props_exp { "nested", "process_scope", "nomerge", "default" };
+    std::vector<std::string> props_exp { "nested", "process_scope", "nomerge", "default", "level_0" };
 
     for (auto s : props) {
         auto it = std::find(props_exp.begin(), props_exp.end(), s);

src/common/cali_types.c

@@ -45,7 +45,7 @@ cali_string2type(const char* str)
 }
 
 static const struct propmap_t {
-  const char* str; cali_attr_properties prop; int mask;
+  const char* str; int prop; int mask;
 } propmap[] = {
   { "default",       CALI_ATTR_DEFAULT,       CALI_ATTR_DEFAULT      },
   { "asvalue",       CALI_ATTR_ASVALUE,       CALI_ATTR_ASVALUE      },
@@ -59,6 +59,14 @@ static const struct propmap_t {
   { "global",        CALI_ATTR_GLOBAL,        CALI_ATTR_GLOBAL       },
   { "unaligned",     CALI_ATTR_UNALIGNED,     CALI_ATTR_UNALIGNED    },
   { "aggregatable",  CALI_ATTR_AGGREGATABLE,  CALI_ATTR_AGGREGATABLE },
+  { "level_0",       CALI_ATTR_LEVEL_0,       CALI_ATTR_LEVEL_MASK   },
+  { "level_1",       CALI_ATTR_LEVEL_1,       CALI_ATTR_LEVEL_MASK   },
+  { "level_2",       CALI_ATTR_LEVEL_2,       CALI_ATTR_LEVEL_MASK   },
+  { "level_3",       CALI_ATTR_LEVEL_3,       CALI_ATTR_LEVEL_MASK   },
+  { "level_4",       CALI_ATTR_LEVEL_4,       CALI_ATTR_LEVEL_MASK   },
+  { "level_5",       CALI_ATTR_LEVEL_5,       CALI_ATTR_LEVEL_MASK   },
+  { "level_6",       CALI_ATTR_LEVEL_6,       CALI_ATTR_LEVEL_MASK   },
+  { "level_7",       CALI_ATTR_LEVEL_7,       CALI_ATTR_LEVEL_MASK   },
   { 0, CALI_ATTR_DEFAULT, CALI_ATTR_DEFAULT }
 };