Legrand / Raritan Xerus™ JSON-RPC API for Remote Access Devices like KX4-101, KX3G2

Loading...
Searching...
No Matches
Log.idl
1/* SPDX-License-Identifier: BSD-3-Clause */
2/*
3 * Copyright 2014 Raritan Inc. All rights reserved.
4 */
5
6#ifndef __LOG_IDL__
7#define __LOG_IDL__
8
9/** Device Logging
10 *
11 * Log:
12 * - organized as a ring buffer
13 * - divided into multiple log chunks
14 * - size is limited (based on amount of storage and not the message count)
15 * - if size limit is reached then the oldest log messages will be removed (in log chunk granularity)
16 * - real size may vary over time because of optional compression and chunk-wise removal of old messages
17 *
18 * Log chunk:
19 * - contains log messages
20 * - usually represented by a dedicated file in the backend
21 * - size is limited (based on amount of storage and not the message count)
22 * - real size may vary slightly
23 *
24 * Log messages:
25 * - have an associated log message id
26 * - the id is not persistent, i.e. id assignment starts from beginning when
27 * - restarting the log service (e.g. by rebooting the device)
28 * - clearing the log
29 *
30 * Log message id:
31 * - unsigned 32bit integer in the backend
32 * - mapped to a signed 32bit integer in IDL
33 * - when the id reaches 2^31 then the IDL representation of the id will become negative
34 * - at 2^32 the id will wrap to 0
35 * - the id start with 0 and is incremented by 1 with each log message
36 *
37 * Id reset detection:
38 * 1. Retrieve LogInfo via getInfo() and remember the creationTime[2].
39 * 2. When retrieving log messages via getChunk() compare the logCreationTime with the creationTime from
40 * getInfo().
41 * 3. If they differ then the id numbering has been reset.
42 *
43 * Log message retrieval:
44 * - only chunk-wise (a chunk is usually represented by a file in the backend)
45 * - one chunk at a time
46 * - when requested start id is in the middle of the chunk then entries before this id are not returned
47 * - when more messages are requested as available in a chunk after the start id then only the available
48 * messages are returned
49 * - requesting 2^31-1 (INT32_MAX) or -1 (2^32-1 (UINT32_MAX) casted to a signed 32bit integer) entries
50 * will ensure you get everything in the requested chunk after the start id
51 * - when going forward: if start id is lower than the first id then the start id is set to the first id
52 * - when going backward: if start id is greater than the last id then the start id is set to the last id
53 *
54 * Examples:
55 *
56 * Retrieving whole log forward from the beginning:
57 *
58 * 1. Get current log info by calling getInfo() and remember it.
59 * 2. Set the start id to idFirst from the log info.
60 * 3. Get chunk by calling getChunk(FORWARD) starting at the start id and requesting -1 entries
61 * (see Log message retrieval above for why using -1 here).
62 * 4. Compare chunk's logCreationTime with the creationTime from log info. If different then restart whole
63 * retrieval (log service was restarted or log was cleared).
64 * 5. Process retrieved log messages if any.
65 * 6. If allEntryCnt of the chunk is 0 then stop (the end of the log has been reached).
66 * 7. Calculate next start id by adding idFirst and allEntryCnt of the current chunk and go to step 3.
67 *
68 * Retrieving whole log backward from the end:
69 *
70 * 1. Get current log info by calling getInfo() and remember it.
71 * 2. If idNext in the logInfo is 0 then stop (log is empty).
72 * 3. Set the start id to idNext-1 (i.e. one less then idNext) from the log info.
73 * 4. Get chunk by calling getChunk(BACKWARD) starting at the start id and requesting -1 entries
74 * (see Log message retrieval above for why using -1 here).
75 * 5. Compare chunk's logCreationTime with the creationTime from log info. If different then restart whole
76 * retrieval (log service was restarted or log was cleared).
77 * 6. Process retrieved log messages if any.
78 * 7. If idFirst or allEntryCnt of the chunk is 0 then stop (the start of the log has been reached).
79 * 8. Calculate next start id by subtracting 1 from idFirst of the current chunk and go to step 4.
80 */
81module logging {
82
83 /** General log info */
84 structure LogInfo {
85 long creationTime; ///< Creation time of log (monotonic clock timestamp).
86 ///< Changed by clear() and service restart/reboot.
87 int idFirst; ///< Id of first entry of the log
88 int idNext; ///< Next unused entry id of the log
89 };
90
91 /** A log entry */
92 structure LogEntry {
93 int id; ///< Entry id
94 time timestamp; ///< Creation time of this entry (UNIX timestamp, UTC)
95 string eventClass; ///< Category (aka event class)
96 string message; ///< Log message
97 };
98
99 /** A log chunk */
100 structure LogChunk {
101 long logCreationTime; ///< Creation time of log at chunk generation (monotonic clock timestamp)
102 int idFirst; ///< Id of first entry in the chunk
103 int allEntryCnt; ///< Count of all entries in the chunk
104 vector<LogEntry> selEntries; ///< Selected entries of the chunk
105 };
106
107 /** Range direction when fetching log entries */
108 enumeration RangeDirection {
109 FORWARD, ///< Fetch log entries with id, id+1, id+2, ...
110 BACKWARD ///< Fetch log entries with id, id-1, id-2, ...
111 };
112
113}
114
115#endif /* __LOG_IDL__ */
logging
Device Logging.
Definition DebugLog.idl:14
logging::RangeDirection
RangeDirection
Range direction when fetching log entries.
Definition Log.idl:108
logging::FORWARD
@ FORWARD
Fetch log entries with id, id+1, id+2, ...
Definition Log.idl:109
logging::BACKWARD
@ BACKWARD
Fetch log entries with id, id-1, id-2, ...
Definition Log.idl:110
logging::LogChunk
A log chunk.
Definition Log.idl:100
logging::LogChunk::allEntryCnt
int allEntryCnt
Count of all entries in the chunk.
Definition Log.idl:103
logging::LogChunk::idFirst
int idFirst
Id of first entry in the chunk.
Definition Log.idl:102
logging::LogChunk::selEntries
vector< LogEntry > selEntries
Selected entries of the chunk.
Definition Log.idl:104
logging::LogChunk::logCreationTime
long logCreationTime
Creation time of log at chunk generation (monotonic clock timestamp)
Definition Log.idl:101
logging::LogEntry
A log entry.
Definition Log.idl:92
logging::LogEntry::eventClass
string eventClass
Category (aka event class)
Definition Log.idl:95
logging::LogEntry::message
string message
Log message.
Definition Log.idl:96
logging::LogEntry::id
int id
Entry id.
Definition Log.idl:93
logging::LogEntry::timestamp
time timestamp
Creation time of this entry (UNIX timestamp, UTC)
Definition Log.idl:94
logging::LogInfo
General log info.
Definition Log.idl:84
logging::LogInfo::idFirst
int idFirst
Id of first entry of the log.
Definition Log.idl:87
logging::LogInfo::creationTime
long creationTime
Creation time of log (monotonic clock timestamp).
Definition Log.idl:85
logging::LogInfo::idNext
int idNext
Next unused entry id of the log.
Definition Log.idl:88