Index

lognestmonster / 01b67c5

A general-purpose single-header C logging library and parser for event-based logs. (Incomplete)

Latest Commit

{#}TimeHashSubjectAuthor#(+)(-)GPG?
12115 Sep 2019 15:31d00611eUpdate readme with build test resultsJosh Stockin130N

Blob @ lognestmonster / README.md

text/plain8431 bytesdownload raw
1<img src="/static/logo.png" height="200px"/>
2
3_Multilevel logging for advanced programs._
4
51. [lognestmonster](#lognestmonster)
62. [Library Class Structure](#library-class-structure)
7 1. [Semantics](#semantics)
83. [Serialization Format](#serialization-format)
9 1. [Events](#events)
10 2. [Statements](#statements)
11 1. [Verbosity Level Enumeration](#verbosity-level-enumeration)
12 3. [Example](#example)
134. [Temporary Data Saving](#temporary-data-saving)
145. [Copyright](#copyright)
15
16# lognestmonster
17
18![linux dev](https://img.shields.io/travis/joshuas3/lognestmonster/dev?logo=travis)
19![windows dev](https://img.shields.io/appveyor/ci/joshuas3/lognestmonster/dev?logo=appveyor)
20
21## Library Class Structure
22This is subject to future change over security concerns regarding pointers and memory allocation.
23```
24class lognestmonster
25
26 enum VerbosityLevels {INFO, DEBUG, VERBOSE, VERYVERBOSE, WARNING, ERROR}
27
28 struct QueueConfig
29 char * out_dir // directory to output log files
30
31 virtual void * alloc(size_t size) // implementation defaults to cstd malloc()
32 virtual void free(void * block) // implementation defaults to cstd free()
33 virtual void * serialize(LogObject * obj) // implementation defaults to manual serialization of standard LogObject to allocated block
34 virtual bool write(void * serialized, size_t size, std::ostream stream, bool append) // implementation defaults to writing entire serialized block to stream
35 virtual int delete(char * file_name) // implementation defaults to cstd remove()
36
37 interface LogObject
38 Pushable * parent
39 char * temp_file
40 virtual bool save_temp()
41 virtual bool delete_temp()
42
43 interface Pushable
44 protected:
45 std::vector<LogObject *> pushed
46 public:
47 push(LogObject * obj)
48 push(int verbosity, char * tag, char * message) // implicitly creates a Statement and then pushes
49
50 class Queue : Pushable
51 public:
52 struct QueueConfig * _config
53 constructor (struct QueueConfig * config)
54 write() // serializes, writes, and clears pushed LogObjects
55 write(LogObject * obj) // implicit push(), then write()
56 write(int verbosity, char * tag, char * message) // implicit Statement creation, push(), then write()
57
58 class Event : LogObject, Pushable
59 public:
60 constructor (LogObject * obj) // implicit push()
61 constructor (int verbosity, char * tag, char * message) // implicit Statement creation, then push()
62
63 class Statement : LogObject
64 public:
65 int verbosity
66 int timestamp
67 std::string * tag
68 std::string * message
69 constructor (int verbosity, char * tag, char * message)
70```
71### Semantics
72A `Queue` handles data serialization and file writing to the main logtree file. Queue writing refers to sending serialized logtree data to the outstream. Queue pushing refers to adding an Event or Statement to the queue for future writing.
73
74An `Event` is a pushable list of statements or events, or the "nest". Event pushing refers to adding an Event or Statement to the parent's list.
75
76A `Statement` is the data-containing log item with a timestamp, verbosity level, tag/invoker, and message.
77
78In reference to data serialization, `parser` as used here is just a deserializer.
79
80## Serialization Format
81
82By default the library serializes log tree information in a special format. This can be overriden by anybody that uses the library.
83
84### Metadata
85
86All saved files should begin with an `unsigned char` version number and an `unsigned long long` millisecond timestamp.
87```
88unsigned char version
89unsigned long long timestamp
90```
91Version is representative of both the type of logtree and the format. Versions `0-99` should be indicative of Queues; `100-199` of Statements; `200-255` of Events.
92
93### Events
94Open event with `0x2` and close with `0x3`. Statements or more events can be written inbetween these tags.
95```
960x2 // open event
97 // more events or statements
980x3 // close event
99```
100
101### Statements
102Open statement with `0x0` and close `0x1`.
103
1041. 1 byte for an open statement tag
1052. 1 byte for a predefined verbosity level enum
1063. 4 bytes for an unsigned integer timestamp
1074. 1 byte for the length of the tag string
1085. 0-255 bytes for the tag string
1096. 2 bytes for the length of the message string
1107. 0-65535 bytes for the message string
1118. 1 byte for a close statement tag
112
113```
1140x0
115 unsigned long long timestamp
116 unsigned char verbosity
117 unsigned char tag_size
118 unsigned char[] tag
119 unsigned short message_size
120 unsigned char[] message
1210x1
122```
123A close statement tag is always needed in case the serializer method is overriden and provides extra data/metadata. If a close statement tag isn't written, a parser/deserializer won't be able to read a serialized logtree with extra data.
124
125#### Verbosity Level Enumeration
126The 6 verbosity level enums and their byte values are:
127```
128INFO = 0
129DEBUG = 1
130VERBOSE = 2
131VERYVERBOSE = 3
132WARNING = 4
133ERROR = 5
134```
135
136### Example
1371 statement inside one 1 event:
138```
1391565561768719 // timestamp 8*
1400x2 // open event 1
1410x0 // open statement 1
1421565561768752 // timestamp 8*
1430 // verbosity 1
1444 // tag_size 1
145"INIT" // tag 4*
1465 // message_size 2
147"HELLO" // message 5*
1480x1 // close statement 1
1490x3 // close event 1
150 // 33 total bytes for this log tree
151```
152With the sample log tree used here, the raw byte file totals 25 bytes. In use, a parser/deserializer could take this file and create output similar to the following:
153```
154lognestmonster - log_folder/
155Size: 33 bytes | Timestamp: 1565561768719
1561 Statement | 1 Event | 0 Unsaved Data Trees
157::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
158
159v 1 ITEM
160 1565561768752 - INFO - INIT - HELLO
161
162
163
164::::::::::: press q to exit | arrow keys to move, expand, collapse :::::::::::
165```
166
167## Temporary Data Saving
168
169By the nature of a push-write logging library, there's a chance that some created Statements and Events might not be pushed and written before the program's exit, whether it hangs, crashes, throws a runtime exception, is SIGKILLed, or anything else. Seeing as the point of logging is to find and diagnose errors with ease, it'd be frustrating to lose critical last-second information like this. The solution: save temporary serialized data for every creation or change to Statements or Events. Every logtree that ends in a Statement will have its own temporary data file; when a Statement is pushed to an Event, the Statement's file will be deleted and replaced into the greater Event file. See the following example for how data is separated into files:
170
171```
172Queue queue;
173Event event;
174Statement state1;
175Statement state2;
176
177// Existing files:
178// statement1.raw
179// statement2.raw
180
181event.push(state1)
182
183// Existing files:
184// event.raw
185// statement2.raw
186
187queue.push(event)
188
189// Existing files:
190// event.raw
191// statement2.raw
192
193event.push(state2)
194
195// Existing files:
196// event.raw (all log items now exist inside the event, in the queue)
197
198queue.write()
199
200// Existing files:
201// log12345.raw (consists of 2 statements inside 1 event)
202```
203
204In reality, file names will likely contain timestamps, hashes, UUIDs, or some other form of identifiable metadata.
205
206## Copyright
207
208lognestmonster Copyright (c) 2019 Joshua 'joshuas3' Stockin under the [GNU General Public License v3](LICENSE).
209
210The following should be present in each file.
211```
212lognestmonster Copyright (c) 2019 Joshua 'joshuas3' Stockin
213<https://github.com/JoshuaS3/lognestmonster/>.
214
215
216This file is part of lognestmonster.
217
218lognestmonster is free software: you can redistribute it and/or modify
219it under the terms of the GNU General Public License as published by
220the Free Software Foundation, either version 3 of the License, or
221(at your option) any later version.
222
223lognestmonster is distributed in the hope that it will be useful,
224but WITHOUT ANY WARRANTY; without even the implied warranty of
225MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
226GNU General Public License for more details.
227
228You should have received a copy of the GNU General Public License
229along with lognestmonster. If not, see <https://www.gnu.org/licenses/>.
230```
231