History Tracker#

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

All tracked entries are timestamped.

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

Modules#

otHistoryTrackerIterator

otHistoryTrackerNetworkInfo

otHistoryTrackerUnicastAddressInfo

otHistoryTrackerMulticastAddressInfo

otHistoryTrackerMessageInfo

otHistoryTrackerNeighborInfo

otHistoryTrackerRouterInfo

otHistoryTrackerOnMeshPrefixInfo

otHistoryTrackerExternalRouteInfo

Enumerations#

enum
OT_HISTORY_TRACKER_ADDRESS_EVENT_ADDED = 0
OT_HISTORY_TRACKER_ADDRESS_EVENT_REMOVED = 1
}

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

enum
@1 {
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
}

Constants representing message priority used in otHistoryTrackerMessageInfo struct.

enum
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
}

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

enum
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
}

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

enum
OT_HISTORY_TRACKER_NET_DATA_ENTRY_ADDED = 0
OT_HISTORY_TRACKER_NET_DATA_ENTRY_REMOVED = 1
}

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

Typedefs#

Represents an iterator to iterate through a history list.

Represents Thread network info.

Represent a unicast IPv6 address info.

Represent an IPv6 multicast address info.

Represents a RX/TX IPv6 message info.

Represents a neighbor info.

Represents a router table entry event.

Represent a Network Data on mesh prefix info.

Represent a Network Data extern route info.

Functions#

void
otHistoryTrackerInitIterator(otHistoryTrackerIterator *aIterator)

Initializes an otHistoryTrackerIterator.

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

Iterates over the entries in the network info history list.

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

Iterates over the entries in the unicast address history list.

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

Iterates over the entries in the multicast address history list.

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

Iterates over the entries in the RX message history list.

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

Iterates over the entries in the TX message history list.

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

Iterates over the entries in the neighbor history list.

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

Iterates over the entries in the router history list.

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

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

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

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

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

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

Macros#

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

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

#define

Recommended size for string representation of an entry age.

#define

No next hop - For mNextHop in otHistoryTrackerRouterInfo.

#define

Infinite path cost - used in otHistoryTrackerRouterInfo.

Enumeration Documentation#

otHistoryTrackerAddressEvent#

otHistoryTrackerAddressEvent

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

Enumerator
OT_HISTORY_TRACKER_ADDRESS_EVENT_ADDED

Address is added.

OT_HISTORY_TRACKER_ADDRESS_EVENT_REMOVED

Address is removed.


Definition at line 89 of file include/openthread/history_tracker.h

@1#

@1

Constants representing message priority used in otHistoryTrackerMessageInfo struct.

Enumerator
OT_HISTORY_TRACKER_MSG_PRIORITY_LOW

Low priority level.

OT_HISTORY_TRACKER_MSG_PRIORITY_NORMAL

Normal priority level.

OT_HISTORY_TRACKER_MSG_PRIORITY_HIGH

High priority level.

OT_HISTORY_TRACKER_MSG_PRIORITY_NET

Network Control priority level.


Definition at line 123 of file include/openthread/history_tracker.h

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.

Enumerator
OT_HISTORY_TRACKER_NEIGHBOR_EVENT_ADDED

Neighbor is added.

OT_HISTORY_TRACKER_NEIGHBOR_EVENT_REMOVED

Neighbor is removed.

OT_HISTORY_TRACKER_NEIGHBOR_EVENT_CHANGED

Neighbor changed (e.g., device mode flags changed).

OT_HISTORY_TRACKER_NEIGHBOR_EVENT_RESTORING

Neighbor is being restored (applicable to child only).


Definition at line 161 of file include/openthread/history_tracker.h

otHistoryTrackerRouterEvent#

otHistoryTrackerRouterEvent

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

whether router is added, removed, or changed).

Enumerator
OT_HISTORY_TRACKER_ROUTER_EVENT_ADDED

Router is added (router ID allocated).

OT_HISTORY_TRACKER_ROUTER_EVENT_REMOVED

Router entry is removed (router ID released).

OT_HISTORY_TRACKER_ROUTER_EVENT_NEXT_HOP_CHANGED

Router entry next hop and cost changed.

OT_HISTORY_TRACKER_ROUTER_EVENT_COST_CHANGED

Router entry path cost changed (next hop as before).


Definition at line 187 of file include/openthread/history_tracker.h

otHistoryTrackerNetDataEvent#

otHistoryTrackerNetDataEvent

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

Enumerator
OT_HISTORY_TRACKER_NET_DATA_ENTRY_ADDED

Network data entry is added.

OT_HISTORY_TRACKER_NET_DATA_ENTRY_REMOVED

Network data entry is removed.


Definition at line 214 of file include/openthread/history_tracker.h

Typedef Documentation#

otHistoryTrackerIterator#

typedef 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(),


Definition at line 72 of file include/openthread/history_tracker.h

otHistoryTrackerNetworkInfo#

typedef struct otHistoryTrackerNetworkInfo otHistoryTrackerNetworkInfo

Represents Thread network info.


Definition at line 83 of file include/openthread/history_tracker.h

otHistoryTrackerUnicastAddressInfo#

typedef struct otHistoryTrackerUnicastAddressInfo otHistoryTrackerUnicastAddressInfo

Represent a unicast IPv6 address info.


Definition at line 108 of file include/openthread/history_tracker.h

otHistoryTrackerMulticastAddressInfo#

typedef struct otHistoryTrackerMulticastAddressInfo otHistoryTrackerMulticastAddressInfo

Represent an IPv6 multicast address info.


Definition at line 118 of file include/openthread/history_tracker.h

otHistoryTrackerMessageInfo#

typedef 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.


Definition at line 152 of file include/openthread/history_tracker.h

otHistoryTrackerNeighborInfo#

typedef struct otHistoryTrackerNeighborInfo otHistoryTrackerNeighborInfo

Represents a neighbor info.


Definition at line 182 of file include/openthread/history_tracker.h

otHistoryTrackerRouterInfo#

typedef struct otHistoryTrackerRouterInfo otHistoryTrackerRouterInfo

Represents a router table entry event.


Definition at line 209 of file include/openthread/history_tracker.h

otHistoryTrackerOnMeshPrefixInfo#

typedef struct otHistoryTrackerOnMeshPrefixInfo otHistoryTrackerOnMeshPrefixInfo

Represent a Network Data on mesh prefix info.


Definition at line 227 of file include/openthread/history_tracker.h

otHistoryTrackerExternalRouteInfo#

typedef struct otHistoryTrackerExternalRouteInfo otHistoryTrackerExternalRouteInfo

Represent a Network Data extern route info.


Definition at line 236 of file include/openthread/history_tracker.h

Function Documentation#

otHistoryTrackerInitIterator#

void otHistoryTrackerInitIterator (otHistoryTrackerIterator * aIterator)

Initializes an otHistoryTrackerIterator.

Parameters
[in]aIterator

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

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.


Definition at line 251 of file include/openthread/history_tracker.h

otHistoryTrackerIterateNetInfoHistory#

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

Iterates over the entries in the network info history list.

Parameters
[in]aInstance

A pointer to the OpenThread instance.

[inout]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.


Definition at line 265 of file include/openthread/history_tracker.h

otHistoryTrackerIterateUnicastAddressHistory#

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

Iterates over the entries in the unicast address history list.

Parameters
[in]aInstance

A pointer to the OpenThread instance.

[inout]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.


Definition at line 281 of file include/openthread/history_tracker.h

otHistoryTrackerIterateMulticastAddressHistory#

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

Iterates over the entries in the multicast address history list.

Parameters
[in]aInstance

A pointer to the OpenThread instance.

[inout]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.


Definition at line 298 of file include/openthread/history_tracker.h

otHistoryTrackerIterateRxHistory#

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

Iterates over the entries in the RX message history list.

Parameters
[in]aInstance

A pointer to the OpenThread instance.

[inout]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.


Definition at line 315 of file include/openthread/history_tracker.h

otHistoryTrackerIterateTxHistory#

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

Iterates over the entries in the TX message history list.

Parameters
[in]aInstance

A pointer to the OpenThread instance.

[inout]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.


Definition at line 331 of file include/openthread/history_tracker.h

otHistoryTrackerIterateNeighborHistory#

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

Iterates over the entries in the neighbor history list.

Parameters
[in]aInstance

A pointer to the OpenThread instance.

[inout]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.


Definition at line 347 of file include/openthread/history_tracker.h

otHistoryTrackerIterateRouterHistory#

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

Iterates over the entries in the router history list.

Parameters
[in]aInstance

A pointer to the OpenThread instance.

[inout]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.


Definition at line 363 of file include/openthread/history_tracker.h

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.

Parameters
[in]aInstance

A pointer to the OpenThread instance.

[inout]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.


Definition at line 379 of file include/openthread/history_tracker.h

otHistoryTrackerIterateExternalRouteHistory#

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

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

Parameters
[in]aInstance

A pointer to the OpenThread instance.

[inout]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.


Definition at line 395 of file include/openthread/history_tracker.h

otHistoryTrackerEntryAgeToString#

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

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

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.

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.


Definition at line 413 of file include/openthread/history_tracker.h

Macro Definition Documentation#

OT_HISTORY_TRACKER_MAX_AGE#

#define OT_HISTORY_TRACKER_MAX_AGE
Value:
(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.


Definition at line 56 of file include/openthread/history_tracker.h

OT_HISTORY_TRACKER_ENTRY_AGE_STRING_SIZE#

#define OT_HISTORY_TRACKER_ENTRY_AGE_STRING_SIZE
Value:
21

Recommended size for string representation of an entry age.


Definition at line 58 of file include/openthread/history_tracker.h

OT_HISTORY_TRACKER_NO_NEXT_HOP#

#define OT_HISTORY_TRACKER_NO_NEXT_HOP
Value:
63

No next hop - For mNextHop in otHistoryTrackerRouterInfo.


Definition at line 195 of file include/openthread/history_tracker.h

OT_HISTORY_TRACKER_INFINITE_PATH_COST#

#define OT_HISTORY_TRACKER_INFINITE_PATH_COST
Value:
0

Infinite path cost - used in otHistoryTrackerRouterInfo.


Definition at line 197 of file include/openthread/history_tracker.h