| 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 |  |
| 19 |  |
| 20 |
|
| 21 | ## Library Class Structure |
| 22 | This is subject to future change over security concerns regarding pointers and memory allocation. |
| 23 | ``` |
| 24 | class 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 |
| 72 | 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. |
| 73 |
|
| 74 | 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. |
| 75 |
|
| 76 | A `Statement` is the data-containing log item with a timestamp, verbosity level, tag/invoker, and message. |
| 77 |
|
| 78 | In reference to data serialization, `parser` as used here is just a deserializer. |
| 79 |
|
| 80 | ## Serialization Format |
| 81 |
|
| 82 | By 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 |
|
| 86 | All saved files should begin with an `unsigned char` version number and an `unsigned long long` millisecond timestamp. |
| 87 | ``` |
| 88 | unsigned char version |
| 89 | unsigned long long timestamp |
| 90 | ``` |
| 91 | Version 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 |
| 94 | Open event with `0x2` and close with `0x3`. Statements or more events can be written inbetween these tags. |
| 95 | ``` |
| 96 | 0x2 // open event |
| 97 | // more events or statements |
| 98 | 0x3 // close event |
| 99 | ``` |
| 100 |
|
| 101 | ### Statements |
| 102 | Open statement with `0x0` and close `0x1`. |
| 103 |
|
| 104 | 1. 1 byte for an open statement tag |
| 105 | 2. 1 byte for a predefined verbosity level enum |
| 106 | 3. 4 bytes for an unsigned integer timestamp |
| 107 | 4. 1 byte for the length of the tag string |
| 108 | 5. 0-255 bytes for the tag string |
| 109 | 6. 2 bytes for the length of the message string |
| 110 | 7. 0-65535 bytes for the message string |
| 111 | 8. 1 byte for a close statement tag |
| 112 |
|
| 113 | ``` |
| 114 | 0x0 |
| 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 |
| 121 | 0x1 |
| 122 | ``` |
| 123 | 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. |
| 124 |
|
| 125 | #### Verbosity Level Enumeration |
| 126 | The 6 verbosity level enums and their byte values are: |
| 127 | ``` |
| 128 | INFO = 0 |
| 129 | DEBUG = 1 |
| 130 | VERBOSE = 2 |
| 131 | VERYVERBOSE = 3 |
| 132 | WARNING = 4 |
| 133 | ERROR = 5 |
| 134 | ``` |
| 135 |
|
| 136 | ### Example |
| 137 | 1 statement inside one 1 event: |
| 138 | ``` |
| 139 | 1565561768719 // timestamp 8* |
| 140 | 0x2 // open event 1 |
| 141 | 0x0 // open statement 1 |
| 142 | 1565561768752 // timestamp 8* |
| 143 | 0 // verbosity 1 |
| 144 | 4 // tag_size 1 |
| 145 | "INIT" // tag 4* |
| 146 | 5 // message_size 2 |
| 147 | "HELLO" // message 5* |
| 148 | 0x1 // close statement 1 |
| 149 | 0x3 // close event 1 |
| 150 | // 33 total bytes for this log tree |
| 151 | ``` |
| 152 | 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: |
| 153 | ``` |
| 154 | lognestmonster - log_folder/ |
| 155 | Size: 33 bytes | Timestamp: 1565561768719 |
| 156 | 1 Statement | 1 Event | 0 Unsaved Data Trees |
| 157 | :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: |
| 158 | |
| 159 | v 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 |
|
| 169 | 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: |
| 170 |
|
| 171 | ``` |
| 172 | Queue queue; |
| 173 | Event event; |
| 174 | Statement state1; |
| 175 | Statement state2; |
| 176 | |
| 177 | // Existing files: |
| 178 | // statement1.raw |
| 179 | // statement2.raw |
| 180 | |
| 181 | event.push(state1) |
| 182 | |
| 183 | // Existing files: |
| 184 | // event.raw |
| 185 | // statement2.raw |
| 186 | |
| 187 | queue.push(event) |
| 188 | |
| 189 | // Existing files: |
| 190 | // event.raw |
| 191 | // statement2.raw |
| 192 | |
| 193 | event.push(state2) |
| 194 | |
| 195 | // Existing files: |
| 196 | // event.raw (all log items now exist inside the event, in the queue) |
| 197 | |
| 198 | queue.write() |
| 199 | |
| 200 | // Existing files: |
| 201 | // log12345.raw (consists of 2 statements inside 1 event) |
| 202 | ``` |
| 203 |
|
| 204 | In reality, file names will likely contain timestamps, hashes, UUIDs, or some other form of identifiable metadata. |
| 205 |
|
| 206 | ## Copyright |
| 207 |
|
| 208 | lognestmonster Copyright (c) 2019 Joshua 'joshuas3' Stockin under the [GNU General Public License v3](LICENSE). |
| 209 |
|
| 210 | The following should be present in each file. |
| 211 | ``` |
| 212 | lognestmonster Copyright (c) 2019 Joshua 'joshuas3' Stockin |
| 213 | <https://github.com/JoshuaS3/lognestmonster/>. |
| 214 | |
| 215 | |
| 216 | This file is part of lognestmonster. |
| 217 | |
| 218 | lognestmonster is free software: you can redistribute it and/or modify |
| 219 | it under the terms of the GNU General Public License as published by |
| 220 | the Free Software Foundation, either version 3 of the License, or |
| 221 | (at your option) any later version. |
| 222 | |
| 223 | lognestmonster is distributed in the hope that it will be useful, |
| 224 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 225 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| 226 | GNU General Public License for more details. |
| 227 | |
| 228 | You should have received a copy of the GNU General Public License |
| 229 | along with lognestmonster. If not, see <https://www.gnu.org/licenses/>. |
| 230 | ``` |
| 231 |
|
Index