Commit | Line | Data |
---|---|---|
e70712b3 | 1 | = babeltrace2-source.text.dmesg(7) |
0659f3af | 2 | :manpagetype: component class |
6f6e5e61 | 3 | :revdate: 1 September 2023 |
0659f3af PP |
4 | |
5 | ||
e70712b3 PP |
6 | == NAME |
7 | ||
8 | babeltrace2-source.text.dmesg - Babeltrace 2's Linux kernel ring buffer | |
0659f3af PP |
9 | source component class |
10 | ||
11 | ||
e70712b3 PP |
12 | == DESCRIPTION |
13 | ||
14 | A Babeltrace~2 compcls:source.text.dmesg message iterator reads the | |
0659f3af | 15 | lines of a Linux kernel ring buffer, as printed by the man:dmesg(1) |
e70712b3 PP |
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 | ---- | |
0659f3af | 28 | |
e70712b3 | 29 | include::common-see-babeltrace2-intro.txt[] |
0659f3af | 30 | |
e70712b3 PP |
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. | |
0659f3af | 34 | |
e70712b3 PP |
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: | |
0659f3af PP |
42 | |
43 | ---- | |
44 | [87166.510937] PM: Finishing wakeup. | |
45 | ---- | |
46 | ||
e70712b3 PP |
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. | |
0659f3af | 53 | |
e70712b3 PP |
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. | |
0659f3af | 60 | |
e70712b3 PP |
61 | This is due to a https://lwn.net/Articles/780556/[2019 change] to the |
62 | kernel's ring buffer API. | |
0659f3af | 63 | |
e70712b3 PP |
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 | ||
6f6e5e61 PP |
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. | |
0659f3af | 78 | |
e70712b3 | 79 | param:path='PATH' vtype:[optional string]:: |
0659f3af PP |
80 | Read the kernel ring buffer lines from the file 'PATH' instead of |
81 | the standard input stream. | |
82 | ||
83 | ||
e70712b3 | 84 | == PORTS |
0659f3af | 85 | |
e70712b3 PP |
86 | ---- |
87 | +----------------+ | |
88 | | src.text.dmesg | | |
89 | | | | |
90 | | out @ | |
91 | +----------------+ | |
92 | ---- | |
0659f3af | 93 | |
0659f3af | 94 | |
e70712b3 | 95 | === Output |
0659f3af | 96 | |
e70712b3 PP |
97 | `out`:: |
98 | Single output port. | |
0659f3af PP |
99 | |
100 | ||
101 | include::common-footer.txt[] | |
102 | ||
103 | ||
e70712b3 PP |
104 | == SEE ALSO |
105 | ||
a8be4294 MJ |
106 | man:babeltrace2-plugin-text(7), |
107 | man:babeltrace2-intro(7) |