nl::Weave::Profiles::DataManagement_Current::LoggingManagement

#include <src/lib/profiles/data-management/Current/LoggingManagement.h>

A class for managing the in memory event logs.

Summary

Constructors and Destructors

LoggingManagement(nl::Weave::WeaveExchangeManager *inMgr, size_t inNumBuffers, size_t *inBufferLengths, void **inBuffers, nl::Weave::Platform::PersistedStorage::Key *inCounterKeys, const uint32_t *inCounterEpochs, nl::Weave::PersistedCounter **inCounterStorage)
LoggingManagement constructor.
LoggingManagement(nl::Weave::WeaveExchangeManager *inMgr, size_t inNumBuffers, size_t *inBufferLengths, void **inBuffers, nl::Weave::MonotonicallyIncreasingCounter **nWeaveCounter)
LoggingManagement constructor.
LoggingManagement(void)
LoggingManagement default constructor.

Public functions

BlitEvent(EventLoadOutContext *aContext, const EventSchema & inSchema, EventWriterFunct inEventWriter, void *inAppData, const EventOptions *inOptions)
Helper function for writing event header and data according to event logging protocol.
CheckShouldRunWDM(void)
bool
Decide whether to offload events based on the number of bytes in event buffers unscheduled for upload.
FetchEventsSince(nl::Weave::TLV::TLVWriter & ioWriter, ImportanceType inImportance, event_id_t & ioEventID)
A function to retrieve events of specified importance since a specified event ID.
GetBytesWritten(void) const
uint32_t
Get the total number of bytes written (across all event importances) to this log since its instantiation.
GetEndOfExternalEventRange(ImportanceType inImportance, event_id_t inEventID) const
For an event ID known to be stored externally, return the last event ID in that set.
GetEventReader(nl::Weave::TLV::TLVReader & ioReader, ImportanceType inImportance)
A helper method useful for examining the in-memory log buffers.
GetFirstEventID(ImportanceType inImportance)
Fetch the most recently vended ID for a particular importance level.
GetLastEventID(ImportanceType inImportance)
Fetch the most recently vended ID for a particular importance level.
IsEventExternal(ImportanceType inImportance, event_id_t inEventID) const
bool
IsEventExternal checks whether inEventID is stored by the platform.
IsValid(void)
bool
IsValid returns whether the LoggingManagement instance is valid.
LogEvent(const EventSchema & inSchema, EventWriterFunct inEventWriter, void *inAppData, const EventOptions *inOptions)
Log an event via a callback, with options.
NotifyEventsDelivered(ImportanceType inImportance, event_id_t inLastDeliveredEventID, uint64_t inRecipientNodeID) const
void
RegisterEventCallbackForImportance(ImportanceType inImportance, FetchExternalEventsFunct inFetchCallback, NotifyExternalEventsDeliveredFunct inNotifyCallback, size_t inNumEvents, ExternalEvents **aExternalEventsPtr)
The public API for registering a set of externally stored events.
RegisterEventCallbackForImportance(ImportanceType inImportance, FetchExternalEventsFunct inFetchCallback, size_t inNumEvents, ExternalEvents **aExternalEventsPtr)
The public API for registering a set of externally stored events.
ScheduleFlushIfNeeded(bool inFlushRequested)
Schedule a log offload task.
SetBDXUploader(LogBDXUpload *inUploader)
void
SetExchangeManager(nl::Weave::WeaveExchangeManager *inMgr)
Set the WeaveExchangeManager to be used with this logging subsystem.
SetLoggingEndpoint(event_id_t *inEventEndpoints, size_t inNumImportanceLevels, size_t & outLoggingPosition)
ThrottleLogger(void)
void
ThrottleLogger elevates the effective logging level to the Production level.
UnregisterEventCallbackForImportance(ImportanceType inImportance, ExternalEvents *inPtr)
void
The public API for unregistering a set of externally stored events.
UnthrottleLogger(void)
void
UnthrottleLogger restores the effective logging level to the configured logging level.

Public static functions

CreateLoggingManagement(nl::Weave::WeaveExchangeManager *inMgr, size_t inNumBuffers, size_t *inBufferLengths, void **inBuffers, nl::Weave::Platform::PersistedStorage::Key *inCounterKeys, const uint32_t *inCounterEpochs, nl::Weave::PersistedCounter **inCounterStorage)
void
Create and initialize the logging management buffers.
CreateLoggingManagement(nl::Weave::WeaveExchangeManager *inMgr, size_t inNumBuffers, size_t *inBufferLengths, void **inBuffers, nl::Weave::MonotonicallyIncreasingCounter **nWeaveCounter)
void
Create and initialize the logging management buffers.
DestroyLoggingManagement(void)
void
Perform any actions we need to on shutdown.
GetInstance(void)

Public functions

BlitEvent

WEAVE_ERROR BlitEvent(
  EventLoadOutContext *aContext,
  const EventSchema & inSchema,
  EventWriterFunct inEventWriter,
  void *inAppData,
  const EventOptions *inOptions
)

Helper function for writing event header and data according to event logging protocol.

Details
Parameters
[in,out] aContext
EventLoadOutContext, initialized with stateful information for the buffer. State is updated and preserved by BlitEvent using this context.
[in] inSchema
Schema defining importance, profile ID, and structure type of this event.
[in] inEventWriter
The callback to invoke to serialize the event data.
[in] inAppData
Application context for the callback.
[in] inOptions
EventOptions describing timestamp and other tags relevant to this event.

CheckShouldRunWDM

bool CheckShouldRunWDM(
  void
)

Decide whether to offload events based on the number of bytes in event buffers unscheduled for upload.

The behavior of the function is controlled via WEAVE_CONFIG_EVENT_LOGGING_BYTE_THRESHOLD constant. If the system wrote more than that number of bytes since the last time a WDM Notification was sent, the function will indicate it is time to trigger the NotificationEngine.

Details
Return Values
true
Events should be offloaded
false
Otherwise

FetchEventsSince

WEAVE_ERROR FetchEventsSince(
  nl::Weave::TLV::TLVWriter & ioWriter,
  ImportanceType inImportance,
  event_id_t & ioEventID
)

A function to retrieve events of specified importance since a specified event ID.

Given a nl::Weave::TLV::TLVWriter, an importance type, and an event ID, the function will fetch events of specified importance since the specified event. The function will continue fetching events until it runs out of space in the nl::Weave::TLV::TLVWriter or in the log. The function will terminate the event writing on event boundary.

Details
Parameters
[in] ioWriter
The writer to use for event storage
[in] inImportance
The importance of events to be fetched
[in,out] ioEventID
On input, the ID of the event immediately prior to the one we're fetching. On completion, the ID of the last event fetched.
Return Values
WEAVE_END_OF_TLV
The function has reached the end of the available log entries at the specified importance level
WEAVE_ERROR_NO_MEMORY
The function ran out of space in the ioWriter, more events in the log are available.
WEAVE_ERROR_BUFFER_TOO_SMALL
The function ran out of space in the ioWriter, more events in the log are available.

GetBytesWritten

uint32_t GetBytesWritten(
  void
) const 

Get the total number of bytes written (across all event importances) to this log since its instantiation.

Details
Returns
The number of bytes written to the log.

GetEndOfExternalEventRange

event_id_t GetEndOfExternalEventRange(
  ImportanceType inImportance,
  event_id_t inEventID
) const 

For an event ID known to be stored externally, return the last event ID in that set.

Details
Returns
The last event ID of a group of event IDs.

GetEventReader

WEAVE_ERROR GetEventReader(
  nl::Weave::TLV::TLVReader & ioReader,
  ImportanceType inImportance
)

A helper method useful for examining the in-memory log buffers.

Details
Parameters
[in,out] ioReader
A reference to the reader that will be initialized with the backing storage from the event log
[in] inImportance
The starting importance for the reader. Note that in this case the starting importance is somewhat counter intuitive: more important events share the buffers with less important events, in addition to their dedicated buffers. As a result, the reader will traverse the least data when the Debug importance is passed in.
Returns
WEAVE_NO_ERROR Unconditionally.

GetFirstEventID

event_id_t GetFirstEventID(
  ImportanceType inImportance
)

Fetch the most recently vended ID for a particular importance level.

Details
Parameters
inImportance
Importance level
Returns
event_id_t most recently vended event ID for that event importance

GetLastEventID

event_id_t GetLastEventID(
  ImportanceType inImportance
)

Fetch the most recently vended ID for a particular importance level.

Details
Parameters
inImportance
Importance level
Returns
event_id_t most recently vended event ID for that event importance

IsEventExternal

bool IsEventExternal(
  ImportanceType inImportance,
  event_id_t inEventID
) const 

IsEventExternal checks whether inEventID is stored by the platform.

Details
Return Values
true
The event is stored externally.
false
The event is not stored externally.

IsValid

bool IsValid(
  void
)

IsValid returns whether the LoggingManagement instance is valid.

Details
Return Values
true
The instance is valid (initialized with the appropriate backing store)
false
Otherwise

LogEvent

event_id_t LogEvent(
  const EventSchema & inSchema,
  EventWriterFunct inEventWriter,
  void *inAppData,
  const EventOptions *inOptions
)

Log an event via a callback, with options.

The function logs an event represented as an EventWriterFunct and an app-specific appData context. The function writes the event metadata and calls the inEventWriter with an nl::Weave::TLV::TLVWriter reference and inAppData context so that the user code can emit the event data directly into the event log. This form of event logging minimizes memory consumption, as event data is serialized directly into the target buffer. The event data MUST contain context tags to be interpreted within the schema identified by inProfileID and inEventType. The tag of the first element will be ignored; the event logging system will replace it with the eventData tag.

The event is logged if the schema importance exceeds the logging threshold specified in the LoggingConfiguration. If the event's importance does not meet the current threshold, it is dropped and the function returns a 0 as the resulting event ID.

This variant of the invocation permits the caller to set any combination of EventOptions:

  • timestamp, when 0 defaults to the current time at the point of the call,
  • "root" section of the event source (event source and trait ID); if NULL, it defaults to the current device. the event is marked as relating to the device that is making the call,
  • a related event ID for grouping event IDs; when the related event ID is 0, the event is marked as not relating to any other events,
  • urgency; by default non-urgent.

Details
Parameters
[in] inSchema
Schema defining importance, profile ID, and structure type of this event.
[in] inEventWriter
The callback to invoke to actually serialize the event data
[in] inAppData
Application context for the callback.
[in] inOptions
The options for the event metadata. May be NULL.
Returns
event_id_t The event ID if the event was written to the log, 0 otherwise.

LoggingManagement

 LoggingManagement(
  nl::Weave::WeaveExchangeManager *inMgr,
  size_t inNumBuffers,
  size_t *inBufferLengths,
  void **inBuffers,
  nl::Weave::Platform::PersistedStorage::Key *inCounterKeys,
  const uint32_t *inCounterEpochs,
  nl::Weave::PersistedCounter **inCounterStorage
)

LoggingManagement constructor.

For prioritization to work correctly, inBuffers must be incrementally increasing in priority.

Details
Parameters
[in] inMgr
WeaveExchangeManager to be used with this logging subsystem
[in] inNumBuffers
Number of buffers to use for event storage
[in] inBufferLengths
Description of inBufferLengths
[in] inBuffers
The buffers to use for actual event logging.
[in] inCounterKeys
Keys naming persisted counters
[in] inCounterEpochs
An array of epochs for each of the persisted counters
[in] inCounterStorage
Application-provided storage for the persistent counters
Returns

LoggingManagement

 LoggingManagement(
  nl::Weave::WeaveExchangeManager *inMgr,
  size_t inNumBuffers,
  size_t *inBufferLengths,
  void **inBuffers,
  nl::Weave::MonotonicallyIncreasingCounter **nWeaveCounter
)

LoggingManagement constructor.

For prioritization to work correctly, inBuffers must be incrementally increasing in priority.

Details
Parameters
[in] inMgr
WeaveExchangeManager to be used with this logging subsystem.
[in] inNumBuffers
Number of buffers to use for event storage.
[in] inBufferLengths
Description of inBufferLengths.
[in] inBuffers
The buffers to use for actual event logging.
[in] nWeaveCounter
The array of counter pointers must contain the initialized counters, and has to contain inNumBuffers of counters.
Returns

LoggingManagement

 LoggingManagement(
  void
)

LoggingManagement default constructor.

Provided primarily to make the compiler happy.

Details
Returns

NotifyEventsDelivered

void NotifyEventsDelivered(
  ImportanceType inImportance,
  event_id_t inLastDeliveredEventID,
  uint64_t inRecipientNodeID
) const 

RegisterEventCallbackForImportance

WEAVE_ERROR RegisterEventCallbackForImportance(
  ImportanceType inImportance,
  FetchExternalEventsFunct inFetchCallback,
  NotifyExternalEventsDeliveredFunct inNotifyCallback,
  size_t inNumEvents,
  ExternalEvents **aExternalEventsPtr
)

The public API for registering a set of externally stored events.

Register a callback of form FetchExternalEventsFunct. This API requires the platform to know the number of events on registration. The internal workings also require this number to be constant. Since this API does not allow the platform to register specific event IDs, this prevents the platform from persisting storage of events (at least with unique event IDs).

The callback will be called whenever a subscriber attempts to fetch event IDs within the range any number of times until it is unregistered.

This variant of the function should be used when the external provider wants to be notified when the events have been delivered to a subscriber. When the events are delivered, the external provider is notified that about the node ID of the recipient and last event delivered to that recipient. Note that the external provider may be notified several times for the same event ID. There are no specific restrictions on the handler, in particular, the handler may unregister the external event IDs.

The pointer to the ExternalEvents struct will be NULL on failure, otherwise will be populated with start and end event IDs assigned to the callback. This pointer should be used to unregister the set of events.

See the documentation for FetchExternalEventsFunct for details on what the callback must implement.

Details
Parameters
inImportance
Importance level
inFetchCallback
Callback to register to fetch external events
inNotifyCallback
Callback to register for delivery notification
inNumEvents
Number of events in this set
aExternalEventsPtr
Pointer to ExternalEvents struct.
Return Values
WEAVE_ERROR_NO_MEMORY
If no more callback slots are available.
WEAVE_ERROR_INVALID_ARGUMENT
Null function callback or no events to register.
WEAVE_NO_ERROR
On success.

RegisterEventCallbackForImportance

WEAVE_ERROR RegisterEventCallbackForImportance(
  ImportanceType inImportance,
  FetchExternalEventsFunct inFetchCallback,
  size_t inNumEvents,
  ExternalEvents **aExternalEventsPtr
)

The public API for registering a set of externally stored events.

Register a callback of form FetchExternalEventsFunct. This API requires the platform to know the number of events on registration. The internal workings also require this number to be constant. Since this API does not allow the platform to register specific event IDs, this prevents the platform from persisting storage of events (at least with unique event IDs).

The callback will be called whenever a subscriber attempts to fetch event IDs within the range any number of times until it is unregistered.

This variant of the function should be used when the external provider does not care to be notified when the external events have been delivered.

The pointer to the ExternalEvents struct will be NULL on failure, otherwise will be populated with start and end event IDs assigned to the callback. This pointer should be used to unregister the set of events.

See the documentation for FetchExternalEventsFunct for details on what the callback must implement.

Details
Parameters
inImportance
Importance level
inCallback
Callback to register to fetch external events
inNumEvents
Number of events in this set
aExternalEventsPtr
Pointer to ExternalEvents struct.
Return Values
WEAVE_ERROR_NO_MEMORY
If no more callback slots are available.
WEAVE_ERROR_INVALID_ARGUMENT
Null function callback or no events to register.
WEAVE_NO_ERROR
On success.

ScheduleFlushIfNeeded

WEAVE_ERROR ScheduleFlushIfNeeded(
  bool inFlushRequested
)

Schedule a log offload task.

The function decides whether to schedule a task offload process, and if so, it schedules the LoggingFlushHandler to be run asynchronously on the Weave thread.

The decision to schedule a flush is dependent on three factors:

an explicit request to flush the buffer

the state of the event buffer and the amount of data not yet synchronized with the event consumers

whether there is an already pending request flush request event.

The explicit request to schedule a flush is passed via an input parameter.

The automatic flush is typically scheduled when the event buffers contain enough data to merit starting a new offload. Additional triggers such as minimum and maximum time between offloads may also be taken into account depending on the offload strategy.

The pending state of the event log is indicated by mUploadRequested variable. Since this function can be called by multiple threads, mUploadRequested must be atomically read and set, to avoid scheduling a redundant LoggingFlushHandler before the notification has been sent.

Details
Parameters
inRequestFlush
A boolean value indicating whether the flush should be scheduled regardless of internal buffer management policy.
Return Values
WEAVE_ERROR_INCORRECT_STATE
LoggingManagement module was not initialized fully.
WEAVE_NO_ERROR
On success.

SetBDXUploader

void SetBDXUploader(
  LogBDXUpload *inUploader
)

SetExchangeManager

WEAVE_ERROR SetExchangeManager(
  nl::Weave::WeaveExchangeManager *inMgr
)

Set the WeaveExchangeManager to be used with this logging subsystem.

On some platforms, this may need to happen separately from CreateLoggingManagement() above.

Details
Parameters
[in] inMgr
WeaveExchangeManager to be used with this logging subsystem

SetLoggingEndpoint

WEAVE_ERROR SetLoggingEndpoint(
  event_id_t *inEventEndpoints,
  size_t inNumImportanceLevels,
  size_t & outLoggingPosition
)

ThrottleLogger

void ThrottleLogger(
  void
)

ThrottleLogger elevates the effective logging level to the Production level.

UnregisterEventCallbackForImportance

void UnregisterEventCallbackForImportance(
  ImportanceType inImportance,
  ExternalEvents *inPtr
)

The public API for unregistering a set of externally stored events.

Unregistering the callback will prevent LoggingManagement from calling the callback for a set of events. LoggingManagement will no longer send those event IDs to subscribers.

The intent is for one function to serve a set of events at a time. If a new set of events need to be registered using the same function, the callback should first be unregistered, then registered again. This means the original set of events can no longer be fetched.

This function succeeds unconditionally. If the callback was never registered or was already unregistered, it's a no-op.

Details
Parameters
inImportance
Importance level
inPtr
Pointer to ExternalEvents struct to unregister.

UnthrottleLogger

void UnthrottleLogger(
  void
)

UnthrottleLogger restores the effective logging level to the configured logging level.

Public static functions

CreateLoggingManagement

void CreateLoggingManagement(
  nl::Weave::WeaveExchangeManager *inMgr,
  size_t inNumBuffers,
  size_t *inBufferLengths,
  void **inBuffers,
  nl::Weave::Platform::PersistedStorage::Key *inCounterKeys,
  const uint32_t *inCounterEpochs,
  nl::Weave::PersistedCounter **inCounterStorage
)

Create and initialize the logging management buffers.

Must be called prior to the logging being used.

Details
Parameters
[in] inMgr
WeaveExchangeManager to be used with this logging subsystem
[in] inNumBuffers
Number of buffers to use for event storage
[in] inBufferLengths
Description of inBufferLengths
[in] inBuffers
The buffers to use for actual event logging.
[in] inCounterKeys
Keys naming persisted counters
[in] inCounterEpochs
An array of epochs for each of the persisted counters
[in] inCounterStorage
Application-provided storage for the persistent counters

CreateLoggingManagement

void CreateLoggingManagement(
  nl::Weave::WeaveExchangeManager *inMgr,
  size_t inNumBuffers,
  size_t *inBufferLengths,
  void **inBuffers,
  nl::Weave::MonotonicallyIncreasingCounter **nWeaveCounter
)

Create and initialize the logging management buffers.

Must be called prior to the logging being used.

Details
Parameters
[in] inMgr
WeaveExchangeManager to be used with this logging subsystem.
[in] inNumBuffers
Number of buffers to use for event storage.
[in] inBufferLengths
Description of inBufferLengths.
[in] inBuffers
The buffers to use for actual event logging.
[in] nWeaveCounter
The array of counter pointers must contain the initialized counters, and has to contain inNumBuffers of counters.

DestroyLoggingManagement

void DestroyLoggingManagement(
  void
)

Perform any actions we need to on shutdown.

GetInstance

LoggingManagement & GetInstance(
  void
)