Collectors Overview

Performance profiles originate either from the user’s own means (i.e. by building their own collectors and generating the profiles w.r.t Specification of Profile Format) or using one of the collectors from Perun’s tool suite.

Perun can collect profiling data in two ways:

1. By Directly running collectors through perun collect command, that generates profile using a single collector with given collector configuration. The resulting profiles are not postprocessed in any way.

2. By Using job specification either as a single run of batch of profiling jobs using perun run job or according to the specification of the so-called job matrix using perun run matrix command.

The format of resulting profiles is w.r.t. Specification of Profile Format. The origin is set to the current HEAD of the wrapped repository. However, note that uncommited changes may skew the resulting profile and Perun cannot guard your project against this. Further, collector_info is filled with configuration of the run collector.

All automatically generated profiles are stored in the .perun/jobs/ directory as a file with the .perf extension. The filename is by default automatically generated according to the following template:

bin-collector-workload-timestamp.perf

Profiles can be further registered and stored in persistent storage using perun add command. Then both stored and pending profiles (i.e. those not yet assigned) can be postprocessed using the perun postprocessby or interpreted using available interpretation techniques using perun show. Refer to Command Line Interface, Postprocessors Overview and Visualizations Overview for more details about running command line commands, capabilities of postprocessors and interpretation techniques respectively. Internals of perun storage is described in Perun Internals.

Supported Collectors

Perun’s tool suite currently contains the following three collectors:

1. Trace Collector (authored by Jirka Pavela), collects running times of C/C++ functions along with the size of the structures they were executed on. E.g. this collects resources such that function search over the class SingleLinkedList took 100ms on single linked list with one million elements. Examples shows concrete examples of profiles generated by Trace Collector

2. Memory Collector (authored by Radima Podola), collects specifications of allocations in C/C++ programs, such as the type of allocation or the full call trace. Examples shows concrete generated profiles by Memory Collector.

3. Time Collector, collects overall running times of arbitrary commands. Internally implemented as a simple wrapper over time utility

4. Bounds Collector, collects bounds of integer and, to some extent, heap-manipulating loops represented as so called ranking function. The collectors works as a wrapper over the Loopus tool. The collection is limited to source codes only, written in subset of C language, i.e. for some construction it might return wrong bounds (e.g. for switch statement). Moreover, the runtime of bounds depends on Z3 library.

All of the listed collectors can be run from command line. For more information about command line interface for individual collectors refer to Collect units.

Collector modules are implementation independent (hence, can be written in any language) and only requires simple python interface registered within Perun. For brief tutorial how to create and register new collectors in Perun refer to Creating your own Collector.

Trace Collector

Trace collector collects running times of C/C++ functions. The collected data are suitable for further postprocessing using the regression analysis and visualization by scatter plots.

Overview and Command Line Interface

perun collect trace

Generates trace performance profile, capturing running times of function depending on underlying structural sizes.

* Limitations: C/C++ binaries

* Metric: mixed (captures both time and size consumption)

* Dependencies: SystemTap (+ corresponding requirements e.g. kernel -dbgsym version)

* Default units: us for time, element number for size

Example of collected resources is as follows:

{
    "amount": 11,
    "subtype": "time delta",
    "type": "mixed",
    "uid": "SLList_init(SLList*)",
    "structure-unit-size": 0
}

Trace collector provides various collection strategies which are supposed to provide sensible default settings for collection. This allows the user to choose suitable collection method without the need of detailed rules / sampling specification. Currently supported strategies are:

* userspace: This strategy traces all userspace functions / code blocks without

the use of sampling. Note that this strategy might be resource-intensive.

* all: This strategy traces all userspace + library + kernel functions / code blocks

that are present in the traced binary without the use of sampling. Note that this strategy

might be very resource-intensive.

* u_sampled: Sampled version of the userspace strategy. This method uses sampling

to reduce the overhead and resources consumption.

* a_sampled: Sampled version of the all strategy. Its goal is to reduce the

overhead and resources consumption of the all method.

* custom: User-specified strategy. Requires the user to specify rules and sampling

manually.

Note that manually specified parameters have higher priority than strategy specification and it is thus possible to override concrete rules / sampling by the user.

The collector interface operates with two seemingly same concepts: (external) command and binary. External command refers to the script, executable, makefile, etc. that will be called / invoked during the profiling, such as ‘make test’, ‘run_script.sh’, ‘./my_binary’. Binary, on the other hand, refers to the actual binary or executable file that will be profiled and contains specified functions / USDT probes etc. It is expected that the binary will be invoked / called as part of the external command script or that external command and binary are the same.

The interface for rules (functions, USDT probes) specification offers a way to specify profiled locations both with sampling or without it. Note that sampling can reduce the overhead imposed by the profiling. USDT rules can be further paired - paired rules act as a start and end point for time measurement. Without a pair, the rule measures time between each two probe hits. The pairing is done automatically for USDT locations with convention <name> and <name>_end or <name>_END - or other commonly found suffixes. Otherwise, it is possible to pair rules by the delimiter ‘#’, such as <name1>#<name2>.

Trace profiles are suitable for postprocessing by Regression Analysis since they capture dependency of time consumption depending on the size of the structure. This allows one to model the estimation of trace of individual functions.

Scatter plots are suitable visualization for profiles collected by trace collector, which plots individual points along with regression models (if the profile was postprocessed by regression analysis). Run perun show scatter --help or refer to Scatter Plot for more information about scatter plots.

Refer to Trace Collector for more thorough description and examples of trace collector.

perun collect trace [OPTIONS]

Options

-e, --engine <engine>

Sets the data collection engine to be used: - stap: the SystemTap framework - ebpf: the eBPF framework

Options:

stap | ebpf

-s, --strategy <strategy>

Required Select strategy for probing the binary. See documentation for detailed explanation for each strategy.

Options:

userspace | all | u_sampled | a_sampled | custom

-f, --func <func>

Set the probe point for the given function as <lib>#<func>#<sampling>.

-u, --usdt <usdt>

Set the probe point for the given USDT location as <lib>#<usdt>#<sampling>.

-d, --dynamic <dynamic>

Set the probe point for the given dynamic location as <lib>#<cl>#<sampling>.

-g, --global-sampling <global_sampling>

Set the global sample for all probes, sampling parameter for specific rules have higher priority.

--with-usdt, --no-usdt

The selected strategy will also extract and profile USDT probes.

-b, --binary <binary>

The profiled executable. If not set, then the command is considered to be the profiled executable and is used as a binary parameter.

-l, --libs <libs>

Additional libraries that should also be profiled.

-t, --timeout <timeout>

Set time limit (in seconds) for the profiled command, i.e. the command will be terminated after reaching the time limit. Useful for, e.g., endless commands.

-z, --zip-temps

Zip and compress the temporary files (SystemTap log, raw performance data, watchdog log, etc.) into the Perun log directory before deleting them.

-k, --keep-temps

Do not delete the temporary files in the file system.

-vt, --verbose-trace

Set the trace file output to be more verbose, useful for debugging.

-q, --quiet

Reduces the verbosity of the collector info messages.

-w, --watchdog

Enable detailed logging of the whole collection process.

-o, --output-handling <output_handling>

Sets the output handling of the profiled command: - default: the output is displayed in the terminal - capture: the output is being captured into a file as well as displayed in the terminal (note that buffering causes a delay in the terminal output) - suppress: redirects the output to the DEVNULL

Options:

default | capture | suppress

-i, --diagnostics

Enable detailed surveillance mode of the collector. The collector turns on detailed logging (watchdog), verbose trace, capturing output etc. and stores the logs and files in an archive (zip-temps) in order to provide as much diagnostic data as possible for further inspection.

-sc, --stap-cache-off

Disables the SystemTap caching of compiled scripts.

-np, --no-profile

Tracer will not transform and save processed data into a perun profile.

-mcg, --extract-mixed-cg

DEBUG: Extract mixed CG.

-cg, --only-extract-cg

Tracer will only extract the CG of the current project version and terminate.

-mt, --max-simultaneous-threads <max_simultaneous_threads>

DEBUG: Maximum number of expected simultaneous threads when sampling is on.

-nds, --no-ds-update

DEBUG: Disables Dynamic Stats updates

Examples

{
  "resources": {
    "SLList_insert(SLList*, int)#0": {
      "amount": [
        1, 0, 1, 1
      ],
      "structure-unit-size": [
        0, 1, 2, 3
      ]
    },
    "SLList_destroy(SLList*)#0": {
      "amount": [
        1
      ],
      "structure-unit-size": [
        4
      ]
    },
    "SLList_init(SLList*)#0": {
      "amount": [
        6
      ],
      "structure-unit-size": [
        0
      ]
    },
    "SLList_search(SLList*, int)#0": {
      "amount": [
        0
      ],
      "structure-unit-size": [
        0
      ]
    }
  },
  "header": {
    "workload": "",
    "type": "mixed",
    "units": {
      "mixed(time delta)": "us"
    },
    "params": "",
    "cmd": "../stap-collector/tst"
  },
  "models": [],
  "collector_info": {
    "params": {
      "global_sampling": null,
      "sampling": [
        {
          "func": "SLList_insert",
          "sample": 1
        },
        {
          "func": "func1",
          "sample": 1
        }
      ],
      "rules": [
        "SLList_init",
        "SLList_insert",
        "SLList_search",
        "SLList_destroy"
      ],
      "method": "custom"
    },
    "name": "complexity"
  },
  "resource_type_map": {
    "SLList_insert(SLList*, int)#0": {
      "subtype": "time delta",
      "uid": "SLList_insert(SLList*, int)",
      "time": "6.8e-05s",
      "type": "mixed"
    },
    "SLList_destroy(SLList*)#0": {
      "subtype": "time delta",
      "uid": "SLList_destroy(SLList*)",
      "time": "6.8e-05s",
      "type": "mixed"
    },
    "SLList_init(SLList*)#0": {
      "subtype": "time delta",
      "uid": "SLList_init(SLList*)",
      "time": "6.8e-05s",
      "type": "mixed"
    },
    "SLList_search(SLList*, int)#0": {
      "subtype": "time delta",
      "uid": "SLList_search(SLList*, int)",
      "time": "6.8e-05s",
      "type": "mixed"
    }
  },
  "postprocessors": [],
  "origin": "f7f3dcea69b97f2b03c421a223a770917149cfae"
}

The above is an example of profiled data for the simple manipulation with program with single linked list. Profile captured running times of three functions—SLList_init (an initialization of single linked list), SLList_destroy (a destruction of single linked list) and SLList_search (search over the single linked list).

Highlighted lines show important keys and regions in the profile, e.g. the origin, collector_info or resources.

The Scatter Plot above shows the example of visualization of trace profile. Each points corresponds to the running time of the SLList_search function over the single linked list with structure-unit-size elements. Elements are further interleaved with set of models obtained by Regression Analysis. The light green line corresponds to linear model, which seems to be the most fitting to model the performance of given function.

The Bars Plot above shows the overall sum of the running times for each structure-unit-size for the SLList_search function. The interpretation highlights that the most of the consumed running time were over the single linked lists with 41 elements.

The Flow Plot above shows the trend of the average running time of the SLList_search function depending on the size of the structure we execute the search on.

Memory Collector

Memory collector collects allocations of C/C++ functions, target addresses of allocations, type of allocations, etc.

Overview and Command Line Interface

perun collect memory

Generates memory performance profile, capturing memory allocations of different types along with target address and full call trace.

* Limitations: C/C++ binaries

* Metric: memory

* Dependencies: libunwind.so and custom libmalloc.so

* Default units: B for memory

The following snippet shows the example of resources collected by memory profiler. It captures allocations done by functions with more detailed description, such as the type of allocation, trace, etc.

{
    "type": "memory",
    "subtype": "malloc",
    "address": 19284560,
    "amount": 4,
    "trace": [
        {
            "source": "../memory_collect_test.c",
            "function": "main",
            "line": 22
        },
    ],
    "uid": {
        "source": "../memory_collect_test.c",
        "function": "main",
        "line": 22
    }
},

Refer to Memory Collector for more thorough description and examples of memory collector.

perun collect memory [OPTIONS]

Options

-s, --sampling <sampling>

Sets the sampling interval for profiling the allocations. I.e. memory snapshots will be collected each <sampling> seconds.

--no-source <no_source>

Will exclude allocations done from <no_source> file during the profiling.

--no-func <no_func>

Will exclude allocations done by <no func> function during the profiling.

-a, --all

Will record the full trace for each allocation, i.e. it will include all allocators and even unreachable records.

Examples

{
  "resources": {
    "../memory_collect_test.c:main:22#0": {
      "amount": [
        4
      ],
      "address": [
        19284560
      ]
    },
    "../memory_collect_test.c:main:27#0": {
      "amount": [
        0
      ],
      "address": [
        19284560
      ]
    }
  },
  "header": {
    "units": {
      "memory": "B"
    },
    "cmd": "./mct",
    "workload": "",
    "params": "",
    "type": "memory"
  },
  "models": [],
  "collector_info": {
    "params": {
      "all": false,
      "sampling": 0.025,
      "no_func": null,
      "no_source": null
    },
    "name": "memory"
  },
  "resource_type_map": {
    "../memory_collect_test.c:main:22#0": {
      "snapshot": 0,
      "time": "0.025000",
      "type": "memory",
      "trace": [
        {
          "function": "malloc",
          "line": 0,
          "source": "unreachable"
        },
        {
          "function": "main",
          "line": 22,
          "source": "../memory_collect_test.c"
        },
        {
          "function": "__libc_start_main",
          "line": 0,
          "source": "unreachable"
        },
        {
          "function": "_start",
          "line": 0,
          "source": "unreachable"
        }
      ],
      "subtype": "malloc",
      "uid": {
        "function": "main",
        "line": 22,
        "source": "../memory_collect_test.c"
      }
    },
    "../memory_collect_test.c:main:27#0": {
      "snapshot": 0,
      "time": "0.025000",
      "type": "memory",
      "trace": [
        {
          "function": "free",
          "line": 0,
          "source": "unreachable"
        },
        {
          "function": "main",
          "line": 27,
          "source": "../memory_collect_test.c"
        },
        {
          "function": "__libc_start_main",
          "line": 0,
          "source": "unreachable"
        },
        {
          "function": "_start",
          "line": 0,
          "source": "unreachable"
        }
      ],
      "subtype": "free",
      "uid": {
        "function": "main",
        "line": 27,
        "source": "../memory_collect_test.c"
      }
    }
  },
  "postprocessors": [],
  "origin": "74288675e4074f1ad5bbb0d3b3253911ab42267a"
}

The above is an example of profiled data on a simple binary, which makes several minor allocations. Profile shows a simple allocation followed by deallocation and highlights important keys and regions in the memory profiles, e.g. the origin, collector_info or resources

The Flow Plot above shows the mean of allocated amounts per each allocation site (i.e. uid) in stacked mode. The stacking of the means clearly shows, where the biggest allocations where made during the program run.

The Flame Graph is an efficient visualization of inclusive consumption of resources. The width of the base of one flame shows the bottleneck and hotspots of profiled binaries.

Time Collector

Time collector collects is a simple wrapper over the time utility. There is nothing special about this, the profiles are simple, and no visualization is especially suitable for this mode.

Overview and Command Line Interface

perun collect time

Generates time performance profile, capturing overall running times of the profiled command.

* Limitations: none

* Metric: running time

* Dependencies: none

* Default units: s

This is a wrapper over the time linux utility and captures resources in the following form:

{
    "amount": 0.59,
    "type": "time",
    "subtype": "sys",
    "uid": cmd
    "order": 1
}

Refer to Time Collector for more thorough description and examples of trace collector.

perun collect time [OPTIONS]

Options

-w, --warmup <int>

Before the actual timing, the collector will execute <int> warm-up executions.

-r, --repeat <int>

The timing of the given binaries will be repeated <int> times.

Examples

{
  "origin": "8de6cd99e4dc36cd73a2af906cde12456e96d9f1",
  "header": {
    "type": "time",
    "params": "",
    "units": {
      "time": "s"
    },
    "cmd": "./list_search",
    "workload": "100000"
  },
  "collector_info": {
    "params": {
      "repeat": 2,
      "warmup": 3
    },
    "name": "time"
  },
  "postprocessors": [],
  "global": {
    "timestamp": 0.565476655960083,
    "resources": [
      {
        "subtype": "real",
        "uid": "./list_search",
        "order": 1,
        "type": "time",
        "amount": 0.26
      },
      {
        "subtype": "user",
        "uid": "./list_search",
        "order": 1,
        "type": "time",
        "amount": 0.25
      },
      {
        "subtype": "sys",
        "uid": "./list_search",
        "order": 1,
        "type": "time",
        "amount": 0.0
      },
      {
        "subtype": "real",
        "uid": "./list_search",
        "order": 2,
        "type": "time",
        "amount": 0.27
      },
      {
        "subtype": "user",
        "uid": "./list_search",
        "order": 2,
        "type": "time",
        "amount": 0.28
      },
      {
        "subtype": "sys",
        "uid": "./list_search",
        "order": 2,
        "type": "time",
        "amount": 0.0
      }
    ]
  },
}

The above is an example of profiled data using the time wrapper with important regions and keys highlighted. The given command was profiled two times.

Bounds Collector

Automatic analysis of resource bounds of C programs.

Bounds collector employs a technique of Loopus tool (see loopus-site), which performs an amortized analysis of input C program. Loopus is limited to integer programs only, and for each function and for each loop it computes a symbolic bound (e.g. 2*n + max(0, m)). Moreover, it computes the big-O notation highlighting the main source of the complexity.

Overview and Command Line Interface

perun collect bounds

Generates memory performance profile, capturing memory allocations of

different types along with target address and full call trace.

• Limitations: C/C++ binaries

• Metric: memory

• Dependencies: libunwind.so and custom libmalloc.so

• Default units: B for memory

The following snippet shows the example of resources collected by memory profiler. It captures allocations done by functions with more detailed description, such as the type of allocation, trace, etc.

{
        "uid": {
            "source": "../test.c",
            "function": "main",
            "line": 22
            "column": 40
        }
        "bound": "1 + max(0, (k + -1))",
        "class": "O(n^1)"
        "type": "bound",
}

Refer to :ref:`collectors-bounds` for more thorough description and
examples of `bounds` collector.

perun collect bounds [OPTIONS]

Options

-s, --source, --src <path>

Source C file that will be analyzed.

-d, --source-dir <dir>

Directory, where source C files are stored. All of the existing files with valid extensions (.c).

Examples

{
  "origin": "409dd7468a328038c9a1ea5a6a0f7baa89f8997a",
  "header": {
    "type": "bound",
    "args": "",
    "workload": "",
    "units": {
      "bound": "iterations"
    },
    "cmd": "partitioning"
  },
  "resources": {
    "int_partitioning.c:partitioning:34:42#0": {},
    "int_partitioning.c:partitioning:49:60#0": {},
    "int_partitioning.c:partitioning:64:69#0": {},
    "int_partitioning.c:partitioning:18:4#0": {},
    "int_partitioning.c:partitioning:55:58#0": {}
  },
  "models": [],
  "postprocessors": [],
  "collector_info": {
    "params": {
      "sources": [
        "int_partitioning.c"
      ],
      "workload": "",
      "source_dir": [],
      "source": [
        "int_partitioning.c"
      ]
    },
    "name": "bounds"
  },
  "resource_type_map": {
    "int_partitioning.c:partitioning:34:42#0": {
      "uid": {
        "line": 34,
        "column": 42,
        "source": "int_partitioning.c",
        "function": "partitioning"
      },
      "type": "local bound",
      "bound": "1 + max(0, (k + -1))",
      "time": "0.0",
      "class": "O(n^1)"
    },
    "int_partitioning.c:partitioning:49:60#0": {
      "uid": {
        "line": 49,
        "column": 60,
        "source": "int_partitioning.c",
        "function": "partitioning"
      },
      "type": "local bound",
      "bound": "2 + max(0, (k + -1))",
      "time": "0.0",
      "class": "O(n^1)"
    },
    "int_partitioning.c:partitioning:64:69#0": {
      "uid": {
        "line": 64,
        "column": 69,
        "source": "int_partitioning.c",
        "function": "partitioning"
      },
      "type": "local bound",
      "bound": "2 + max(0, (k + -1))",
      "time": "0.0",
      "class": "O(n^1)"
    },
    "int_partitioning.c:partitioning:18:4#0": {
      "uid": {
        "line": 18,
        "column": 4,
        "source": "int_partitioning.c",
        "function": "partitioning"
      },
      "type": "total bound",
      "bound": "6 + 4 × max(0, (k + -1))",
      "time": "0.0",
      "class": "O(n^1)"
    },
    "int_partitioning.c:partitioning:55:58#0": {
      "uid": {
        "line": 55,
        "column": 58,
        "source": "int_partitioning.c",
        "function": "partitioning"
      },
      "type": "local bound",
      "bound": "1 + max(0, (k + -1))",
      "time": "0.0",
      "class": "O(n^1)"
    }
  }
}

The above is an example of profiled data using the bounds with important regions and keys highlighted. The bounds corresponds to the program listed below, which contains four highlighted loops. For each loop we have a local bound that is represented as a ranking function based on input function parameters. For each bound, we also list its class, i.e. the highest polynom of the ranking function, or Big-O complexity. In case, the complexity cannot be inferred, the Loopus returns failure and we report infinite bound, which is safe approximation. Each function then gets a cummulative total bound, that represents the whole complexity of the function.

int partitioning(unsigned int k) {
    TList *list, *temp;

    unsigned int list_next_NULL;
    unsigned int list_next_p;
    unsigned int p_next_NULL;
    unsigned int x_next_NULL;
    unsigned int y_next_x;
    list = malloc(sizeof(TList));
    list->next = NULL;

    // Create nondeterminstic list
    TList *p = list;
    list_next_NULL = 1;
    list_next_p = 0;
    while(k > 1) {
        temp = malloc(sizeof(TList));
        temp->next = NULL;
        p->next = temp;
        p = temp;
        list_next_NULL = list_next_p + 2;
        list_next_p += 1;
        --k;
    }

    // Traverse the list
    TList* x = list;
    TList* y = x;
    x_next_NULL = list_next_NULL;
    y_next_x = 0;
    while(x_next_NULL > 0 && x != NULL) {
        x = x->next;
        x_next_NULL -= 1;
        y_next_x += 1;
        // The end will always jump out
        if(NONDET) {
            while(y_next_x > 0 && y != x) {
                y = y->next;
                y_next_x -= 1;
            }
        }
    }

    p = list;
    p_next_NULL = list_next_NULL;
    while(p_next_NULL > 0 && p != NULL) {
        temp = p;
        p = p->next;
        free(temp);
        p_next_NULL -= 1;
    }

    return 0;
}

Creating your own Collector

New collectors can be registered within Perun in several steps. Internally they can be implemented in any programming language and in order to work with Perun requires three phases to be specified as given in Collectors Overview—before(), collect() and after(). Each new collector requires a interface module run.py, which contains the three functions and, moreover, a cli API for Click.

You can register your new collector as follows:

1. Run perun utils create collect mycollector to generate a new modules in perun/collect directory with the following structure. The command takes a predefined templates for new collectors and creates __init__.py and run.py according to the supplied command line arguments (see Utility Commands for more information about interface of perun utils create command):

   /perun
   |-- /collect
       |-- /mycollector
           |-- __init__.py
           |-- run.py
       |-- /trace
       |-- /memory
       |-- /time
       |-- __init__.py
   

2. First, implement the __init__.py file, including the module docstring with brief collector descriptions and definitions of constants that are used for automatic setting of profiles (namely the collector_info) which has the following structure:

"""..."""

COLLECTOR_TYPE = "time|memory|mixed"
COLLECTOR_DEFAULT_UNITS = {"type": "unit"}

3. Next, implement the run.py module with collect() function, (optionally with before() and after()). The collect() function should do the actual collection of the profiling data over the given configuration. Each function should return the integer status of the phase, the status message (used in case of error) and dictionary including params passed to additional phases and ‘profile’ with dictionary w.r.t Specification of Profile Format.

def before(**kwargs):
    """(optional)"""
    return STATUS, STATUS_MSG, dict(kwargs)


def collect(**kwargs):
    """..."""
    return STATUS, STATUS_MSG, dict(kwargs)


def after(**kwargs):
    """(optional)"""
    return STATUS, STATUS_MSG, dict(kwargs)

4. Additionally implement the command line interface function in run.py, named the same as your collector. This function will is called from command line as perun collect mycollector and is based on Click library.

--- /home/runner/work/perun/perun/docs/_static/templates/collectors_run.py
+++ /home/runner/work/perun/perun/docs/_static/templates/collectors_run_api.py
@@ -1,3 +1,8 @@
+import click
+
+import perun.logic.runner as runner
+
+
 def before(**kwargs):
     """(optional)"""
     return STATUS, STATUS_MSG, dict(kwargs)
@@ -11,3 +16,10 @@
 def after(**kwargs):
     """(optional)"""
     return STATUS, STATUS_MSG, dict(kwargs)
+
+
+@click.command()
+@click.pass_context
+def mycollector(ctx, **kwargs):
+    """..."""
+    runner.run_collector_from_cli_context(ctx, "mycollector", kwargs)

5. Finally register your newly created module in function get_supported_module_names located in perun.utils.common.cli_kit.py:

--- /home/runner/work/perun/perun/docs/_static/templates/supported_module_names.py
+++ /home/runner/work/perun/perun/docs/_static/templates/supported_module_names_collectors.py
@@ -4,7 +4,7 @@
         error(f"trying to call get_supported_module_names with incorrect package '{package}'")
     return {
         "vcs": ["git", "svs"],
-        "collect": ["trace", "memory", "time"],
+        "collect": ["trace", "memory", "time", "mycollector"],
         "postprocess": [
             "moving-average",
             "kernel-regression",

6. Preferably, verify that registering did not break anything in the Perun and if you are not using the developer installation, then reinstall Perun:

   make test
   make install
   

7. At this point you can start using your collector either using perun collect or using the following to set the job matrix and run the batch collection of profiles:

   perun config --edit
   perun run matrix
   

8. If you think your collector could help others, please, consider making Pull Request.