Skip to content

Commit 5856e41

Browse files
dl1998dl1998
committed
Add usage description how to read logger configuration from a file
1 parent 69d7f83 commit 5856e41

File tree

1 file changed

+278
-1
lines changed

1 file changed

+278
-1
lines changed

‎README.md

Lines changed: 278 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -311,14 +311,291 @@ applicationLogger.Close()
311311
312312
// Open the logger with a new message queue size.
313313
if err := applicationLogger.Open(100); err != nil {
314-
panic(err)
314+
panic(err)
315315
}
316316
```
317317

318318
*Note: if you assign a new message queue size that is smaller than the number of messages sent to the queue, the logger
319319
will add messages to the queue until it is not full, then it will wait (blocking the process) until the message from the
320320
queue will be processed and free up the space in the message queue.*
321321

322+
### Reading Configuration from File
323+
324+
You could also read configuration from a file. Configuration file should be in one of the following formats: `*.json`,
325+
`*.yaml`, `*.xml`. Configuration file should contain the following fields:
326+
327+
```text
328+
- Loggers (array of loggers)
329+
- Name (string)
330+
- Time Format (string)
331+
- Message Queue Size (int)
332+
- Handlers (array of handlers)
333+
- Type (string)
334+
- From Level (string)
335+
- To Level (string)
336+
- File (string)
337+
- Formatter (string)
338+
- Type (string)
339+
- Pretty Print (bool)
340+
- Pair Separator (string)
341+
- Key Value Delimiter (string)
342+
- Template (template)
343+
- String Value (string)
344+
- Map Value (map of string to string)
345+
```
346+
347+
Example of the configuration files:
348+
349+
- JSON
350+
351+
```json
352+
{
353+
"loggers": [
354+
{
355+
"name": "example-logger",
356+
"time-format": "2006-01-02 15:04:05",
357+
"message-queue-size": 100,
358+
"handlers": [
359+
{
360+
"type": "stdout",
361+
"from-level": "all",
362+
"to-level": "severe",
363+
"formatter": {
364+
"type": "json",
365+
"pretty-print": false,
366+
"template": {
367+
"string": "%(datetime) - %(level) - %(message)",
368+
"map": {
369+
"timestamp": "%(datetime)",
370+
"level": "%(level)",
371+
"name": "%(name)"
372+
}
373+
}
374+
}
375+
},
376+
{
377+
"type": "stderr",
378+
"from-level": "error",
379+
"to-level": "null",
380+
"formatter": {
381+
"type": "key-value",
382+
"pair-separator": " ",
383+
"key-value-delimiter": ":",
384+
"template": {
385+
"string": "%(datetime) - %(level) - %(message)",
386+
"map": {
387+
"timestamp": "%(datetime)",
388+
"level": "%(level)",
389+
"name": "%(name)"
390+
}
391+
}
392+
}
393+
},
394+
{
395+
"type": "file",
396+
"from-level": "all",
397+
"to-level": "null",
398+
"file": "example.log",
399+
"formatter": {
400+
"type": "json",
401+
"pretty-print": true,
402+
"template": {
403+
"string": "%(datetime) - %(level) - %(message)",
404+
"map": {
405+
"timestamp": "%(datetime)",
406+
"level": "%(level)",
407+
"name": "%(name)"
408+
}
409+
}
410+
}
411+
}
412+
]
413+
}
414+
]
415+
}
416+
```
417+
418+
- YAML
419+
420+
```yaml
421+
loggers:
422+
- name: example-logger
423+
time-format: "2006-01-02 15:04:05"
424+
message-queue-size: 100
425+
handlers:
426+
- type: stdout
427+
from-level: all
428+
to-level: severe
429+
formatter:
430+
type: json
431+
pretty-print: false
432+
template:
433+
string: "%(datetime) - %(level) - %(message)"
434+
map:
435+
timestamp: "%(datetime)"
436+
level: "%(level)"
437+
name: "%(name)"
438+
- type: stderr
439+
from-level: error
440+
to-level: "null"
441+
formatter:
442+
type: key-value
443+
pair-separator: " "
444+
key-value-delimiter: ":"
445+
template:
446+
string: "%(datetime) - %(level) - %(message)"
447+
map:
448+
timestamp: "%(datetime)"
449+
level: "%(level)"
450+
name: "%(name)"
451+
- type: file
452+
from-level: all
453+
to-level: "null"
454+
file: example.log
455+
formatter:
456+
type: json
457+
pretty-print: true
458+
template:
459+
string: "%(datetime) - %(level) - %(message)"
460+
map:
461+
timestamp: "%(datetime)"
462+
level: "%(level)"
463+
name: "%(name)"
464+
```
465+
466+
- XML
467+
468+
```xml
469+
<root>
470+
<loggers>
471+
<logger>
472+
<name>example-logger</name>
473+
<time-format>2006-01-02 15:04:05</time-format>
474+
<message-queue-size>100</message-queue-size>
475+
<handlers>
476+
<handler>
477+
<type>stdout</type>
478+
<from-level>all</from-level>
479+
<to-level>severe</to-level>
480+
<formatter>
481+
<type>json</type>
482+
<pretty-print>false</pretty-print>
483+
<template>
484+
<string>%(datetime) - %(level) - %(message)</string>
485+
<map>
486+
<timestamp>%(datetime)</timestamp>
487+
<level>%(level)</level>
488+
<name>%(name)</name>
489+
</map>
490+
</template>
491+
</formatter>
492+
</handler>
493+
<handler>
494+
<type>stderr</type>
495+
<from-level>error</from-level>
496+
<to-level>null</to-level>
497+
<formatter>
498+
<type>key-value</type>
499+
<pair-separator> </pair-separator>
500+
<key-value-delimiter>:</key-value-delimiter>
501+
<template>
502+
<string>%(datetime) - %(level) - %(message)</string>
503+
<map>
504+
<timestamp>%(datetime)</timestamp>
505+
<level>%(level)</level>
506+
<name>%(name)</name>
507+
</map>
508+
</template>
509+
</formatter>
510+
</handler>
511+
<handler>
512+
<type>file</type>
513+
<from-level>all</from-level>
514+
<to-level>null</to-level>
515+
<file>example.log</file>
516+
<formatter>
517+
<type>json</type>
518+
<pretty-print>true</pretty-print>
519+
<template>
520+
<string>%(datetime) - %(level) - %(message)</string>
521+
<map>
522+
<timestamp>%(datetime)</timestamp>
523+
<level>%(level)</level>
524+
<name>%(name)</name>
525+
</map>
526+
</template>
527+
</formatter>
528+
</handler>
529+
</handlers>
530+
</logger>
531+
</loggers>
532+
</root>
533+
```
534+
535+
To create a logger from the configuration file, you need to:
536+
537+
1. Create a new Parser with the Configuration object. You shall use parser from the `logger` or `structuredlogger`.
538+
1. Create a new Configuration object manually and initialize parser with it.
539+
1. Parse configuration file to receive the Configuration. You could do this by calling the `ReadFromJSON`,
540+
`ReadFromYAML`, `ReadFromXML` methods respectively, it will return the Configuration object.
541+
542+
```go
543+
// Parse configuration from JSON file.
544+
newConfiguration, err := parser.ReadFromJSON("path/to/configuration/file.json")
545+
if err != nil {
546+
panic(err)
547+
}
548+
549+
// Parse configuration from YAML file.
550+
newConfiguration, err := parser.ReadFromYAML("path/to/configuration/file.yaml")
551+
if err != nil {
552+
panic(err)
553+
}
554+
555+
// Parse configuration from XML file.
556+
newConfiguration, err := parser.ReadFromXML("path/to/configuration/file.xml")
557+
if err != nil {
558+
panic(err)
559+
}
560+
```
561+
2. Create a new Parser with the Configuration object. You shall use parser from the `logger` or `structuredlogger`
562+
packages respectively, depending on which one you need.
563+
564+
```go
565+
newParser := parser.NewParser(newConfiguration)
566+
```
567+
2. Create Parser from the configuration file directly.
568+
569+
```go
570+
// Create a new Parser from JSON configuration file.
571+
newParser, err := parser.ParseJSON("path/to/configuration/file.json")
572+
if err != nil {
573+
panic(err)
574+
}
575+
576+
// Create a new Parser from YAML configuration file.
577+
newParser, err := parser.ParseYAML("path/to/configuration/file.yaml")
578+
if err != nil {
579+
panic(err)
580+
}
581+
582+
// Create a new Parser from XML configuration file.
583+
newParser, err := parser.ParseXML("path/to/configuration/file.xml")
584+
if err != nil {
585+
panic(err)
586+
}
587+
```
588+
589+
2. Get a logger from the Parser.
590+
591+
```go
592+
// Standard Logger
593+
newLogger := newParser.GetLogger("example-logger")
594+
595+
// Async Logger
596+
newLogger := newParser.GetAsyncLogger("example-logger")
597+
```
598+
322599
## Class Diagram
323600

324601
![Class Diagram](./docs/architecture/diagrams/png/class_diagram.png)

0 commit comments

Comments
 (0)