Support external (i.e. user-defined) trace annotations

[jrmadsen]

• tweaked the python examples to be more balanced
• updated the user-api example to conform to user API changes
• moved the get/set for State and ThreadState to state.{hpp,cpp}
• introduced user-provided trace annotations
• added perfetto python category
• moved coverage impl files around
• created enumerations for mapping category enums to category types
• created enumerations for mapping annotation type enums to annotation values
• moved tracing::add_perfetto_annotations to tracing/annotation.hpp
• utility make_index_sequence_range
• libomnitrace-dl: omnitrace_push_category_region
• libomnitrace-dl: omnitrace_pop_category_region
• libomnitrace-user: omnitrace_user_push_annotated_region
• libomnitrace-user: omnitrace_user_pop_annotated_region
• libpyomnitrace: support extra annotations via annotate_trace config value
  • filename
  • line
  • last attempted instr in bytecode (lasti)
  • argcount
  • num local variables
  • stacksize
• omnitrace-python: -a / --annotate-traces option

Perfetto Python Annotations

Updated User API

#include <omnitrace/user.h>

int
custom_push_region(const char* name);

namespace
{
// instance holding custom callbacks
omnitrace_user_callbacks_t custom_callbacks   = OMNITRACE_USER_CALLBACKS_INIT;
// instance holding former callbacks
omnitrace_user_callbacks_t original_callbacks = OMNITRACE_USER_CALLBACKS_INIT;
}  // namespace

int
main(int argc, char** argv)
{
    // set the callback for pushing a region
    custom_callbacks.push_region = &custom_push_region;
    // update the config
    //   OMNITRACE_USER_UNION_CONFIG will only update config with non-null callbacks
    //   OMNITRACE_USER_REPLACE_CONFIG will swap in entire config
    omnitrace_user_configure(OMNITRACE_USER_UNION_CONFIG, custom_callbacks,
                             &original_callbacks);

    // ... etc. ...
    return 0;
}

int
custom_push_region(const char* name)
{
    // check we have the push_annotated_region callback
    if(!original_callbacks.push_annotated_region)
        return OMNITRACE_USER_ERROR_NO_BINDING;

    // store data for annotation
    int32_t _err = errno;
    char*   _msg = nullptr;
    char    _buff[1024];
    if(_err != 0) _msg = strerror_r(_err, _buff, sizeof(_buff));

    // annotate the global errno and if non-zero, annotate the error string
    omnitrace_annotation_t _annotations[] = {
        { "errno", OMNITRACE_INT32, &_err }, { "strerror", OMNITRACE_STRING, _msg }
    };

    errno = 0;  // reset errno
    return (*original_callbacks.push_annotated_region)(
        name, _annotations, sizeof(_annotations) / sizeof(omnitrace_annotation_t));
}

[jrmadsen]

@koomie Looking for feedback on how the user-defined annotations should be specified. Example at the bottom of the first comment. LMK if you have any questions.