Github user clebertsuconic commented on a diff in the pull request:
https://github.com/apache/activemq-artemis/pull/1295#discussion_r124857265
--- Diff: docs/user-manual/en/tools.md ---
@@ -220,5 +233,115 @@ COMMANDS
With --bindings option, The folder used for bindings (default
from
broker.xml)
+ perf-journal-stat
+ Provide sampling of performance counters of a profiled journal
+
+ With --separator option, The column separator, whitespace if
not
+ specified
+
+ With --broker option, This would override the broker
configuration
+ from the bootstrap
+
+ With --verbose option, Adds more information on the execution
+
+ With --bytes option, Add bytes flushed column in the CSV
output,
+ false if not defined
+
+ With --freq option, Profile at this frequency (Hz) or will use
half
+ of the configured Journal timeout
+
+ With --raw-time option, Uses raw timestamps, false if not
defined
+
+ With --out option, Print the CSV output in a text file or
stdout if
+ not defined
+
+ With --in option, The input counter file to be used to sample
+ profiled data
+
+
+```
+
+## The `perf-journal-stat` tool
+
+This CLI command allows to sample the journal performance counters events
of a broker [configured](configuration-index.md) to emit them.
+
+This sampling profiling tool shares most features of Linux's
[`perf-tools`](https://perf.wiki.kernel.org/index.php/Main_Page):
+
+- (costantly) lightweight while profiling
+- (negligible) no performance hit while not profiling
+- constant and very low memory footprint (i.e. just one [OS
Page](https://en.wikipedia.org/wiki/Page_(computer_memory)) size in total)
+- no Network stack involved (i.e. only Inter-Process Communication)
+- no external dependencies
+
+The next simple example will illustrate how to use it, but it could be
easily integrated with Nagios or any custom toolchain.
+
+### Gnuplot example
+
+Run while a proper [configured](configuration-index.md) broker is running:
+```
+$ ./perf-journal-stat --verbose --freq 20000 --out
~/Documents/journal_trace.csv
--- End diff --
typo? wasn't this supposed to be ./artemis perf-journal-state ???
also: I thought you would run the perf tool against a running broker?
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at [email protected] or file a JIRA ticket
with INFRA.
---
