doc/man: make default values of boolean init. params. clearer

[babeltrace.git] / doc / man / babeltrace2-source.text.dmesg.7.txt

= babeltrace2-source.text.dmesg(7)
:manpagetype: component class
:revdate: 1 September 2023


== NAME

babeltrace2-source.text.dmesg - Babeltrace 2's Linux kernel ring buffer
source component class


== DESCRIPTION

A Babeltrace~2 compcls:source.text.dmesg message iterator reads the
lines of a Linux kernel ring buffer, as printed by the man:dmesg(1)
tool, and emits corresponding event messages.

----
Linux kernel ring buffer
lines (file or standard input)
  |
  |   +----------------+
  |   | src.text.dmesg |
  '-->|                |
      |            out @--> Messages (single stream)
      +----------------+
----

include::common-see-babeltrace2-intro.txt[]

A compcls:source.text.dmesg message iterator names the events it creates
`string`. Each event contain a single payload string field named `str`
which contains the corresponding ring buffer line.

By default, a compcls:source.text.dmesg message iterator reads the lines
of the standard input stream. You can make the message iterator read the
lines of a text file instead with the param:path parameter.

By default, the message iterator tries to extract the timestamps of the
kernel ring buffer lines and use them as the created events's
timestamps. A typical man:dmesg(1) line looks like this:

----
[87166.510937] PM: Finishing wakeup.
----

The `[87166.510937]` part is the timestamp to extract. When this
information is available, the component creates a clock class which does
:not: have the Unix epoch as its origin.

You can make the message iterator not extract timestamps from lines with
the param:no-extract-timestamp parameter.

[NOTE]
====
It is possible that the output of man:dmesg(1) contains unsorted lines,
that is, their timestamps go back in time. You can see this with the
nlopt:--show-delta option of man:dmesg(1): some time differences can be
negative.

This is due to a https://lwn.net/Articles/780556/[2019 change] to the
kernel's ring buffer API.

As of this version, a compcls:source.text.dmesg message iterator
requires that the input kernel ring buffer lines be sorted by timestamp
(when they have timestamps), failing otherwise.
====


== INITIALIZATION PARAMETERS

param:no-extract-timestamp='VAL' vtype:[optional boolean]::
    If 'VAL' is true, then do :not: extract timestamps from the kernel
    ring buffer lines: set the created event's payload's `str` field to
    the whole line, including any timestamp prefix.
+
Default: false.

param:path='PATH' vtype:[optional string]::
    Read the kernel ring buffer lines from the file 'PATH' instead of
    the standard input stream.


== PORTS

----
+----------------+
| src.text.dmesg |
|                |
|            out @
+----------------+
----


=== Output

`out`::
    Single output port.


include::common-footer.txt[]


== SEE ALSO

man:babeltrace2-plugin-text(7),
man:babeltrace2-intro(7)