doc/man/babeltrace2-source.text.dmesg.7.txt

   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)