[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)
Commit	Line	Data
	1	= babeltrace2-source.text.dmesg(7)
	2	:manpagetype: component class
	3	:revdate: 1 September 2023
	4
	5
	6	== NAME
	7
	8	babeltrace2-source.text.dmesg - Babeltrace 2's Linux kernel ring buffer
	9	source component class
	10
	11
	12	== DESCRIPTION
	13
	14	A Babeltrace~2 compcls:source.text.dmesg message iterator reads the
	15	lines of a Linux kernel ring buffer, as printed by the man:dmesg(1)
	16	tool, and emits corresponding event messages.
	17
	18	----
	19	Linux kernel ring buffer
	20	lines (file or standard input)
	21	\|
	22	\| +----------------+
	23	\| \| src.text.dmesg \|
	24	'-->\| \|
	25	\| out @--> Messages (single stream)
	26	+----------------+
	27	----
	28
	29	include::common-see-babeltrace2-intro.txt[]
	30
	31	A compcls:source.text.dmesg message iterator names the events it creates
	32	`string`. Each event contain a single payload string field named `str`
	33	which contains the corresponding ring buffer line.
	34
	35	By default, a compcls:source.text.dmesg message iterator reads the lines
	36	of the standard input stream. You can make the message iterator read the
	37	lines of a text file instead with the param:path parameter.
	38
	39	By default, the message iterator tries to extract the timestamps of the
	40	kernel ring buffer lines and use them as the created events's
	41	timestamps. A typical man:dmesg(1) line looks like this:
	42
	43	----
	44	[87166.510937] PM: Finishing wakeup.
	45	----
	46
	47	The `[87166.510937]` part is the timestamp to extract. When this
	48	information is available, the component creates a clock class which does
	49	:not: have the Unix epoch as its origin.
	50
	51	You can make the message iterator not extract timestamps from lines with
	52	the param:no-extract-timestamp parameter.
	53
	54	[NOTE]
	55	====
	56	It is possible that the output of man:dmesg(1) contains unsorted lines,
	57	that is, their timestamps go back in time. You can see this with the
	58	nlopt:--show-delta option of man:dmesg(1): some time differences can be
	59	negative.
	60
	61	This is due to a https://lwn.net/Articles/780556/[2019 change] to the
	62	kernel's ring buffer API.
	63
	64	As of this version, a compcls:source.text.dmesg message iterator
	65	requires that the input kernel ring buffer lines be sorted by timestamp
	66	(when they have timestamps), failing otherwise.
	67	====
	68
	69
	70	== INITIALIZATION PARAMETERS
	71
	72	param:no-extract-timestamp='VAL' vtype:[optional boolean]::
	73	If 'VAL' is true, then do :not: extract timestamps from the kernel
	74	ring buffer lines: set the created event's payload's `str` field to
	75	the whole line, including any timestamp prefix.
	76	+
	77	Default: false.
	78
	79	param:path='PATH' vtype:[optional string]::
	80	Read the kernel ring buffer lines from the file 'PATH' instead of
	81	the standard input stream.
	82
	83
	84	== PORTS
	85
	86	----
	87	+----------------+
	88	\| src.text.dmesg \|
	89	\| \|
	90	\| out @
	91	+----------------+
	92	----
	93
	94
	95	=== Output
	96
	97	`out`::
	98	Single output port.
	99
	100
	101	include::common-footer.txt[]
	102
	103
	104	== SEE ALSO
	105
	106	man:babeltrace2-plugin-text(7),
	107	man:babeltrace2-intro(7)