1.. _thread_analyzer:
2
3Thread analyzer
4###################
5
6The thread analyzer module enables all the Zephyr options required to track
7the thread information, e.g. thread stack size usage and other runtime thread
8runtime statistics.
9
10The analysis is performed on demand when the application calls
11:c:func:`thread_analyzer_run` or :c:func:`thread_analyzer_print`.
12
13For example, to build the synchronization sample with Thread Analyser enabled,
14do the following:
15
16   .. zephyr-app-commands::
17      :zephyr-app: samples/synchronization/
18      :board: qemu_x86
19      :goals: build
20      :gen-args: -DCONFIG_QEMU_ICOUNT=n -DCONFIG_THREAD_ANALYZER=y \
21                   -DCONFIG_THREAD_ANALYZER_USE_PRINTK=y -DCONFIG_THREAD_ANALYZER_AUTO=y \
22                   -DCONFIG_THREAD_ANALYZER_AUTO_INTERVAL=5
23
24
25When you run the generated application in Qemu, you will get the additional
26information from Thread Analyzer::
27
28
29	thread_a: Hello World from cpu 0 on qemu_x86!
30	Thread analyze:
31	 thread_b            : STACK: unused 740 usage 284 / 1024 (27 %); CPU: 0 %
32	 thread_analyzer     : STACK: unused 8 usage 504 / 512 (98 %); CPU: 0 %
33	 thread_a            : STACK: unused 648 usage 376 / 1024 (36 %); CPU: 98 %
34	 idle                : STACK: unused 204 usage 116 / 320 (36 %); CPU: 0 %
35	thread_b: Hello World from cpu 0 on qemu_x86!
36	thread_a: Hello World from cpu 0 on qemu_x86!
37	thread_b: Hello World from cpu 0 on qemu_x86!
38	thread_a: Hello World from cpu 0 on qemu_x86!
39	thread_b: Hello World from cpu 0 on qemu_x86!
40	thread_a: Hello World from cpu 0 on qemu_x86!
41	thread_b: Hello World from cpu 0 on qemu_x86!
42	thread_a: Hello World from cpu 0 on qemu_x86!
43	Thread analyze:
44	 thread_b            : STACK: unused 648 usage 376 / 1024 (36 %); CPU: 7 %
45	 thread_analyzer     : STACK: unused 8 usage 504 / 512 (98 %); CPU: 0 %
46	 thread_a            : STACK: unused 648 usage 376 / 1024 (36 %); CPU: 9 %
47	 idle                : STACK: unused 204 usage 116 / 320 (36 %); CPU: 82 %
48	thread_b: Hello World from cpu 0 on qemu_x86!
49	thread_a: Hello World from cpu 0 on qemu_x86!
50	thread_b: Hello World from cpu 0 on qemu_x86!
51	thread_a: Hello World from cpu 0 on qemu_x86!
52	thread_b: Hello World from cpu 0 on qemu_x86!
53	thread_a: Hello World from cpu 0 on qemu_x86!
54	thread_b: Hello World from cpu 0 on qemu_x86!
55	thread_a: Hello World from cpu 0 on qemu_x86!
56	Thread analyze:
57	 thread_b            : STACK: unused 648 usage 376 / 1024 (36 %); CPU: 7 %
58	 thread_analyzer     : STACK: unused 8 usage 504 / 512 (98 %); CPU: 0 %
59	 thread_a            : STACK: unused 648 usage 376 / 1024 (36 %); CPU: 8 %
60	 idle                : STACK: unused 204 usage 116 / 320 (36 %); CPU: 83 %
61	thread_b: Hello World from cpu 0 on qemu_x86!
62	thread_a: Hello World from cpu 0 on qemu_x86!
63	thread_b: Hello World from cpu 0 on qemu_x86!
64
65
66Configuration
67*************
68Configure this module using the following options.
69
70:kconfig:option:`CONFIG_THREAD_ANALYZER`
71   Enable the module.
72:kconfig:option:`CONFIG_THREAD_ANALYZER_USE_PRINTK`
73   Use printk for thread statistics.
74:kconfig:option:`CONFIG_THREAD_ANALYZER_USE_LOG`
75   Use the logger for thread statistics.
76:kconfig:option:`CONFIG_THREAD_ANALYZER_AUTO`
77   Run the thread analyzer automatically.
78   You do not need to add any code to the application when using this option.
79:kconfig:option:`CONFIG_THREAD_ANALYZER_AUTO_INTERVAL`
80   The time for which the module sleeps between consecutive printing of thread analysis in automatic
81   mode.
82:kconfig:option:`CONFIG_THREAD_ANALYZER_AUTO_STACK_SIZE`
83  The stack for thread analyzer automatic thread.
84:kconfig:option:`CONFIG_THREAD_NAME`
85  Print the name of the thread instead of its ID.
86:kconfig:option:`CONFIG_THREAD_RUNTIME_STATS`
87  Print thread runtime data such as utilization.
88  This options is automatically selected by :kconfig:option:`CONFIG_THREAD_ANALYZER`.
89:kconfig:option:`CONFIG_THREAD_ANALYZER_LONG_FRAME_PER_INTERVAL`
90  Reset Longest Frame value statistics after printing.
91  When using :kconfig:option:`SCHED_THREAD_USAGE_ANALYSIS` to get average and longest
92  frame thread statistics, reset the Longest Frame value to zero after each time
93  printing the thread statistics.  This enables observation of the longest frame
94  during the most recent interval rather than longest frame since startup.
95
96API documentation
97*****************
98
99.. doxygengroup:: thread_analyzer
100