1# OpenThread CLI - History Tracker 2 3History Tracker module records history of different events (e.g., RX and TX IPv6 messages or network info changes, etc.) as the Thread network operates. All tracked entries are timestamped. 4 5All commands under `history` require `OPENTHREAD_CONFIG_HISTORY_TRACKER_ENABLE` feature to be enabled. 6 7The number of entries recorded for each history list is configurable through a set of OpenThread config options, e.g. `OPENTHREAD_CONFIG_HISTORY_TRACKER_NET_INFO_LIST_SIZE` specifies the number of entries in Network Info history list. The History Tracker will keep the most recent entries overwriting oldest one when the list gets full. 8 9## Command List 10 11Usage : `history [command] ...` 12 13- [help](#help) 14- [neighbor](#neighbor) 15- [netinfo](#netinfo) 16- [rx](#rx) 17- [rxtx](#rxtx) 18- [tx](#tx) 19 20## Timestamp Format 21 22Recorded entries are timestamped. When the history list is printed, the timestamps are shown relative the time the command was issues (i.e., when the list was printed) indicating how long ago the entry was recorded. 23 24```bash 25> history netinfo 26| Age | Role | Mode | RLOC16 | Partition ID | 27+----------------------+----------+------+--------+--------------+ 28| 02:31:50.628 | leader | rdn | 0x2000 | 151029327 | 29| 02:31:53.262 | detached | rdn | 0xfffe | 0 | 30| 02:31:54.663 | detached | rdn | 0x2000 | 0 | 31Done 32``` 33 34For example `02:31:50.628` indicates the event was recorded "2 hours, 31 minutes, 50 seconds, and 628 milliseconds ago". Number of days is added for events that are older than 24 hours, e.g., `1 day 11:25:31.179`, or `31 days 03:00:23.931`. 35 36Timestamps use millisecond accuracy and are tacked up to 49 days. If the event is older than 49 days, the entry is still tracked in the list but the timestamp is shown as `more than 49 days`. 37 38## Command Details 39 40### help 41 42Usage: `history help` 43 44Print SRP client help menu. 45 46```bash 47> history help 48help 49neighbor 50netinfo 51rx 52rxtx 53tx 54Done 55> 56``` 57 58### neighbor 59 60Usage `history neighbor [list] [<num-entries>]` 61 62Print the neighbor table history. Each entry provides: 63 64- Type: Child or Router 65- Event: Added, Removed, Changed (e.g., mode change). 66- Extended Address 67- RLOC16 68- MLE Link Mode 69- Average RSS (in dBm) of received frames from neighbor at the time the entry was recorded 70 71Print the neighbor history as a table. 72 73```bash 74> history neighbor 75| Age | Type | Event | Extended Address | RLOC16 | Mode | Ave RSS | 76+----------------------+--------+-----------+------------------+--------+------+---------+ 77| 00:00:29.233 | Child | Added | ae5105292f0b9169 | 0x8404 | - | -20 | 78| 00:01:38.368 | Child | Removed | ae5105292f0b9169 | 0x8401 | - | -20 | 79| 00:04:27.181 | Child | Changed | ae5105292f0b9169 | 0x8401 | - | -20 | 80| 00:04:51.236 | Router | Added | 865c7ca38a5fa960 | 0x9400 | rdn | -20 | 81| 00:04:51.587 | Child | Removed | 865c7ca38a5fa960 | 0x8402 | rdn | -20 | 82| 00:05:22.764 | Child | Changed | ae5105292f0b9169 | 0x8401 | rn | -20 | 83| 00:06:40.764 | Child | Added | 4ec99efc874a1841 | 0x8403 | r | -20 | 84| 00:06:44.060 | Child | Added | 865c7ca38a5fa960 | 0x8402 | rdn | -20 | 85| 00:06:49.515 | Child | Added | ae5105292f0b9169 | 0x8401 | - | -20 | 86Done 87``` 88 89Print the neighbor history as a list. 90 91```bash 92 93> history neighbor list 9400:00:34.753 -> type:Child event:Added extaddr:ae5105292f0b9169 rloc16:0x8404 mode:- rss:-20 9500:01:43.888 -> type:Child event:Removed extaddr:ae5105292f0b9169 rloc16:0x8401 mode:- rss:-20 9600:04:32.701 -> type:Child event:Changed extaddr:ae5105292f0b9169 rloc16:0x8401 mode:- rss:-20 9700:04:56.756 -> type:Router event:Added extaddr:865c7ca38a5fa960 rloc16:0x9400 mode:rdn rss:-20 9800:04:57.107 -> type:Child event:Removed extaddr:865c7ca38a5fa960 rloc16:0x8402 mode:rdn rss:-20 9900:05:28.284 -> type:Child event:Changed extaddr:ae5105292f0b9169 rloc16:0x8401 mode:rn rss:-20 10000:06:46.284 -> type:Child event:Added extaddr:4ec99efc874a1841 rloc16:0x8403 mode:r rss:-20 10100:06:49.580 -> type:Child event:Added extaddr:865c7ca38a5fa960 rloc16:0x8402 mode:rdn rss:-20 10200:06:55.035 -> type:Child event:Added extaddr:ae5105292f0b9169 rloc16:0x8401 mode:- rss:-20 103Done 104``` 105 106### netinfo 107 108Usage `history netinfo [list] [<num-entries>]` 109 110Print the Network Info history. Each Network Info provides: 111 112- Device Role 113- MLE Link Mode 114- RLOC16 115- Partition ID 116 117Print the Network Info history as a table. 118 119```bash 120> history netinfo 121| Age | Role | Mode | RLOC16 | Partition ID | 122+----------------------+----------+------+--------+--------------+ 123| 00:00:10.069 | router | rdn | 0x6000 | 151029327 | 124| 00:02:09.337 | child | rdn | 0x2001 | 151029327 | 125| 00:02:09.338 | child | rdn | 0x2001 | 151029327 | 126| 00:07:40.806 | child | - | 0x2001 | 151029327 | 127| 00:07:42.297 | detached | - | 0x6000 | 0 | 128| 00:07:42.968 | disabled | - | 0x6000 | 0 | 129Done 130``` 131 132Print the Network Info history as a list. 133 134```bash 135> history netinfo list 13600:00:59.467 -> role:router mode:rdn rloc16:0x6000 partition-id:151029327 13700:02:58.735 -> role:child mode:rdn rloc16:0x2001 partition-id:151029327 13800:02:58.736 -> role:child mode:rdn rloc16:0x2001 partition-id:151029327 13900:08:30.204 -> role:child mode:- rloc16:0x2001 partition-id:151029327 14000:08:31.695 -> role:detached mode:- rloc16:0x6000 partition-id:0 14100:08:32.366 -> role:disabled mode:- rloc16:0x6000 partition-id:0 142Done 143``` 144 145Print only the latest 2 entries. 146 147```bash 148> history netinfo 2 149| Age | Role | Mode | RLOC16 | Partition ID | 150+----------------------+----------+------+--------+--------------+ 151| 00:02:05.451 | router | rdn | 0x6000 | 151029327 | 152| 00:04:04.719 | child | rdn | 0x2001 | 151029327 | 153Done 154``` 155 156### rx 157 158Usage `history rx [list] [<num-entries>]` 159 160Print the IPv6 message RX history in either table or list format. Entries provide same information and follow same format as in `history rxtx` command. 161 162Print the IPv6 message RX history as a table: 163 164```bash 165> history rx 166| Age | Type | Len | Chksum | Sec | Prio | RSS |Dir | Neighb | Radio | 167+----------------------+------------------+-------+--------+-----+------+------+----+--------+-------+ 168| | UDP | 50 | 0xbd26 | no | net | -20 | RX | 0x4800 | 15.4 | 169| 00:00:07.640 | src: [fe80:0:0:0:d03d:d3e7:cc5e:7cd7]:19788 | 170| | dst: [ff02:0:0:0:0:0:0:1]:19788 | 171+----------------------+------------------+-------+--------+-----+------+------+----+--------+-------+ 172| | HopOpts | 44 | 0x0000 | yes | norm | -20 | RX | 0x4800 | 15.4 | 173| 00:00:09.263 | src: [fdde:ad00:beef:0:0:ff:fe00:4800]:0 | 174| | dst: [ff03:0:0:0:0:0:0:2]:0 | 175+----------------------+------------------+-------+--------+-----+------+------+----+--------+-------+ 176| | UDP | 12 | 0x3f7d | yes | net | -20 | RX | 0x4800 | 15.4 | 177| 00:00:09.302 | src: [fdde:ad00:beef:0:0:ff:fe00:4800]:61631 | 178| | dst: [fdde:ad00:beef:0:0:ff:fe00:4801]:61631 | 179+----------------------+------------------+-------+--------+-----+------+------+----+--------+-------+ 180| | ICMP6(EchoReqst) | 16 | 0x942c | yes | norm | -20 | RX | 0x4800 | 15.4 | 181| 00:00:09.304 | src: [fdde:ad00:beef:0:ac09:a16b:3204:dc09]:0 | 182| | dst: [fdde:ad00:beef:0:dc0e:d6b3:f180:b75b]:0 | 183+----------------------+------------------+-------+--------+-----+------+------+----+--------+-------+ 184| | HopOpts | 44 | 0x0000 | yes | norm | -20 | RX | 0x4800 | 15.4 | 185| 00:00:09.304 | src: [fdde:ad00:beef:0:0:ff:fe00:4800]:0 | 186| | dst: [ff03:0:0:0:0:0:0:2]:0 | 187+----------------------+------------------+-------+--------+-----+------+------+----+--------+-------+ 188| | UDP | 50 | 0x2e37 | no | net | -20 | RX | 0x4800 | 15.4 | 189| 00:00:21.622 | src: [fe80:0:0:0:d03d:d3e7:cc5e:7cd7]:19788 | 190| | dst: [ff02:0:0:0:0:0:0:1]:19788 | 191+----------------------+------------------+-------+--------+-----+------+------+----+--------+-------+ 192| | UDP | 50 | 0xe177 | no | net | -20 | RX | 0x4800 | 15.4 | 193| 00:00:26.640 | src: [fe80:0:0:0:d03d:d3e7:cc5e:7cd7]:19788 | 194| | dst: [ff02:0:0:0:0:0:0:1]:19788 | 195+----------------------+------------------+-------+--------+-----+------+------+----+--------+-------+ 196| | UDP | 165 | 0x82ee | yes | net | -20 | RX | 0x4800 | 15.4 | 197| 00:00:30.000 | src: [fe80:0:0:0:d03d:d3e7:cc5e:7cd7]:19788 | 198| | dst: [fe80:0:0:0:a4a5:bbac:a8e:bd07]:19788 | 199+----------------------+------------------+-------+--------+-----+------+------+----+--------+-------+ 200| | UDP | 93 | 0x52df | no | net | -20 | RX | unknwn | 15.4 | 201| 00:00:30.480 | src: [fe80:0:0:0:d03d:d3e7:cc5e:7cd7]:19788 | 202| | dst: [fe80:0:0:0:a4a5:bbac:a8e:bd07]:19788 | 203+----------------------+------------------+-------+--------+-----+------+------+----+--------+-------+ 204| | UDP | 50 | 0x5ccf | no | net | -20 | RX | unknwn | 15.4 | 205| 00:00:30.772 | src: [fe80:0:0:0:d03d:d3e7:cc5e:7cd7]:19788 | 206| | dst: [ff02:0:0:0:0:0:0:1]:19788 | 207Done 208 209``` 210 211Print the latest 5 entries of the IPv6 message RX history as a list: 212 213```bash 214> history rx list 4 21500:00:13.368 216 type:UDP len:50 cheksum:0xbd26 sec:no prio:net rss:-20 from:0x4800 radio:15.4 217 src:[fe80:0:0:0:d03d:d3e7:cc5e:7cd7]:19788 218 dst:[ff02:0:0:0:0:0:0:1]:19788 21900:00:14.991 220 type:HopOpts len:44 cheksum:0x0000 sec:yes prio:norm rss:-20 from:0x4800 radio:15.4 221 src:[fdde:ad00:beef:0:0:ff:fe00:4800]:0 222 dst:[ff03:0:0:0:0:0:0:2]:0 22300:00:15.030 224 type:UDP len:12 cheksum:0x3f7d sec:yes prio:net rss:-20 from:0x4800 radio:15.4 225 src:[fdde:ad00:beef:0:0:ff:fe00:4800]:61631 226 dst:[fdde:ad00:beef:0:0:ff:fe00:4801]:61631 22700:00:15.032 228 type:ICMP6(EchoReqst) len:16 cheksum:0x942c sec:yes prio:norm rss:-20 from:0x4800 radio:15.4 229 src:[fdde:ad00:beef:0:ac09:a16b:3204:dc09]:0 230 dst:[fdde:ad00:beef:0:dc0e:d6b3:f180:b75b]:0 231Done 232``` 233 234### rxtx 235 236Usage `history rxtx [list] [<num-entries>]` 237 238Print the combined IPv6 message RX and TX history in either table or list format. Each entry provides: 239 240- IPv6 message type: UDP, TCP, ICMP6 (and its subtype), etc. 241- IPv6 payload length (excludes the IPv6 header). 242- Source IPv6 address and port number. 243- Destination IPv6 address and port number (port number is valid for UDP/TCP, it is zero otherwise). 244- Whether or not link-layer security was used. 245- Message priority: low, norm, high, net (for Thread control messages). 246- Message checksum (valid for UDP, TCP, or ICMP6 message) 247- RSS: Received Signal Strength (in dBm) - averaged over all received fragment frames that formed the message. For TX history `NA` (not applicable) is used. 248- Whether the message was sent or received (`TX` or `RX`). A failed transmission (e.g., if tx was aborted or no ack from peer for any of the message fragments) is indicated with `TX-F` in the table format or `tx-success:no` in the list format. 249- Short address (RLOC16) of neighbor to/from which the message was sent/received. If the frame is broadcast, it is shown as `bcast` in table format or `0xffff` in the list format. If the short address of neighbor is not available, it is shown as `unknwn` in the table format or `0xfffe` in the list format. 250- Radio link on which the message was sent/received (useful when `OPENTHREAD_CONFIG_MULTI_RADIO` is enabled). Can be `15.4`, `trel`, or `all` (if sent on all radio links). 251 252Print the IPv6 message RX and TX history as a table: 253 254```bash 255> history rxtx 256| Age | Type | Len | Chksum | Sec | Prio | RSS |Dir | Neighb | Radio | 257+----------------------+------------------+-------+--------+-----+------+------+----+--------+-------+ 258| | HopOpts | 44 | 0x0000 | yes | norm | -20 | RX | 0x0800 | 15.4 | 259| 00:00:09.267 | src: [fdde:ad00:beef:0:0:ff:fe00:800]:0 | 260| | dst: [ff03:0:0:0:0:0:0:2]:0 | 261+----------------------+------------------+-------+--------+-----+------+------+----+--------+-------+ 262| | UDP | 12 | 0x6c6b | yes | net | -20 | RX | 0x0800 | 15.4 | 263| 00:00:09.290 | src: [fdde:ad00:beef:0:0:ff:fe00:800]:61631 | 264| | dst: [fdde:ad00:beef:0:0:ff:fe00:801]:61631 | 265+----------------------+------------------+-------+--------+-----+------+------+----+--------+-------+ 266| | ICMP6(EchoReqst) | 16 | 0xc6a2 | yes | norm | -20 | RX | 0x0800 | 15.4 | 267| 00:00:09.292 | src: [fdde:ad00:beef:0:efe8:4910:cf95:dee9]:0 | 268| | dst: [fdde:ad00:beef:0:af4c:3644:882a:3698]:0 | 269+----------------------+------------------+-------+--------+-----+------+------+----+--------+-------+ 270| | ICMP6(EchoReply) | 16 | 0xc5a2 | yes | norm | NA | TX | 0x0800 | 15.4 | 271| 00:00:09.292 | src: [fdde:ad00:beef:0:af4c:3644:882a:3698]:0 | 272| | dst: [fdde:ad00:beef:0:efe8:4910:cf95:dee9]:0 | 273+----------------------+------------------+-------+--------+-----+------+------+----+--------+-------+ 274| | UDP | 50 | 0xaa0d | yes | net | NA | TX | 0x0800 | 15.4 | 275| 00:00:09.294 | src: [fdde:ad00:beef:0:0:ff:fe00:801]:61631 | 276| | dst: [fdde:ad00:beef:0:0:ff:fe00:800]:61631 | 277+----------------------+------------------+-------+--------+-----+------+------+----+--------+-------+ 278| | HopOpts | 44 | 0x0000 | yes | norm | -20 | RX | 0x0800 | 15.4 | 279| 00:00:09.296 | src: [fdde:ad00:beef:0:0:ff:fe00:800]:0 | 280| | dst: [ff03:0:0:0:0:0:0:2]:0 | 281+----------------------+------------------+-------+--------+-----+------+------+----+--------+-------+ 282| | UDP | 50 | 0xc1d8 | no | net | -20 | RX | 0x0800 | 15.4 | 283| 00:00:09.569 | src: [fe80:0:0:0:54d9:5153:ffc6:df26]:19788 | 284| | dst: [ff02:0:0:0:0:0:0:1]:19788 | 285+----------------------+------------------+-------+--------+-----+------+------+----+--------+-------+ 286| | UDP | 50 | 0x3cb1 | no | net | -20 | RX | 0x0800 | 15.4 | 287| 00:00:16.519 | src: [fe80:0:0:0:54d9:5153:ffc6:df26]:19788 | 288| | dst: [ff02:0:0:0:0:0:0:1]:19788 | 289+----------------------+------------------+-------+--------+-----+------+------+----+--------+-------+ 290| | UDP | 50 | 0xeda0 | no | net | -20 | RX | 0x0800 | 15.4 | 291| 00:00:20.599 | src: [fe80:0:0:0:54d9:5153:ffc6:df26]:19788 | 292| | dst: [ff02:0:0:0:0:0:0:1]:19788 | 293+----------------------+------------------+-------+--------+-----+------+------+----+--------+-------+ 294| | UDP | 165 | 0xbdfa | yes | net | -20 | RX | 0x0800 | 15.4 | 295| 00:00:21.059 | src: [fe80:0:0:0:54d9:5153:ffc6:df26]:19788 | 296| | dst: [fe80:0:0:0:8893:c2cc:d983:1e1c]:19788 | 297+----------------------+------------------+-------+--------+-----+------+------+----+--------+-------+ 298| | UDP | 64 | 0x1c11 | no | net | NA | TX | 0x0800 | 15.4 | 299| 00:00:21.062 | src: [fe80:0:0:0:8893:c2cc:d983:1e1c]:19788 | 300| | dst: [fe80:0:0:0:54d9:5153:ffc6:df26]:19788 | 301+----------------------+------------------+-------+--------+-----+------+------+----+--------+-------+ 302| | UDP | 93 | 0xedff | no | net | -20 | RX | unknwn | 15.4 | 303| 00:00:21.474 | src: [fe80:0:0:0:54d9:5153:ffc6:df26]:19788 | 304| | dst: [fe80:0:0:0:8893:c2cc:d983:1e1c]:19788 | 305+----------------------+------------------+-------+--------+-----+------+------+----+--------+-------+ 306| | UDP | 44 | 0xd383 | no | net | NA | TX | bcast | 15.4 | 307| 00:00:21.811 | src: [fe80:0:0:0:8893:c2cc:d983:1e1c]:19788 | 308| | dst: [ff02:0:0:0:0:0:0:2]:19788 | 309Done 310``` 311 312Print the latest 5 entries of the IPv6 message RX history as a list: 313 314```bash 315> history rxtx list 5 316 31700:00:02.100 318 type:UDP len:50 cheksum:0xd843 sec:no prio:net rss:-20 from:0x0800 radio:15.4 319 src:[fe80:0:0:0:54d9:5153:ffc6:df26]:19788 320 dst:[ff02:0:0:0:0:0:0:1]:19788 32100:00:15.331 322 type:HopOpts len:44 cheksum:0x0000 sec:yes prio:norm rss:-20 from:0x0800 radio:15.4 323 src:[fdde:ad00:beef:0:0:ff:fe00:800]:0 324 dst:[ff03:0:0:0:0:0:0:2]:0 32500:00:15.354 326 type:UDP len:12 cheksum:0x6c6b sec:yes prio:net rss:-20 from:0x0800 radio:15.4 327 src:[fdde:ad00:beef:0:0:ff:fe00:800]:61631 328 dst:[fdde:ad00:beef:0:0:ff:fe00:801]:61631 32900:00:15.356 330 type:ICMP6(EchoReqst) len:16 cheksum:0xc6a2 sec:yes prio:norm rss:-20 from:0x0800 radio:15.4 331 src:[fdde:ad00:beef:0:efe8:4910:cf95:dee9]:0 332 dst:[fdde:ad00:beef:0:af4c:3644:882a:3698]:0 33300:00:15.356 334 type:ICMP6(EchoReply) len:16 cheksum:0xc5a2 sec:yes prio:norm tx-success:yes to:0x0800 radio:15.4 335 src:[fdde:ad00:beef:0:af4c:3644:882a:3698]:0 336 dst:[fdde:ad00:beef:0:efe8:4910:cf95:dee9]:0 337``` 338 339### tx 340 341Usage `history tx [list] [<num-entries>]` 342 343Print the IPv6 message TX history in either table or list format. Entries provide same information and follow same format as in `history rxtx` command. 344 345Print the IPv6 message TX history as a table (10 latest entries): 346 347```bash 348> history tx 349| Age | Type | Len | Chksum | Sec | Prio | RSS |Dir | Neighb | Radio | 350+----------------------+------------------+-------+--------+-----+------+------+----+--------+-------+ 351| | ICMP6(EchoReply) | 16 | 0x932c | yes | norm | NA | TX | 0x4800 | 15.4 | 352| 00:00:18.798 | src: [fdde:ad00:beef:0:dc0e:d6b3:f180:b75b]:0 | 353| | dst: [fdde:ad00:beef:0:ac09:a16b:3204:dc09]:0 | 354+----------------------+------------------+-------+--------+-----+------+------+----+--------+-------+ 355| | UDP | 50 | 0xce87 | yes | net | NA | TX | 0x4800 | 15.4 | 356| 00:00:18.800 | src: [fdde:ad00:beef:0:0:ff:fe00:4801]:61631 | 357| | dst: [fdde:ad00:beef:0:0:ff:fe00:4800]:61631 | 358+----------------------+------------------+-------+--------+-----+------+------+----+--------+-------+ 359| | UDP | 64 | 0xf7ba | no | net | NA | TX | 0x4800 | 15.4 | 360| 00:00:39.499 | src: [fe80:0:0:0:a4a5:bbac:a8e:bd07]:19788 | 361| | dst: [fe80:0:0:0:d03d:d3e7:cc5e:7cd7]:19788 | 362+----------------------+------------------+-------+--------+-----+------+------+----+--------+-------+ 363| | UDP | 44 | 0x26d4 | no | net | NA | TX | bcast | 15.4 | 364| 00:00:40.256 | src: [fe80:0:0:0:a4a5:bbac:a8e:bd07]:19788 | 365| | dst: [ff02:0:0:0:0:0:0:2]:19788 | 366Done 367``` 368 369Print the IPv6 message TX history as a list: 370 371```bash 372history tx list 37300:00:23.957 374 type:ICMP6(EchoReply) len:16 cheksum:0x932c sec:yes prio:norm tx-success:yes to:0x4800 radio:15.4 375 src:[fdde:ad00:beef:0:dc0e:d6b3:f180:b75b]:0 376 dst:[fdde:ad00:beef:0:ac09:a16b:3204:dc09]:0 37700:00:23.959 378 type:UDP len:50 cheksum:0xce87 sec:yes prio:net tx-success:yes to:0x4800 radio:15.4 379 src:[fdde:ad00:beef:0:0:ff:fe00:4801]:61631 380 dst:[fdde:ad00:beef:0:0:ff:fe00:4800]:61631 38100:00:44.658 382 type:UDP len:64 cheksum:0xf7ba sec:no prio:net tx-success:yes to:0x4800 radio:15.4 383 src:[fe80:0:0:0:a4a5:bbac:a8e:bd07]:19788 384 dst:[fe80:0:0:0:d03d:d3e7:cc5e:7cd7]:19788 38500:00:45.415 386 type:UDP len:44 cheksum:0x26d4 sec:no prio:net tx-success:yes to:0xffff radio:15.4 387 src:[fe80:0:0:0:a4a5:bbac:a8e:bd07]:19788 388 dst:[ff02:0:0:0:0:0:0:2]:19788 389Done 390``` 391