| 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) |