History Tracker

Records the history of different events, for example RX and TX messages or network info changes.

Summary

All tracked entries are timestamped.

The functions in this module are available when OPENTHREAD_CONFIG_HISTORY_TRACKER_ENABLE is enabled.

Enumerations
`Anonymous Enum 2{ OT_HISTORY_TRACKER_MSG_PRIORITY_LOW = OT_MESSAGE_PRIORITY_LOW, OT_HISTORY_TRACKER_MSG_PRIORITY_NORMAL = OT_MESSAGE_PRIORITY_NORMAL, OT_HISTORY_TRACKER_MSG_PRIORITY_HIGH = OT_MESSAGE_PRIORITY_HIGH, OT_HISTORY_TRACKER_MSG_PRIORITY_NET = OT_MESSAGE_PRIORITY_HIGH + 1 }`	enum Constants representing message priority used in `otHistoryTrackerMessageInfo` struct.
`otHistoryTrackerAddressEvent{ OT_HISTORY_TRACKER_ADDRESS_EVENT_ADDED = 0, OT_HISTORY_TRACKER_ADDRESS_EVENT_REMOVED = 1 }`	enum Defines the events for an IPv6 (unicast or multicast) address info (i.e., whether address is added or removed).
`otHistoryTrackerNeighborEvent{ OT_HISTORY_TRACKER_NEIGHBOR_EVENT_ADDED = 0, OT_HISTORY_TRACKER_NEIGHBOR_EVENT_REMOVED = 1, OT_HISTORY_TRACKER_NEIGHBOR_EVENT_CHANGED = 2, OT_HISTORY_TRACKER_NEIGHBOR_EVENT_RESTORING = 3 }`	enum Defines the events in a neighbor info (i.e.
`otHistoryTrackerNetDataEvent{ OT_HISTORY_TRACKER_NET_DATA_ENTRY_ADDED = 0, OT_HISTORY_TRACKER_NET_DATA_ENTRY_REMOVED = 1 }`	enum Defines the events for a Network Data entry (i.e., whether an entry is added or removed).
`otHistoryTrackerRouterEvent{ OT_HISTORY_TRACKER_ROUTER_EVENT_ADDED = 0, OT_HISTORY_TRACKER_ROUTER_EVENT_REMOVED = 1, OT_HISTORY_TRACKER_ROUTER_EVENT_NEXT_HOP_CHANGED = 2, OT_HISTORY_TRACKER_ROUTER_EVENT_COST_CHANGED = 3 }`	enum Defines the events in a router info (i.e.

Typedefs
`otHistoryTrackerExternalRouteInfo`	typedef `struct otHistoryTrackerExternalRouteInfo` Represent a Network Data extern route info.
`otHistoryTrackerIterator`	typedef `struct otHistoryTrackerIterator` Represents an iterator to iterate through a history list.
`otHistoryTrackerMessageInfo`	typedef `struct otHistoryTrackerMessageInfo` Represents a RX/TX IPv6 message info.
`otHistoryTrackerMulticastAddressInfo`	typedef `struct otHistoryTrackerMulticastAddressInfo` Represent an IPv6 multicast address info.
`otHistoryTrackerNeighborInfo`	typedef `struct otHistoryTrackerNeighborInfo` Represents a neighbor info.
`otHistoryTrackerNetworkInfo`	typedef `struct otHistoryTrackerNetworkInfo` Represents Thread network info.
`otHistoryTrackerOnMeshPrefixInfo`	typedef `struct otHistoryTrackerOnMeshPrefixInfo` Represent a Network Data on mesh prefix info.
`otHistoryTrackerRouterInfo`	typedef `struct otHistoryTrackerRouterInfo` Represents a router table entry event.
`otHistoryTrackerUnicastAddressInfo`	typedef `struct otHistoryTrackerUnicastAddressInfo` Represent a unicast IPv6 address info.

Functions
`otHistoryTrackerEntryAgeToString(uint32_t aEntryAge, char *aBuffer, uint16_t aSize)`	`void` Converts a given entry age to a human-readable string.
`otHistoryTrackerInitIterator(otHistoryTrackerIterator *aIterator)`	`void` Initializes an `otHistoryTrackerIterator`.
`otHistoryTrackerIterateExternalRouteHistory(otInstance aInstance, otHistoryTrackerIterator aIterator, uint32_t *aEntryAge)`	`const otHistoryTrackerExternalRouteInfo *` Iterates over the entries in the Network Data external route entry history list.
`otHistoryTrackerIterateMulticastAddressHistory(otInstance aInstance, otHistoryTrackerIterator aIterator, uint32_t *aEntryAge)`	`const otHistoryTrackerMulticastAddressInfo *` Iterates over the entries in the multicast address history list.
`otHistoryTrackerIterateNeighborHistory(otInstance aInstance, otHistoryTrackerIterator aIterator, uint32_t *aEntryAge)`	`const otHistoryTrackerNeighborInfo *` Iterates over the entries in the neighbor history list.
`otHistoryTrackerIterateNetInfoHistory(otInstance aInstance, otHistoryTrackerIterator aIterator, uint32_t *aEntryAge)`	`const otHistoryTrackerNetworkInfo *` Iterates over the entries in the network info history list.
`otHistoryTrackerIterateOnMeshPrefixHistory(otInstance aInstance, otHistoryTrackerIterator aIterator, uint32_t *aEntryAge)`	`const otHistoryTrackerOnMeshPrefixInfo *` Iterates over the entries in the Network Data on mesh prefix entry history list.
`otHistoryTrackerIterateRouterHistory(otInstance aInstance, otHistoryTrackerIterator aIterator, uint32_t *aEntryAge)`	`const otHistoryTrackerRouterInfo *` Iterates over the entries in the router history list.
`otHistoryTrackerIterateRxHistory(otInstance aInstance, otHistoryTrackerIterator aIterator, uint32_t *aEntryAge)`	`const otHistoryTrackerMessageInfo *` Iterates over the entries in the RX message history list.
`otHistoryTrackerIterateTxHistory(otInstance aInstance, otHistoryTrackerIterator aIterator, uint32_t *aEntryAge)`	`const otHistoryTrackerMessageInfo *` Iterates over the entries in the TX message history list.
`otHistoryTrackerIterateUnicastAddressHistory(otInstance aInstance, otHistoryTrackerIterator aIterator, uint32_t *aEntryAge)`	`const otHistoryTrackerUnicastAddressInfo *` Iterates over the entries in the unicast address history list.

Macros
`OT_HISTORY_TRACKER_ENTRY_AGE_STRING_SIZE 21`	Recommended size for string representation of an entry age.
`OT_HISTORY_TRACKER_INFINITE_PATH_COST 0`	Infinite path cost - used in `otHistoryTrackerRouterInfo`.
`OT_HISTORY_TRACKER_MAX_AGE (49 * 24 * 60 * 60 * 1000u)`	This constant specifies the maximum age of entries which is 49 days (in msec).
`OT_HISTORY_TRACKER_NO_NEXT_HOP 63`	No next hop - For `mNextHop` in `otHistoryTrackerRouterInfo`.

Structs
otHistoryTrackerExternalRouteInfo	Represent a Network Data extern route info.
otHistoryTrackerIterator	Represents an iterator to iterate through a history list.
otHistoryTrackerMessageInfo	Represents a RX/TX IPv6 message info.
otHistoryTrackerMulticastAddressInfo	Represent an IPv6 multicast address info.
otHistoryTrackerNeighborInfo	Represents a neighbor info.
otHistoryTrackerNetworkInfo	Represents Thread network info.
otHistoryTrackerOnMeshPrefixInfo	Represent a Network Data on mesh prefix info.
otHistoryTrackerRouterInfo	Represents a router table entry event.
otHistoryTrackerUnicastAddressInfo	Represent a unicast IPv6 address info.

Enumerations

Anonymous Enum 2

 Anonymous Enum 2

Constants representing message priority used in otHistoryTrackerMessageInfo struct.

Properties
`OT_HISTORY_TRACKER_MSG_PRIORITY_HIGH`	High priority level.
`OT_HISTORY_TRACKER_MSG_PRIORITY_LOW`	Low priority level.
`OT_HISTORY_TRACKER_MSG_PRIORITY_NET`	Network Control priority level.
`OT_HISTORY_TRACKER_MSG_PRIORITY_NORMAL`	Normal priority level.

otHistoryTrackerAddressEvent

 otHistoryTrackerAddressEvent

Defines the events for an IPv6 (unicast or multicast) address info (i.e., whether address is added or removed).

Properties
`OT_HISTORY_TRACKER_ADDRESS_EVENT_ADDED`	Address is added.
`OT_HISTORY_TRACKER_ADDRESS_EVENT_REMOVED`	Address is removed.

otHistoryTrackerNeighborEvent

 otHistoryTrackerNeighborEvent

Defines the events in a neighbor info (i.e.

whether neighbor is added, removed, or changed).

Event OT_HISTORY_TRACKER_NEIGHBOR_EVENT_RESTORING is applicable to child neighbors only. It is triggered after the device (re)starts and when the previous children list is retrieved from non-volatile settings and the device tries to restore connection to them.

Properties
`OT_HISTORY_TRACKER_NEIGHBOR_EVENT_ADDED`	Neighbor is added.
`OT_HISTORY_TRACKER_NEIGHBOR_EVENT_CHANGED`	Neighbor changed (e.g., device mode flags changed).
`OT_HISTORY_TRACKER_NEIGHBOR_EVENT_REMOVED`	Neighbor is removed.
`OT_HISTORY_TRACKER_NEIGHBOR_EVENT_RESTORING`	Neighbor is being restored (applicable to child only).

otHistoryTrackerNetDataEvent

 otHistoryTrackerNetDataEvent

Defines the events for a Network Data entry (i.e., whether an entry is added or removed).

Properties
`OT_HISTORY_TRACKER_NET_DATA_ENTRY_ADDED`	Network data entry is added.
`OT_HISTORY_TRACKER_NET_DATA_ENTRY_REMOVED`	Network data entry is removed.

otHistoryTrackerRouterEvent

 otHistoryTrackerRouterEvent

Defines the events in a router info (i.e.

whether router is added, removed, or changed).

Properties
`OT_HISTORY_TRACKER_ROUTER_EVENT_ADDED`	Router is added (router ID allocated).
`OT_HISTORY_TRACKER_ROUTER_EVENT_COST_CHANGED`	Router entry path cost changed (next hop as before).
`OT_HISTORY_TRACKER_ROUTER_EVENT_NEXT_HOP_CHANGED`	Router entry next hop and cost changed.
`OT_HISTORY_TRACKER_ROUTER_EVENT_REMOVED`	Router entry is removed (router ID released).

Typedefs

otHistoryTrackerExternalRouteInfo

struct otHistoryTrackerExternalRouteInfo otHistoryTrackerExternalRouteInfo

Represent a Network Data extern route info.

otHistoryTrackerIterator

struct otHistoryTrackerIterator otHistoryTrackerIterator

Represents an iterator to iterate through a history list.

The fields in this type are opaque (intended for use by OpenThread core) and therefore should not be accessed/used by caller.

Before using an iterator, it MUST be initialized using otHistoryTrackerInitIterator(),

otHistoryTrackerMessageInfo

struct otHistoryTrackerMessageInfo otHistoryTrackerMessageInfo

Represents a RX/TX IPv6 message info.

Some of the fields in this struct are applicable to a RX message or a TX message only, e.g., mAveRxRss is the average RSS of all fragment frames that form a received message and is only applicable for a RX message.

otHistoryTrackerMulticastAddressInfo

struct otHistoryTrackerMulticastAddressInfo otHistoryTrackerMulticastAddressInfo

Represent an IPv6 multicast address info.

otHistoryTrackerNeighborInfo

struct otHistoryTrackerNeighborInfo otHistoryTrackerNeighborInfo

Represents a neighbor info.

otHistoryTrackerNetworkInfo

struct otHistoryTrackerNetworkInfo otHistoryTrackerNetworkInfo

Represents Thread network info.

otHistoryTrackerOnMeshPrefixInfo

struct otHistoryTrackerOnMeshPrefixInfo otHistoryTrackerOnMeshPrefixInfo

Represent a Network Data on mesh prefix info.

otHistoryTrackerRouterInfo

struct otHistoryTrackerRouterInfo otHistoryTrackerRouterInfo

Represents a router table entry event.

otHistoryTrackerUnicastAddressInfo

struct otHistoryTrackerUnicastAddressInfo otHistoryTrackerUnicastAddressInfo

Represent a unicast IPv6 address info.

Functions

otHistoryTrackerEntryAgeToString

void otHistoryTrackerEntryAgeToString(
  uint32_t aEntryAge,
  char *aBuffer,
  uint16_t aSize
)

Converts a given entry age to a human-readable string.

The entry age string follows the format hours:minutes:seconds:milliseconds (if shorter than one day) or days:hours:minutes:seconds(if longer than one day).

If the resulting string does not fit in aBuffer (within its aSize characters), the string will be truncated but the outputted string is always null-terminated.

Details

Parameters

`[in] aEntryAge`	The entry age (duration in msec).
`[out] aBuffer`	A pointer to a char array to output the string (MUST NOT be NULL).
`[in] aSize`	The size of `aBuffer`. Recommended to use `OT_HISTORY_TRACKER_ENTRY_AGE_STRING_SIZE`.

otHistoryTrackerInitIterator

void otHistoryTrackerInitIterator(
  otHistoryTrackerIterator *aIterator
)

Initializes an otHistoryTrackerIterator.

An iterator MUST be initialized before it is used.

An iterator can be initialized again to start from the beginning of the list.

When iterating over entries in a list, to ensure the entry ages are consistent, the age is given relative to the time the iterator was initialized, i.e., the entry age is provided as the duration (in milliseconds) from the event (when entry was recorded) to the iterator initialization time.

Details

Parameters

[in] aIterator

A pointer to the iterator to initialize (MUST NOT be NULL).

otHistoryTrackerIterateExternalRouteHistory

const otHistoryTrackerExternalRouteInfo * otHistoryTrackerIterateExternalRouteHistory(
  otInstance *aInstance,
  otHistoryTrackerIterator *aIterator,
  uint32_t *aEntryAge
)

Iterates over the entries in the Network Data external route entry history list.

Details

Parameters

`[in] aInstance`	A pointer to the OpenThread instance.
`[in,out] aIterator`	A pointer to an iterator. MUST be initialized or the behavior is undefined.
`[out] aEntryAge`	A pointer to a variable to output the entry's age. MUST NOT be NULL. Age is provided as the duration (in milliseconds) from when entry was recorded to `aIterator` initialization time. It is set to `OT_HISTORY_TRACKER_MAX_AGE` for entries older than max age.

Returns

The otHistoryTrackerExternalRouteInfo entry or NULL if no more entries in the list.

otHistoryTrackerIterateMulticastAddressHistory

const otHistoryTrackerMulticastAddressInfo * otHistoryTrackerIterateMulticastAddressHistory(
  otInstance *aInstance,
  otHistoryTrackerIterator *aIterator,
  uint32_t *aEntryAge
)

Iterates over the entries in the multicast address history list.

Details

Parameters

`[in] aInstance`	A pointer to the OpenThread instance.
`[in,out] aIterator`	A pointer to an iterator. MUST be initialized or the behavior is undefined.
`[out] aEntryAge`	A pointer to a variable to output the entry's age. MUST NOT be NULL. Age is provided as the duration (in milliseconds) from when entry was recorded to `aIterator` initialization time. It is set to `OT_HISTORY_TRACKER_MAX_AGE` for entries older than max age.

Returns

A pointer to otHistoryTrackerMulticastAddressInfo entry or NULL if no more entries in the list.

otHistoryTrackerIterateNeighborHistory

const otHistoryTrackerNeighborInfo * otHistoryTrackerIterateNeighborHistory(
  otInstance *aInstance,
  otHistoryTrackerIterator *aIterator,
  uint32_t *aEntryAge
)

Iterates over the entries in the neighbor history list.

Details

Parameters

`[in] aInstance`	A pointer to the OpenThread instance.
`[in,out] aIterator`	A pointer to an iterator. MUST be initialized or the behavior is undefined.
`[out] aEntryAge`	A pointer to a variable to output the entry's age. MUST NOT be NULL. Age is provided as the duration (in milliseconds) from when entry was recorded to `aIterator` initialization time. It is set to `OT_HISTORY_TRACKER_MAX_AGE` for entries older than max age.

Returns

The otHistoryTrackerNeighborInfo entry or NULL if no more entries in the list.

otHistoryTrackerIterateNetInfoHistory

const otHistoryTrackerNetworkInfo * otHistoryTrackerIterateNetInfoHistory(
  otInstance *aInstance,
  otHistoryTrackerIterator *aIterator,
  uint32_t *aEntryAge
)

Iterates over the entries in the network info history list.

Details

Parameters

`[in] aInstance`	A pointer to the OpenThread instance.
`[in,out] aIterator`	A pointer to an iterator. MUST be initialized or the behavior is undefined.
`[out] aEntryAge`	A pointer to a variable to output the entry's age. MUST NOT be NULL. Age is provided as the duration (in milliseconds) from when entry was recorded to `aIterator` initialization time. It is set to `OT_HISTORY_TRACKER_MAX_AGE` for entries older than max age.

Returns

A pointer to otHistoryTrackerNetworkInfo entry or NULL if no more entries in the list.

otHistoryTrackerIterateOnMeshPrefixHistory

const otHistoryTrackerOnMeshPrefixInfo * otHistoryTrackerIterateOnMeshPrefixHistory(
  otInstance *aInstance,
  otHistoryTrackerIterator *aIterator,
  uint32_t *aEntryAge
)

Iterates over the entries in the Network Data on mesh prefix entry history list.

Details

Parameters

`[in] aInstance`	A pointer to the OpenThread instance.
`[in,out] aIterator`	A pointer to an iterator. MUST be initialized or the behavior is undefined.
`[out] aEntryAge`	A pointer to a variable to output the entry's age. MUST NOT be NULL. Age is provided as the duration (in milliseconds) from when entry was recorded to `aIterator` initialization time. It is set to `OT_HISTORY_TRACKER_MAX_AGE` for entries older than max age.

Returns

The otHistoryTrackerOnMeshPrefixInfo entry or NULL if no more entries in the list.

otHistoryTrackerIterateRouterHistory

const otHistoryTrackerRouterInfo * otHistoryTrackerIterateRouterHistory(
  otInstance *aInstance,
  otHistoryTrackerIterator *aIterator,
  uint32_t *aEntryAge
)

Iterates over the entries in the router history list.

Details

Parameters

`[in] aInstance`	A pointer to the OpenThread instance.
`[in,out] aIterator`	A pointer to an iterator. MUST be initialized or the behavior is undefined.
`[out] aEntryAge`	A pointer to a variable to output the entry's age. MUST NOT be NULL. Age is provided as the duration (in milliseconds) from when entry was recorded to `aIterator` initialization time. It is set to `OT_HISTORY_TRACKER_MAX_AGE` for entries older than max age.

Returns

The otHistoryTrackerRouterInfo entry or NULL if no more entries in the list.

otHistoryTrackerIterateRxHistory

const otHistoryTrackerMessageInfo * otHistoryTrackerIterateRxHistory(
  otInstance *aInstance,
  otHistoryTrackerIterator *aIterator,
  uint32_t *aEntryAge
)

Iterates over the entries in the RX message history list.

Details

Parameters

`[in] aInstance`	A pointer to the OpenThread instance.
`[in,out] aIterator`	A pointer to an iterator. MUST be initialized or the behavior is undefined.
`[out] aEntryAge`	A pointer to a variable to output the entry's age. MUST NOT be NULL. Age is provided as the duration (in milliseconds) from when entry was recorded to `aIterator` initialization time. It is set to `OT_HISTORY_TRACKER_MAX_AGE` for entries older than max age.

Returns

The otHistoryTrackerMessageInfo entry or NULL if no more entries in the list.

otHistoryTrackerIterateTxHistory

const otHistoryTrackerMessageInfo * otHistoryTrackerIterateTxHistory(
  otInstance *aInstance,
  otHistoryTrackerIterator *aIterator,
  uint32_t *aEntryAge
)

Iterates over the entries in the TX message history list.

Details

Parameters

`[in] aInstance`	A pointer to the OpenThread instance.
`[in,out] aIterator`	A pointer to an iterator. MUST be initialized or the behavior is undefined.
`[out] aEntryAge`	A pointer to a variable to output the entry's age. MUST NOT be NULL. Age is provided as the duration (in milliseconds) from when entry was recorded to `aIterator` initialization time. It is set to `OT_HISTORY_TRACKER_MAX_AGE` for entries older than max age.

Returns

The otHistoryTrackerMessageInfo entry or NULL if no more entries in the list.

otHistoryTrackerIterateUnicastAddressHistory

const otHistoryTrackerUnicastAddressInfo * otHistoryTrackerIterateUnicastAddressHistory(
  otInstance *aInstance,
  otHistoryTrackerIterator *aIterator,
  uint32_t *aEntryAge
)

Iterates over the entries in the unicast address history list.

Details

Parameters

`[in] aInstance`	A pointer to the OpenThread instance.
`[in,out] aIterator`	A pointer to an iterator. MUST be initialized or the behavior is undefined.
`[out] aEntryAge`	A pointer to a variable to output the entry's age. MUST NOT be NULL. Age is provided as the duration (in milliseconds) from when entry was recorded to `aIterator` initialization time. It is set to `OT_HISTORY_TRACKER_MAX_AGE` for entries older than max age.

Returns

A pointer to otHistoryTrackerUnicastAddressInfo entry or NULL if no more entries in the list.

Macros

OT_HISTORY_TRACKER_ENTRY_AGE_STRING_SIZE

 OT_HISTORY_TRACKER_ENTRY_AGE_STRING_SIZE 21

Recommended size for string representation of an entry age.

OT_HISTORY_TRACKER_INFINITE_PATH_COST

 OT_HISTORY_TRACKER_INFINITE_PATH_COST 0

Infinite path cost - used in otHistoryTrackerRouterInfo.

OT_HISTORY_TRACKER_MAX_AGE

 OT_HISTORY_TRACKER_MAX_AGE (49 * 24 * 60 * 60 * 1000u)

This constant specifies the maximum age of entries which is 49 days (in msec).

Entries older than the max age will give this value as their age.

OT_HISTORY_TRACKER_NO_NEXT_HOP

 OT_HISTORY_TRACKER_NO_NEXT_HOP 63

No next hop - For mNextHop in otHistoryTrackerRouterInfo.

Resources

OpenThread API Reference topics originate from the source code, available on GitHub. For more information, or to contribute to our documentation, refer to Resources.

History Tracker

Summary

Enumerations

Typedefs

Functions

Macros

Structs

Enumerations

Anonymous Enum 2

otHistoryTrackerAddressEvent

otHistoryTrackerNeighborEvent

otHistoryTrackerNetDataEvent

otHistoryTrackerRouterEvent

Typedefs

otHistoryTrackerExternalRouteInfo

otHistoryTrackerIterator

otHistoryTrackerMessageInfo

otHistoryTrackerMulticastAddressInfo

otHistoryTrackerNeighborInfo

otHistoryTrackerNetworkInfo

otHistoryTrackerOnMeshPrefixInfo

otHistoryTrackerRouterInfo

otHistoryTrackerUnicastAddressInfo

Functions

otHistoryTrackerEntryAgeToString

otHistoryTrackerInitIterator

otHistoryTrackerIterateExternalRouteHistory

otHistoryTrackerIterateMulticastAddressHistory

otHistoryTrackerIterateNeighborHistory

otHistoryTrackerIterateNetInfoHistory

otHistoryTrackerIterateOnMeshPrefixHistory

otHistoryTrackerIterateRouterHistory

otHistoryTrackerIterateRxHistory

otHistoryTrackerIterateTxHistory

otHistoryTrackerIterateUnicastAddressHistory

Macros

OT_HISTORY_TRACKER_ENTRY_AGE_STRING_SIZE

OT_HISTORY_TRACKER_INFINITE_PATH_COST

OT_HISTORY_TRACKER_MAX_AGE

OT_HISTORY_TRACKER_NO_NEXT_HOP

Resources