1 <img src="/static/logo.png" height="200px"/>
2
3 _Multilevel logging for advanced programs._
4
5 1. [lognestmonster](#lognestmonster)
6 2. [Library Class Structure](#library-class-structure)
7     1. [Semantics](#semantics)
8 3. [Serialization Format](#serialization-format)
9     1. [Events](#events)
10     2. [Statements](#statements)
11         1. [Verbosity Level Enumeration](#verbosity-level-enumeration)
12     3. [Example](#example)
13 4. [Temporary Data Saving](#temporary-data-saving)
14 5. [Copyright](#copyright)
15
16 # lognestmonster
17
18 ## Library Class Structure
19 This is subject to future change over security concerns regarding pointers and memory allocation.
20 ```
21 class lognestmonster
22
23     enum VerbosityLevels {INFO, DEBUG, VERBOSE, VERYVERBOSE, WARNING, ERROR}
24
25     struct QueueConfig
26         char * out_dir // directory to output log files
27
28     virtual void * alloc(size_t size)         // implementation defaults to cstd malloc()
29     virtual void free(void * block)           // implementation defaults to cstd free()
30     virtual void * serialize(LogObject * obj) // implementation defaults to manual serialization of standard LogObject to allocated block
31     virtual bool write(void * serialized, size_t size, std::ostream stream, bool append) // implementation defaults to writing entire serialized block to stream
32     virtual int delete(char * file_name)      // implementation defaults to cstd remove()
33
34     interface LogObject
35         Pushable * parent
36         char * temp_file
37         virtual bool save_temp()
38         virtual bool delete_temp()
39
40     interface Pushable
41     protected:
42         std::vector<LogObject *> pushed
43     public:
44         push(LogObject * obj)
45         push(int verbosity, char * tag, char * message) // implicitly creates a Statement and then pushes
46
47     class Queue : Pushable
48     public:
49         struct QueueConfig * _config
50         constructor (struct QueueConfig * config)
51         write()                                          // serializes, writes, and clears pushed LogObjects
52         write(LogObject * obj)                           // implicit push(), then write()
53         write(int verbosity, char * tag, char * message) // implicit Statement creation, push(), then write()
54
55     class Event : LogObject, Pushable
56     public:
57         constructor (LogObject * obj)                           // implicit push()
58         constructor (int verbosity, char * tag, char * message) // implicit Statement creation, then push()
59
60     class Statement : LogObject
61     public:
62         int verbosity
63         int timestamp
64         std::string * tag
65         std::string * message
66         constructor (int verbosity, char * tag, char * message)
67 ```
68 ### Semantics
69 A `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.
70
71 An `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.
72
73 A `Statement` is the data-containing log item with a timestamp, verbosity level, tag/invoker, and message.
74
75 In reference to data serialization, `parser` as used here is just a deserializer.
76
77 ## Serialization Format
78
79 By default the library serializes log tree information in a special format. This can be overriden by anybody that uses the library.
80
81 ### Metadata
82
83 All saved files should begin with an `unsigned char` version number and an `unsigned long long` millisecond timestamp.
84 ```
85 unsigned char version
86 unsigned long long timestamp
87 ```
88
89 ### Events
90 Open event with `0x2` and close with `0x3`. Statements or more events can be written inbetween these tags.
91 ```
92 0x2 // open event
93     // more events or statements
94 0x3 // close event
95 ```
96
97 ### Statements
98 Open statement with `0x0` and close `0x1`.
99
100 1. 1 byte for an open statement tag
101 2. 1 byte for a predefined verbosity level enum
102 3. 4 bytes for an unsigned integer timestamp
103 4. 1 byte for the length of the tag string
104 5. 0-255 bytes for the tag string
105 6. 2 bytes for the length of the message string
106 7. 0-65535 bytes for the message string
107 8. 1 byte for a close statement tag
108
109 ```
110 0x0
111     unsigned char verbosity
112     unsigned long long timestamp
113     unsigned char tag_size
114     unsigned char[] tag
115     unsigned short message_size
116     unsigned char[] message
117 0x1
118 ```
119 A 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.
120
121 #### Verbosity Level Enumeration
122 The 6 verbosity level enums and their byte values are:
123 ```
124 INFO        = 0
125 DEBUG       = 1
126 VERBOSE     = 2
127 VERYVERBOSE = 3
128 WARNING     = 4
129 ERROR       = 5
130 ```
131
132 ### Example
133 1 statement inside one 1 event:
134 ```
135 1565561768719 // timestamp    8*
136 0x2     // open event         1
137 0x0     // open statement     1
138 1565561768752 // timestamp    8*
139 0       // verbosity          1
140 4       // tag_size           1
141 "INIT"  // tag                4*
142 5       // message_size       2
143 "HELLO" // message            5*
144 0x1     // close statement    1
145 0x3     // close event        1
146         //                    33 total bytes for this log tree
147 ```
148 With 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:
149 ```
150 Log: sample.raw
151 Timestamp: 1565561768719
152 File size: 25 bytes
153 Content: 1 statement
154
155 v 1 ITEM
156     1565561768752 - INFO - INIT - HELLO
157 ```
158
159 ## Temporary Data Saving
160
161 By 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:
162
163 ```
164 Queue queue;
165 Event event;
166 Statement state1;
167 Statement state2;
168
169 // Existing files:
170 // statement1.raw
171 // statement2.raw
172
173 event.push(state1)
174
175 // Existing files:
176 // event.raw
177 // statement2.raw
178
179 queue.push(event)
180
181 // Existing files:
182 // event.raw
183 // statement2.raw
184
185 event.push(state2)
186
187 // Existing files:
188 // event.raw (all log items now exist inside the event, in the queue)
189
190 queue.write()
191
192 // Existing files:
193 // log12345.raw (consists of 2 statements inside 1 event)
194 ```
195
196 In reality, file names will likely contain timestamps, hashes, UUIDs, or some other form of identifiable metadata.
197
198 ## Copyright
199
200 lognestmonster Copyright (c) 2019 Joshua 'joshuas3' Stockin under the [GNU General Public License v3](LICENSE).
201
202 The following should be present in each file.
203 ```
204 lognestmonster Copyright (c) 2019 Joshua 'joshuas3' Stockin
205 <https://github.com/JoshuaS3/lognestmonster/>.
206
207
208 This file is part of lognestmonster.
209
210 lognestmonster is free software: you can redistribute it and/or modify
211 it under the terms of the GNU General Public License as published by
212 the Free Software Foundation, either version 3 of the License, or
213 (at your option) any later version.
214
215 lognestmonster is distributed in the hope that it will be useful,
216 but WITHOUT ANY WARRANTY; without even the implied warranty of
217 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
218 GNU General Public License for more details.
219
220 You should have received a copy of the GNU General Public License
221 along with lognestmonster. If not, see <https://www.gnu.org/licenses/>.
222 ```
223
1	<img src="/static/logo.png" height="200px"/>
2
3	_Multilevel logging for advanced programs._
4
5	1. [lognestmonster](#lognestmonster)
6	2. [Library Class Structure](#library-class-structure)
7	1. [Semantics](#semantics)
8	3. [Serialization Format](#serialization-format)
9	1. [Events](#events)
10	2. [Statements](#statements)
11	1. [Verbosity Level Enumeration](#verbosity-level-enumeration)
12	3. [Example](#example)
13	4. [Temporary Data Saving](#temporary-data-saving)
14	5. [Copyright](#copyright)
15
16	# lognestmonster
17
18	## Library Class Structure
19	This is subject to future change over security concerns regarding pointers and memory allocation.
20	```
21	class lognestmonster
22
23	enum VerbosityLevels {INFO, DEBUG, VERBOSE, VERYVERBOSE, WARNING, ERROR}
24
25	struct QueueConfig
26	char * out_dir // directory to output log files
27
28	virtual void * alloc(size_t size) // implementation defaults to cstd malloc()
29	virtual void free(void * block) // implementation defaults to cstd free()
30	virtual void * serialize(LogObject * obj) // implementation defaults to manual serialization of standard LogObject to allocated block
31	virtual bool write(void * serialized, size_t size, std::ostream stream, bool append) // implementation defaults to writing entire serialized block to stream
32	virtual int delete(char * file_name) // implementation defaults to cstd remove()
33
34	interface LogObject
35	Pushable * parent
36	char * temp_file
37	virtual bool save_temp()
38	virtual bool delete_temp()
39
40	interface Pushable
41	protected:
42	std::vector<LogObject *> pushed
43	public:
44	push(LogObject * obj)
45	push(int verbosity, char * tag, char * message) // implicitly creates a Statement and then pushes
46
47	class Queue : Pushable
48	public:
49	struct QueueConfig * _config
50	constructor (struct QueueConfig * config)
51	write() // serializes, writes, and clears pushed LogObjects
52	write(LogObject * obj) // implicit push(), then write()
53	write(int verbosity, char * tag, char * message) // implicit Statement creation, push(), then write()
54
55	class Event : LogObject, Pushable
56	public:
57	constructor (LogObject * obj) // implicit push()
58	constructor (int verbosity, char * tag, char * message) // implicit Statement creation, then push()
59
60	class Statement : LogObject
61	public:
62	int verbosity
63	int timestamp
64	std::string * tag
65	std::string * message
66	constructor (int verbosity, char * tag, char * message)
67	```
68	### Semantics
69	A `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.
70
71	An `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.
72
73	A `Statement` is the data-containing log item with a timestamp, verbosity level, tag/invoker, and message.
74
75	In reference to data serialization, `parser` as used here is just a deserializer.
76
77	## Serialization Format
78
79	By default the library serializes log tree information in a special format. This can be overriden by anybody that uses the library.
80
81	### Metadata
82
83	All saved files should begin with an `unsigned char` version number and an `unsigned long long` millisecond timestamp.
84	```
85	unsigned char version
86	unsigned long long timestamp
87	```
88
89	### Events
90	Open event with `0x2` and close with `0x3`. Statements or more events can be written inbetween these tags.
91	```
92	0x2 // open event
93	// more events or statements
94	0x3 // close event
95	```
96
97	### Statements
98	Open statement with `0x0` and close `0x1`.
99
100	1. 1 byte for an open statement tag
101	2. 1 byte for a predefined verbosity level enum
102	3. 4 bytes for an unsigned integer timestamp
103	4. 1 byte for the length of the tag string
104	5. 0-255 bytes for the tag string
105	6. 2 bytes for the length of the message string
106	7. 0-65535 bytes for the message string
107	8. 1 byte for a close statement tag
108
109	```
110	0x0
111	unsigned char verbosity
112	unsigned long long timestamp
113	unsigned char tag_size
114	unsigned char[] tag
115	unsigned short message_size
116	unsigned char[] message
117	0x1
118	```
119	A 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.
120
121	#### Verbosity Level Enumeration
122	The 6 verbosity level enums and their byte values are:
123	```
124	INFO = 0
125	DEBUG = 1
126	VERBOSE = 2
127	VERYVERBOSE = 3
128	WARNING = 4
129	ERROR = 5
130	```
131
132	### Example
133	1 statement inside one 1 event:
134	```
135	1565561768719 // timestamp 8*
136	0x2 // open event 1
137	0x0 // open statement 1
138	1565561768752 // timestamp 8*
139	0 // verbosity 1
140	4 // tag_size 1
141	"INIT" // tag 4*
142	5 // message_size 2
143	"HELLO" // message 5*
144	0x1 // close statement 1
145	0x3 // close event 1
146	// 33 total bytes for this log tree
147	```
148	With 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:
149	```
150	Log: sample.raw
151	Timestamp: 1565561768719
152	File size: 25 bytes
153	Content: 1 statement
154
155	v 1 ITEM
156	1565561768752 - INFO - INIT - HELLO
157	```
158
159	## Temporary Data Saving
160
161	By 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:
162
163	```
164	Queue queue;
165	Event event;
166	Statement state1;
167	Statement state2;
168
169	// Existing files:
170	// statement1.raw
171	// statement2.raw
172
173	event.push(state1)
174
175	// Existing files:
176	// event.raw
177	// statement2.raw
178
179	queue.push(event)
180
181	// Existing files:
182	// event.raw
183	// statement2.raw
184
185	event.push(state2)
186
187	// Existing files:
188	// event.raw (all log items now exist inside the event, in the queue)
189
190	queue.write()
191
192	// Existing files:
193	// log12345.raw (consists of 2 statements inside 1 event)
194	```
195
196	In reality, file names will likely contain timestamps, hashes, UUIDs, or some other form of identifiable metadata.
197
198	## Copyright
199
200	lognestmonster Copyright (c) 2019 Joshua 'joshuas3' Stockin under the [GNU General Public License v3](LICENSE).
201
202	The following should be present in each file.
203	```
204	lognestmonster Copyright (c) 2019 Joshua 'joshuas3' Stockin
205	<https://github.com/JoshuaS3/lognestmonster/>.
206
207
208	This file is part of lognestmonster.
209
210	lognestmonster is free software: you can redistribute it and/or modify
211	it under the terms of the GNU General Public License as published by
212	the Free Software Foundation, either version 3 of the License, or
213	(at your option) any later version.
214
215	lognestmonster is distributed in the hope that it will be useful,
216	but WITHOUT ANY WARRANTY; without even the implied warranty of
217	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
218	GNU General Public License for more details.
219
220	You should have received a copy of the GNU General Public License
221	along with lognestmonster. If not, see <https://www.gnu.org/licenses/>.
222	```
223