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, const LogStorageResources const inLogStorageResources)` LoggingManagement constructor.
`LoggingManagement(void)` LoggingManagement default constructor.

Public functions
`BlitEvent(EventLoadOutContext aContext, const EventSchema & inSchema, EventWriterFunct inEventWriter, void inAppData, const EventOptions *inOptions)`	`WEAVE_ERROR` Helper function for writing event header and data according to event logging protocol.
`CancelShutdownInProgress(void)`	`void` Set mShutdownInProgress flag to false.
`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)`	`WEAVE_ERROR` 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.
`GetEventReader(nl::Weave::TLV::TLVReader & ioReader, ImportanceType inImportance)`	`WEAVE_ERROR` A helper method useful for examining the in-memory log buffers.
`GetFirstEventID(ImportanceType inImportance)`	`event_id_t` Fetch the first event ID currently stored for a particular importance level.
`GetLastEventID(ImportanceType inImportance)`	`event_id_t` Fetch the most recently vended ID for a particular importance level.
`IsShutdownInProgress(void)`	`bool` Check mShutdownInProgress flag.
`IsValid(void)`	`bool` IsValid returns whether the LoggingManagement instance is valid.
`LoadEvents(TLVReader & reader)`	`WEAVE_ERROR` Load previously persisted Weave event.
`LogEvent(const EventSchema & inSchema, EventWriterFunct inEventWriter, void inAppData, const EventOptions inOptions)`	`event_id_t` Log an event via a callback, with options.
`MarkShutdownInProgress(void)`	`void` Set mShutdownInProgress flag to true.
`NotifyEventsDelivered(ImportanceType inImportance, event_id_t inLastDeliveredEventID, uint64_t inRecipientNodeID)`	`void`
`RegisterEventCallbackForImportance(ImportanceType inImportance, FetchExternalEventsFunct inFetchCallback, NotifyExternalEventsDeliveredFunct inNotifyCallback, NotifyExternalEventsEvictedFunct inEvictedCallback, size_t inNumEvents, event_id_t *outLastEventID)`	`WEAVE_ERROR` The public API for registering a set of externally stored events.
`RegisterEventCallbackForImportance(ImportanceType inImportance, FetchExternalEventsFunct inFetchCallback, NotifyExternalEventsDeliveredFunct inNotifyCallback, size_t inNumEvents, event_id_t *outLastEventID)`	`WEAVE_ERROR` The public API for registering a set of externally stored events.
`RegisterEventCallbackForImportance(ImportanceType inImportance, FetchExternalEventsFunct inFetchCallback, size_t inNumEvents, event_id_t *outLastEventID)`	`WEAVE_ERROR` The public API for registering a set of externally stored events.
`ScheduleFlushIfNeeded(bool inFlushRequested)`	`WEAVE_ERROR` Schedule a log offload task.
`SerializeEvents(TLVWriter & writer)`	`WEAVE_ERROR` Serialize the Weave events of all importance types.
`SetBDXUploader(LogBDXUpload *inUploader)`	`void`
`SetExchangeManager(nl::Weave::WeaveExchangeManager *inMgr)`	`WEAVE_ERROR` Set the WeaveExchangeManager to be used with this logging subsystem.
`SetLoggingEndpoint(event_id_t *inEventEndpoints, size_t inNumImportanceLevels, size_t & outLoggingPosition)`	`WEAVE_ERROR`
`SkipEvent(EventLoadOutContext *aContext)`	`void` Helper function to skip writing an event corresponding to an allocated event id.
`ThrottleLogger(void)`	`void` ThrottleLogger elevates the effective logging level to the Production level.
`UnregisterEventCallbackForImportance(ImportanceType inImportance, event_id_t inEventID)`	`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, const LogStorageResources const inLogStorageResources)`	`void` Create LoggingManagement object and initialize the logging management subsystem with provided resources.
`DestroyLoggingManagement(void)`	`void` Perform any actions we need to on shutdown.
`GetInstance(void)`	`LoggingManagement &`

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.

CancelShutdownInProgress

void CancelShutdownInProgress(
  void
)

Set mShutdownInProgress flag to false.

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.

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 first event ID currently stored for a particular importance level.

Details

Parameters

inImportance

Importance level

Returns

event_id_t First currently stored 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

IsShutdownInProgress

bool IsShutdownInProgress(
  void
)

Check mShutdownInProgress flag.

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

LoadEvents

WEAVE_ERROR LoadEvents(
  TLVReader & reader
)

Load previously persisted Weave event.

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,
  const LogStorageResources *const inLogStorageResources
)

LoggingManagement constructor.

Initialize the LoggingManagement with an array of LogStorageResources. The array must provide a resource for each valid importance level, the elements of the array must be in increasing numerical value of importance (and in decreasing importance); the first element in the array corresponds to the resources allocated for the most critical events, and the last element corresponds to the least important events.

Details

Parameters

`[in] inMgr`	WeaveExchangeManager to be used with this logging subsystem
`[in] inNumBuffers`	Number of elements in inLogStorageResources array
`[in] inLogStorageResources`	An array of LogStorageResources for each importance level.

LoggingManagement

 LoggingManagement(
  void
)

LoggingManagement default constructor.

Provided primarily to make the compiler happy.

Details
Returns	LoggingManagement

MarkShutdownInProgress

void MarkShutdownInProgress(
  void
)

Set mShutdownInProgress flag to true.

NotifyEventsDelivered

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

RegisterEventCallbackForImportance

WEAVE_ERROR RegisterEventCallbackForImportance(
  ImportanceType inImportance,
  FetchExternalEventsFunct inFetchCallback,
  NotifyExternalEventsDeliveredFunct inNotifyCallback,
  NotifyExternalEventsEvictedFunct inEvictedCallback,
  size_t inNumEvents,
  event_id_t *outLastEventID
)

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 both when the events have been delivered to a subscriber and if the external events object is evicted.

When the events are delivered, the external provider is notified about that along with the node ID of the recipient and the id of the 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.

If the external events object is evicted from the log buffers, the external provider is notified along with a copy of the external events object.

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

`[in] inImportance`	Importance level
`[in] inFetchCallback`	Callback to register to fetch external events
`[in] inNotifyCallback`	Callback to register for delivery notification
`[in] inEvictedCallback`	Callback to register for eviction notification
`[in] inNumEvents`	Number of events in this set
`[out] outLastEventID`	Pointer to an event_id_t; on successful registration of external events the function will store the event ID corresponding to the last event ID of the external event block. The parameter may be NULL.

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,
  NotifyExternalEventsDeliveredFunct inNotifyCallback,
  size_t inNumEvents,
  event_id_t *outLastEventID
)

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

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, but not when the external events object is evicted. When the events are delivered, the external provider is notified about that along with the node ID of the recipient and the id of the 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.

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

Details

Parameters

`[in] inImportance`	Importance level
`[in] inCallback`	Callback to register to fetch external events
`[in] inNotifyCallback`	Callback to register for delivery notification
`[in] inNumEvents`	Number of events in this set
`[out] outLastEventID`	Pointer to an event_id_t; on successful registration of external events the function will store the event ID corresponding to the last event ID of the external event block. The parameter may be NULL.

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,
  event_id_t *outLastEventID
)

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

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 desires a notifification neither when the external events have been delivered nor when the external events object is evicted.

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

Details

Parameters

`[in] inImportance`	Importance level
`[in] inCallback`	Callback to register to fetch external events
`[in] inNumEvents`	Number of events in this set
`[out] outLastEventID`	Pointer to an event_id_t; on successful registration of external events the function will store the event ID corresponding to the last event ID of the external event block. The parameter may be NULL.

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.

SerializeEvents

WEAVE_ERROR SerializeEvents(
  TLVWriter & writer
)

Serialize the Weave events of all importance types.

Serializes the events in WeaveCircularTLVBuffer and the associated states into the supplied buffer.

This method is intended to be used by devices that do not retain RAM while sleeping, allowing them to persist events before going to sleep and thereby prevent lost of events

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
)

SkipEvent

void SkipEvent(
  EventLoadOutContext *aContext
)

Helper function to skip writing an event corresponding to an allocated event id.

Details

Parameters

[in,out] aContext

EventLoadOutContext, initialized with stateful information for the buffer. State is updated and preserved by BlitEvent using this context.

ThrottleLogger

void ThrottleLogger(
  void
)

ThrottleLogger elevates the effective logging level to the Production level.

UnregisterEventCallbackForImportance

void UnregisterEventCallbackForImportance(
  ImportanceType inImportance,
  event_id_t inEventID
)

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

`[in] inImportance`	Importance level
`[in] inEventID`	An event ID corresponding to any of the events in the external event block to be unregistered.

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,
  const LogStorageResources *const inLogStorageResources
)

Create LoggingManagement object and initialize the logging management subsystem with provided resources.

Details

Parameters

`[in] inMgr`	WeaveExchangeManager to be used with this logging subsystem
`[in] inNumBuffers`	Number of elements in inLogStorageResources array
`[in] inLogStorageResources`	An array of LogStorageResources for each importance level.

DestroyLoggingManagement

void DestroyLoggingManagement(
  void
)

Perform any actions we need to on shutdown.

GetInstance

LoggingManagement & GetInstance(
  void
)

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

Summary

Constructors and Destructors

Public functions

Public static functions

Public functions

BlitEvent

CancelShutdownInProgress

CheckShouldRunWDM

FetchEventsSince

GetBytesWritten

GetEventReader

GetFirstEventID

GetLastEventID

IsShutdownInProgress

IsValid

LoadEvents

LogEvent

LoggingManagement

LoggingManagement

MarkShutdownInProgress

NotifyEventsDelivered

RegisterEventCallbackForImportance

RegisterEventCallbackForImportance

RegisterEventCallbackForImportance

ScheduleFlushIfNeeded

SerializeEvents

SetBDXUploader

SetExchangeManager

SetLoggingEndpoint

SkipEvent

ThrottleLogger

UnregisterEventCallbackForImportance

UnthrottleLogger

Public static functions

CreateLoggingManagement

DestroyLoggingManagement

GetInstance