Device Logging.
Log:
- organized as a ring buffer
- divided into multiple log chunks
- size is limited (based on amount of storage and not the message count)
- if size limit is reached then the oldest log messages will be removed (in log chunk granularity)
- real size may vary over time because of optional compression and chunk-wise removal of old messages
Log chunk:
- contains log messages
- usually represented by a dedicated file in the backend
- size is limited (based on amount of storage and not the message count)
- real size may vary slightly
Log messages:
- have an associated log message id
- the id is not persistent, i.e. id assignment starts from beginning when
- restarting the log service (e.g. by rebooting the device)
- clearing the log
Log message id:
- unsigned 32bit integer in the backend
- mapped to a signed 32bit integer in IDL
- when the id reaches 2^31 then the IDL representation of the id will become negative
- at 2^32 the id will wrap to 0
- the id start with 0 and is incremented by 1 with each log message
Id reset detection:
- Retrieve LogInfo via getInfo() and remember the creationTime[2].
- When retrieving log messages via getChunk() compare the logCreationTime with the creationTime from getInfo().
- If they differ then the id numbering has been reset.
Log message retrieval:
- only chunk-wise (a chunk is usually represented by a file in the backend)
- one chunk at a time
- when requested start id is in the middle of the chunk then entries before this id are not returned
- when more messages are requested as available in a chunk after the start id then only the available messages are returned
- requesting 2^31-1 (INT32_MAX) or -1 (2^32-1 (UINT32_MAX) casted to a signed 32bit integer) entries will ensure you get everything in the requested chunk after the start id
- when going forward: if start id is lower than the first id then the start id is set to the first id
- when going backward: if start id is greater than the last id then the start id is set to the last id
Examples:
Retrieving whole log forward from the beginning:
- Get current log info by calling getInfo() and remember it.
- Set the start id to idFirst from the log info.
- Get chunk by calling getChunk(FORWARD) starting at the start id and requesting -1 entries (see Log message retrieval above for why using -1 here).
- Compare chunk's logCreationTime with the creationTime from log info. If different then restart whole retrieval (log service was restarted or log was cleared).
- Process retrieved log messages if any.
- If allEntryCnt of the chunk is 0 then stop (the end of the log has been reached).
- Calculate next start id by adding idFirst and allEntryCnt of the current chunk and go to step 3.
Retrieving whole log backward from the end:
- Get current log info by calling getInfo() and remember it.
- If idNext in the logInfo is 0 then stop (log is empty).
- Set the start id to idNext-1 (i.e. one less then idNext) from the log info.
- Get chunk by calling getChunk(BACKWARD) starting at the start id and requesting -1 entries (see Log message retrieval above for why using -1 here).
- Compare chunk's logCreationTime with the creationTime from log info. If different then restart whole retrieval (log service was restarted or log was cleared).
- Process retrieved log messages if any.
- If idFirst or allEntryCnt of the chunk is 0 then stop (the start of the log has been reached).
- Calculate next start id by subtracting 1 from idFirst of the current chunk and go to step 4.
