Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 36763C433FE for ; Mon, 17 Jan 2022 23:22:17 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S235380AbiAQXWQ (ORCPT ); Mon, 17 Jan 2022 18:22:16 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:45882 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S235370AbiAQXWQ (ORCPT ); Mon, 17 Jan 2022 18:22:16 -0500 Received: from ams.source.kernel.org (ams.source.kernel.org [IPv6:2604:1380:4601:e00::1]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 2085BC061574 for ; Mon, 17 Jan 2022 15:22:16 -0800 (PST) Received: from smtp.kernel.org (relay.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ams.source.kernel.org (Postfix) with ESMTPS id A6EF6B811D6 for ; Mon, 17 Jan 2022 23:22:14 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id 4A6E5C36AEF; Mon, 17 Jan 2022 23:22:13 +0000 (UTC) Received: from rostedt by gandalf.local.home with local (Exim 4.95) (envelope-from ) id 1n9bKG-006fYu-9L; Mon, 17 Jan 2022 18:22:12 -0500 From: Steven Rostedt To: linux-trace-devel@vger.kernel.org Cc: Steven Rostedt Subject: [PATCH 1/3] libtracefs: Split up libtracefs-hist.txt man page Date: Mon, 17 Jan 2022 18:22:08 -0500 Message-Id: <20220117232210.1589656-2-rostedt@goodmis.org> X-Mailer: git-send-email 2.33.0 In-Reply-To: <20220117232210.1589656-1-rostedt@goodmis.org> References: <20220117232210.1589656-1-rostedt@goodmis.org> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Precedence: bulk List-ID: X-Mailing-List: linux-trace-devel@vger.kernel.org Man page generation appears to not allow more than 9 functions to be described before it starts spitting out errors. As libtracefs-hist.txt has 14 functions (and it did not even include tracefs_hist_append_filter() to make it 15), split out the functions: tracefs_hist_add_sort_key() tracefs_hist_set_sort_key() tracefs_hist_sort_key_direction() tracefs_hist_append_filter() tracefs_hist_echo_cmd() tracefs_hist_command() tracefs_hist_get_name() tracefs_hist_get_event() tracefs_hist_get_system() into their own man page: libtracefs-hist-mod.txt and this removes the errors for libtracefs-hist.txt. Signed-off-by: Steven Rostedt --- Documentation/libtracefs-hist-mod.txt | 540 ++++++++++++++++++++++++++ Documentation/libtracefs-hist.txt | 130 +------ 2 files changed, 542 insertions(+), 128 deletions(-) create mode 100644 Documentation/libtracefs-hist-mod.txt diff --git a/Documentation/libtracefs-hist-mod.txt b/Documentation/libtracefs-hist-mod.txt new file mode 100644 index 000000000000..732ae2b62e88 --- /dev/null +++ b/Documentation/libtracefs-hist-mod.txt @@ -0,0 +1,540 @@ +libtracefs(3) +============= + +NAME +---- +tracefs_hist_add_sort_key, tracefs_hist_set_sort_key, tracefs_hist_sort_key_direction, +tracefs_hist_append_filter, tracefs_hist_echo_cmd, tracefs_hist_command, +tracefs_hist_get_name, tracefs_hist_get_event, tracefs_hist_get_system - Update and describe an event histogram + +SYNOPSIS +-------- +[verse] +-- +*#include * + +int *tracefs_hist_add_sort_key*(struct tracefs_hist pass:[*]_hist_, + const char pass:[*]_sort_key_); + +int *tracefs_hist_set_sort_key*(struct tracefs_hist pass:[*]_hist_, + const char pass:[*]_sort_key_, _..._); +int *tracefs_hist_sort_key_direction*(struct tracefs_hist pass:[*]_hist_, + const char pass:[*]_sort_key_, + enum tracefs_hist_sort_direction _dir_); + +int *tracefs_hist_add_name*(struct tracefs_hist pass:[*]_hist_, const char pass:[*]_name_); + +int *tracefs_hist_append_filter*(struct tracefs_hist pass:[*]_hist_, + enum tracefs_filter _type_, + const char pass:[*]_field_, + enum tracefs_compare _compare_, + const char pass:[*]_val_); + +int *tracefs_hist_echo_cmd*(struct trace_seq pass:[*]_s_, struct tracefs_instance pass:[*]_instance_, + struct tracefs_hist pass:[*]_hist_, + enum tracefs_hist_command _command_); + +int *tracefs_hist_command*(struct tracefs_instance pass:[*]_instance_, + struct tracefs_hist pass:[*]_hist_, + enum tracefs_hist_command _command_); + +const char pass:[*]*tracefs_hist_get_name*(struct tracefs_hist pass:[*]_hist_); + +const char pass:[*]*tracefs_hist_get_event*(struct tracefs_hist pass:[*]_hist_); + +const char pass:[*]*tracefs_hist_get_system*(struct tracefs_hist pass:[*]_hist_); + +-- + +DESCRIPTION +----------- +Event histograms are created by the trigger file in the event directory. +The syntax can be complex and difficult to get correct. This API handles the +syntax, and facilitates the creation and interaction with the event histograms. +See https://www.kernel.org/doc/html/latest/trace/histogram.html for more information. + +*tracefs_hist_add_sort_key*() will add a key to sort on. The _hist_ is the +histogram descriptor to add the sort key to. The _sort_key_ is a string +that must match either an already defined key of the histogram, or an already +defined value. If _hist_ already has sorting keys (previously added) the new +_sort_key_ will have lower priority(be secondary or so on) when sorting. + +*tracefs_hist_set_sort_key*() will reset the list of key to sort on. The _hist_ is +the histogram descriptor to reset the sort key to. The _sort_key_ is a string +that must match either an already defined key of the histogram, or an already +defined value. Multiple sort keys may be added to denote a secondary, sort order +and so on, but all sort keys must match an existing key or value, or be +TRACEFS_HIST_HITCOUNT. The last parameter of *tracefs_hist_add_sort_key*() must +be NULL. + +*tracefs_hist_sort_key_direction*() allows to change the direction of an +existing sort key of _hist_. The _sort_key_ is the sort key to change, and +_dir_ can be either TRACEFS_HIST_SORT_ASCENDING or TRACEFS_HIST_SORT_DESCENDING, +to make the direction of the sort key either ascending or descending respectively. + +*tracefs_hist_add_name*() adds a name to a histogram. A histogram may be +named and if the name matches between more than one event, and they have +compatible keys, the multiple histograms with the same name will be merged +into a single histogram (shown by either event's hist file). The _hist_ +is the histogram to name, and the _name_ is the name to give it. + +*tracefs_hist_append_filter*() creates a filter or appends to it for the +histogram event. Depending on _type_, it will build a string of tokens for +parenthesis or logic statements, or it may add a comparison of _field_ +to _val_ based on _compare_. + +If _type_ is: +*TRACEFS_FILTER_COMPARE* - See below +*TRACEFS_FILTER_AND* - Append "&&" to the filter +*TRACEFS_FILTER_OR* - Append "||" to the filter +*TRACEFS_FILTER_NOT* - Append "!" to the filter +*TRACEFS_FILTER_OPEN_PAREN* - Append "(" to the filter +*TRACEFS_FILTER_CLOSE_PAREN* - Append ")" to the filter + +_field_, _compare_, and _val_ are ignored unless _type_ is equal to +*TRACEFS_FILTER_COMPARE*, then _compare_ will be used for the following: + +*TRACEFS_COMPARE_EQ* - _field_ == _val_ + +*TRACEFS_COMPARE_NE* - _field_ != _val_ + +*TRACEFS_COMPARE_GT* - _field_ > _val_ + +*TRACEFS_COMPARE_GE* - _field_ >= _val_ + +*TRACEFS_COMPARE_LT* - _field_ < _val_ + +*TRACEFS_COMPARE_LE* - _field_ +#include +#include + +enum commands { + START, + PAUSE, + CONT, + RESET, + DELETE, + SHOW, +}; + +static void parse_system_event(char *group, char **system, char **event) +{ + *system = strtok(group, "/"); + *event = strtok(NULL, "/"); + if (!*event) { + *event = *system; + *system = NULL; + } +} + +static int parse_keys(char *keys, struct tracefs_hist_axis **axes) +{ + char *sav = NULL; + char *key; + int cnt = 0; + + for (key = strtok_r(keys, ",", &sav); key; key = strtok_r(NULL, ",", &sav)) { + struct tracefs_hist_axis *ax; + char *att; + + ax = realloc(*axes, sizeof(*ax) * (cnt + 2)); + if (!ax) { + perror("Failed to allocate axes"); + exit(-1); + } + ax[cnt].key = key; + ax[cnt].type = 0; + ax[cnt + 1].key = NULL; + ax[cnt + 1].type = 0; + + *axes = ax; + + att = strchr(key, '.'); + if (att) { + *att++ = '\0'; + if (strcmp(att, "hex") == 0) + ax[cnt].type = TRACEFS_HIST_KEY_HEX; + else if (strcmp(att, "sym") == 0) + ax[cnt].type = TRACEFS_HIST_KEY_SYM; + else if (strcmp(att, "sym_offset") == 0) + ax[cnt].type = TRACEFS_HIST_KEY_SYM_OFFSET; + else if (strcmp(att, "syscall") == 0) + ax[cnt].type = TRACEFS_HIST_KEY_SYSCALL; + else if (strcmp(att, "exec") == 0) + ax[cnt].type = TRACEFS_HIST_KEY_EXECNAME; + else if (strcmp(att, "log") == 0) + ax[cnt].type = TRACEFS_HIST_KEY_LOG; + else if (strcmp(att, "usecs") == 0) + ax[cnt].type = TRACEFS_HIST_KEY_USECS; + else { + fprintf(stderr, "Undefined attribute '%s'\n", att); + fprintf(stderr," Acceptable attributes:\n"); + fprintf(stderr," hex, sym, sym_offset, syscall, exe, log, usecs\n"); + exit(-1); + } + } + cnt++; + } + return cnt; +} + +static void process_hist(enum commands cmd, const char *instance_name, + char *group, char *keys, char *vals, char *sort, + char *ascend, char *desc) +{ + struct tracefs_instance *instance = NULL; + struct tracefs_hist *hist; + struct tep_handle *tep; + struct tracefs_hist_axis *axes = NULL; + char *system; + char *event; + char *sav; + char *val; + int ret; + int cnt; + + if (instance_name) { + instance = tracefs_instance_create(instance_name); + if (!instance) { + fprintf(stderr, "Failed instance create\n"); + exit(-1); + } + } + + tep = tracefs_local_events(NULL); + if (!tep) { + perror("Could not read events"); + exit(-1); + } + + parse_system_event(group, &system, &event); + + if (cmd == SHOW) { + char *content; + content = tracefs_event_file_read(instance, system, event, + "hist", NULL); + if (!content) { + perror("Reading hist file"); + exit(-1); + } + printf("%s\n", content); + free(content); + return; + } + + if (!keys) { + fprintf(stderr, "Command needs -k option\n"); + exit(-1); + } + + cnt = parse_keys(keys, &axes); + if (!cnt) { + fprintf(stderr, "No keys??\n"); + exit(-1); + } + + /* Show examples of hist1d and hist2d */ + switch (cnt) { + case 1: + hist = tracefs_hist_alloc(tep, system, event, + axes[0].key, axes[0].type); + break; + case 2: + hist = tracefs_hist_alloc_2d(tep, system, event, + axes[0].key, axes[0].type, + axes[1].key, axes[1].type); + break; + default: + /* Really, 1 and 2 could use this too */ + hist = tracefs_hist_alloc_nd(tep, system, event, axes); + } + if (!hist) { + fprintf(stderr, "Failed hist create\n"); + exit(-1); + } + + if (vals) { + sav = NULL; + for (val = strtok_r(vals, ",", &sav); val; val = strtok_r(NULL, ",", &sav)) { + ret = tracefs_hist_add_value(hist, val); + if (ret) { + fprintf(stderr, "Failed to add value %s\n", val); + exit(-1); + } + } + } + + if (sort) { + sav = NULL; + for (val = strtok_r(sort, ",", &sav); val; val = strtok_r(NULL, ",", &sav)) { + ret = tracefs_hist_add_sort_key(hist, val); + if (ret) { + fprintf(stderr, "Failed to add sort key/val %s\n", val); + exit(-1); + } + } + } + + if (ascend) { + sav = NULL; + for (val = strtok_r(ascend, ",", &sav); val; val = strtok_r(NULL, ",", &sav)) { + ret = tracefs_hist_sort_key_direction(hist, val, TRACEFS_HIST_SORT_ASCENDING); + if (ret) { + fprintf(stderr, "Failed to add ascending key/val %s\n", val); + exit(-1); + } + } + } + + if (desc) { + sav = NULL; + for (val = strtok_r(desc, ",", &sav); val; val = strtok_r(NULL, ",", &sav)) { + ret = tracefs_hist_sort_key_direction(hist, val, TRACEFS_HIST_SORT_DESCENDING); + if (ret) { + fprintf(stderr, "Failed to add descending key/val %s\n", val); + exit(-1); + } + } + } + + tracefs_error_clear(instance); + + switch (cmd) { + case START: + ret = tracefs_hist_start(instance, hist); + if (ret) { + char *err = tracefs_error_last(instance); + if (err) + fprintf(stderr, "\n%s\n", err); + } + break; + case PAUSE: + ret = tracefs_hist_pause(instance, hist); + break; + case CONT: + ret = tracefs_hist_continue(instance, hist); + break; + case RESET: + ret = tracefs_hist_reset(instance, hist); + break; + case DELETE: + ret = tracefs_hist_destroy(instance, hist); + break; + case SHOW: + /* Show was already done */ + break; + } + if (ret) + fprintf(stderr, "Failed: command\n"); + exit(ret); +} + +int main (int argc, char **argv, char **env) +{ + enum commands cmd; + char *instance = NULL; + char *cmd_str; + char *event = NULL; + char *keys = NULL; + char *vals = NULL; + char *sort = NULL; + char *desc = NULL; + char *ascend = NULL; + + if (argc < 2) { + fprintf(stderr, "usage: %s command [-B instance][-e [system/]event][-k keys][-v vals][-s sort]\n", argv[0]); + fprintf(stderr, " [-a ascending][-d descending]\n"); + exit(-1); + } + + cmd_str = argv[1]; + + if (!strcmp(cmd_str, "start")) + cmd = START; + else if (!strcmp(cmd_str, "pause")) + cmd = PAUSE; + else if (!strcmp(cmd_str, "cont")) + cmd = CONT; + else if (!strcmp(cmd_str, "reset")) + cmd = RESET; + else if (!strcmp(cmd_str, "delete")) + cmd = DELETE; + else if (!strcmp(cmd_str, "show")) + cmd = SHOW; + else { + fprintf(stderr, "Unknown command %s\n", cmd_str); + exit(-1); + } + + for (;;) { + int c; + + c = getopt(argc - 1, argv + 1, "e:k:v:B:s:d:a:"); + if (c == -1) + break; + + switch (c) { + case 'e': + event = optarg; + break; + case 'k': + keys = optarg; + break; + case 'v': + vals = optarg; + break; + case 'B': + instance = optarg; + break; + case 's': + sort = optarg; + break; + case 'd': + desc = optarg; + break; + case 'a': + ascend = optarg; + break; + } + } + if (!event) { + event = "kmem/kmalloc"; + if (!keys) + keys = "call_site.sym,bytes_req"; + if (!vals) + vals = "bytes_alloc"; + if (!sort) + sort = "bytes_req,bytes_alloc"; + if (!desc) + desc = "bytes_alloc"; + } + process_hist(cmd, instance, event, keys, vals, sort, ascend, desc); +} +-- + +FILES +----- +[verse] +-- +*tracefs.h* + Header file to include in order to have access to the library APIs. +*-ltracefs* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtracefs(3)_, +_libtraceevent(3)_, +_trace-cmd(1)_, +_tracefs_hist_pause(3)_, +_tracefs_hist_continue(3)_, +_tracefs_hist_reset(3)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* +*Tzvetomir Stoyanov* +*sameeruddin shaik* +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtracefs is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/ + +COPYING +------- +Copyright \(C) 2020 VMware, Inc. Free use of this software is granted under +the terms of the GNU Public License (GPL). diff --git a/Documentation/libtracefs-hist.txt b/Documentation/libtracefs-hist.txt index d7ab709b6e94..9a86df52923a 100644 --- a/Documentation/libtracefs-hist.txt +++ b/Documentation/libtracefs-hist.txt @@ -3,9 +3,8 @@ libtracefs(3) NAME ---- -tracefs_hist_alloc, tracefs_hist_free, tracefs_hist_add_key, tracefs_hist_add_value, tracefs_hist_add_name, tracefs_hist_start, -tracefs_hist_destroy, tracefs_hist_add_sort_key, tracefs_hist_set_sort_key, tracefs_hist_sort_key_direction -tracefs_hist_echo_cmd, tracefs_hist_get_name, tracefs_hist_get_event, tracefs_hist_get_system - Create, update and describe event histograms +tracefs_hist_alloc, tracefs_hist_free, tracefs_hist_add_key, tracefs_hist_add_value, +tracefs_hist_add_name, tracefs_hist_start, tracefs_hist_destroy - Create and destroy event histograms SYNOPSIS -------- @@ -45,37 +44,6 @@ void *tracefs_hist_free*(struct tracefs_hist pass:[*]_hist_); int *tracefs_hist_add_key*(struct tracefs_hist pass:[*]_hist_, const char pass:[*]_key_, enum tracefs_hist_key_type _type_); int *tracefs_hist_add_value*(struct tracefs_hist pass:[*]_hist_, const char pass:[*]_value_); -int *tracefs_hist_add_sort_key*(struct tracefs_hist pass:[*]_hist_, - const char pass:[*]_sort_key_); - -int *tracefs_hist_set_sort_key*(struct tracefs_hist pass:[*]_hist_, - const char pass:[*]_sort_key_, _..._); -int *tracefs_hist_sort_key_direction*(struct tracefs_hist pass:[*]_hist_, - const char pass:[*]_sort_key_, - enum tracefs_hist_sort_direction _dir_); - -int *tracefs_hist_add_name*(struct tracefs_hist pass:[*]_hist_, const char pass:[*]_name_); - -int *tracefs_hist_append_filter*(struct tracefs_hist pass:[*]_hist_, - enum tracefs_filter _type_, - const char pass:[*]_field_, - enum tracefs_compare _compare_, - const char pass:[*]_val_); - -int *tracefs_hist_echo_cmd*(struct trace_seq pass:[*]_s_, struct tracefs_instance pass:[*]_instance_, - struct tracefs_hist pass:[*]_hist_, - enum tracefs_hist_command _command_); - -int *tracefs_hist_command*(struct tracefs_instance pass:[*]_instance_, - struct tracefs_hist pass:[*]_hist_, - enum tracefs_hist_command _command_); - -const char pass:[*]*tracefs_hist_get_name*(struct tracefs_hist pass:[*]_hist_); - -const char pass:[*]*tracefs_hist_get_event*(struct tracefs_hist pass:[*]_hist_); - -const char pass:[*]*tracefs_hist_get_system*(struct tracefs_hist pass:[*]_hist_); - -- DESCRIPTION @@ -128,85 +96,6 @@ key was hit. The _hist_ is the histogram descriptor to add the value to. The _value_ is a field in the histogram to add to when an instance of the key is hit. -*tracefs_hist_add_sort_key*() will add a key to sort on. The _hist_ is the -histogram descriptor to add the sort key to. The _sort_key_ is a string -that must match either an already defined key of the histogram, or an already -defined value. If _hist_ already has sorting keys (previously added) the new -_sort_key_ will have lower priority(be secondary or so on) when sorting. - -*tracefs_hist_set_sort_key*() will reset the list of key to sort on. The _hist_ is -the histogram descriptor to reset the sort key to. The _sort_key_ is a string -that must match either an already defined key of the histogram, or an already -defined value. Multiple sort keys may be added to denote a secondary, sort order -and so on, but all sort keys must match an existing key or value, or be -TRACEFS_HIST_HITCOUNT. The last parameter of *tracefs_hist_add_sort_key*() must -be NULL. - -*tracefs_hist_sort_key_direction*() allows to change the direction of an -existing sort key of _hist_. The _sort_key_ is the sort key to change, and -_dir_ can be either TRACEFS_HIST_SORT_ASCENDING or TRACEFS_HIST_SORT_DESCENDING, -to make the direction of the sort key either ascending or descending respectively. - -*tracefs_hist_add_name*() adds a name to a histogram. A histogram may be -named and if the name matches between more than one event, and they have -compatible keys, the multiple histograms with the same name will be merged -into a single histogram (shown by either event's hist file). The _hist_ -is the histogram to name, and the _name_ is the name to give it. - -*tracefs_hist_append_filter*() creates a filter or appends to it for the -histogram event. Depending on _type_, it will build a string of tokens for -parenthesis or logic statements, or it may add a comparison of _field_ -to _val_ based on _compare_. - -If _type_ is: -*TRACEFS_FILTER_COMPARE* - See below -*TRACEFS_FILTER_AND* - Append "&&" to the filter -*TRACEFS_FILTER_OR* - Append "||" to the filter -*TRACEFS_FILTER_NOT* - Append "!" to the filter -*TRACEFS_FILTER_OPEN_PAREN* - Append "(" to the filter -*TRACEFS_FILTER_CLOSE_PAREN* - Append ")" to the filter - -_field_, _compare_, and _val_ are ignored unless _type_ is equal to -*TRACEFS_FILTER_COMPARE*, then _compare_ will be used for the following: - -*TRACEFS_COMPARE_EQ* - _field_ == _val_ - -*TRACEFS_COMPARE_NE* - _field_ != _val_ - -*TRACEFS_COMPARE_GT* - _field_ > _val_ - -*TRACEFS_COMPARE_GE* - _field_ >= _val_ - -*TRACEFS_COMPARE_LT* - _field_ < _val_ - -*TRACEFS_COMPARE_LE* - _field_