cogger 0.7.0 → 0.7.1
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- checksums.yaml.gz.sig +0 -0
- data/README.adoc +134 -28
- data/cogger.gemspec +1 -1
- data/lib/cogger/formatters/json.rb +1 -1
- data/lib/cogger/formatters/kit/sanitizer.rb +1 -1
- data/lib/cogger/formatters/parsers/individual.rb +3 -2
- data/lib/cogger/formatters/processors/color.rb +1 -1
- data/lib/cogger/registry.rb +1 -1
- data.tar.gz.sig +0 -0
- metadata +2 -2
- metadata.gz.sig +0 -0
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 3226b0b30d4c6a4eba83e9aec637de1938ac852f8a7e1bbd3b4a07d501d67920
|
4
|
+
data.tar.gz: 4e00980079107adbb150c4b03f7d80f63ede92fe6fbbb628642d532dc9d82e9b
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: cf70a4540105ad59bc4237c9d654e2db5191eeb00b504391a465957b28d7d2fbb7c418969d30762fc8fe0f57ea97893be8980432ab7c2bd0b5643f9fea81ec02
|
7
|
+
data.tar.gz: d731085187625db4b92c45cc30eaff79c763d47c9e169d3e24a672627f9e2d144b40e4cd49074ce5afb47d05aa1e43c9cd29c0f2c97494d6f91d35e860a8e799
|
checksums.yaml.gz.sig
CHANGED
Binary file
|
data/README.adoc
CHANGED
@@ -10,18 +10,19 @@
|
|
10
10
|
|
11
11
|
= Cogger
|
12
12
|
|
13
|
-
Cogger is a portmanteau for custom logging (i.e. `[c]ustom + l[ogger] = cogger`) which enhances Ruby's native
|
13
|
+
Cogger is a portmanteau for custom logging (i.e. `[c]ustom + l[ogger] = cogger`) which enhances Ruby's native {logger_link} functionality with additional features such as dynamic emojis, colorized text, structured JSON, multiple outputs, and much more. 🚀
|
14
14
|
|
15
15
|
toc::[]
|
16
16
|
|
17
17
|
== Features
|
18
18
|
|
19
|
-
|
20
|
-
|
21
|
-
|
22
|
-
|
23
|
-
|
24
|
-
|
19
|
+
* Enhances Ruby's default {logger_link} with additional functionality and firepower.
|
20
|
+
* Provides dynamic/specific emoji output.
|
21
|
+
* Provides dynamic/specific colorized output via the {tone_link} gem.
|
22
|
+
* Provides customizable templates which leverage the native {format_link}.
|
23
|
+
* Provides customizable formatters for simple, color, JSON, and/or custom output.
|
24
|
+
* Provides multiple streams so you can log the same information to several outputs at once.
|
25
|
+
* Provides filtering of sensitive information.
|
25
26
|
|
26
27
|
== Screenshot
|
27
28
|
|
@@ -33,11 +34,34 @@ image::https://alchemists.io/images/projects/cogger/screenshots/console.png[Cons
|
|
33
34
|
|
34
35
|
== Setup
|
35
36
|
|
36
|
-
To
|
37
|
+
To install _with_ security, run:
|
37
38
|
|
38
39
|
[source,bash]
|
39
40
|
----
|
40
|
-
|
41
|
+
# 💡 Skip this line if you already have the public certificate installed.
|
42
|
+
gem cert --add <(curl --compressed --location https://alchemists.io/gems.pem)
|
43
|
+
gem install cogger --trust-policy HighSecurity
|
44
|
+
----
|
45
|
+
|
46
|
+
To install _without_ security, run:
|
47
|
+
|
48
|
+
[source,bash]
|
49
|
+
----
|
50
|
+
gem install cogger
|
51
|
+
----
|
52
|
+
|
53
|
+
You can also add the gem directly to your project:
|
54
|
+
|
55
|
+
[source,bash]
|
56
|
+
----
|
57
|
+
bundle add cogger
|
58
|
+
----
|
59
|
+
|
60
|
+
Once the gem is installed, you only need to require it:
|
61
|
+
|
62
|
+
[source,ruby]
|
63
|
+
----
|
64
|
+
require "cogger"
|
41
65
|
----
|
42
66
|
|
43
67
|
== Usage
|
@@ -86,7 +110,7 @@ logger.any { "demo" } # "demo"
|
|
86
110
|
|
87
111
|
When creating a new logger, you can configure behavior via the following attributes:
|
88
112
|
|
89
|
-
* `id`: The program/process ID which shows up in the logs as your `id`. Default: `$PROGRAM_NAME`. For example, if
|
113
|
+
* `id`: The program/process ID which shows up in the logs as your `id`. Default: `$PROGRAM_NAME`. For example, if run within a `demo.rb` script, the `id` would be `"demo"`,
|
90
114
|
* `io`: The input/output stream. This can be `STDOUT/$stdout`, a file/path, or `nil`. Default: `$stdout`.
|
91
115
|
* `level`: The severity level you want to log at. Can be `:debug`, `:info`, `:warn`, `:error`, `:fatal`, or `:unknown`. Default: `:info`.
|
92
116
|
* `formatter`: The formatter to use for formatting your log output. Default: `Cogger::Formatter::Color`. See the _Formatters_ section for more info.
|
@@ -125,7 +149,6 @@ export LOG_LEVEL=WARN
|
|
125
149
|
export LOG_LEVEL=ERROR
|
126
150
|
export LOG_LEVEL=FATAL
|
127
151
|
export LOG_LEVEL=UNKNOWN
|
128
|
-
export LOG_LEVEL=ANY
|
129
152
|
----
|
130
153
|
|
131
154
|
By default, `Cogger` will automatically use whatever is set via the `LOG_LEVEL` environment variable unless overwritten during initialization.
|
@@ -141,33 +164,57 @@ In addition to the above, the {format_link} is further enhanced with the use of
|
|
141
164
|
|
142
165
|
[source,ruby]
|
143
166
|
----
|
144
|
-
# Universal: Dynamic
|
167
|
+
# Universal: Dynamic (color is determined by severity)
|
145
168
|
"<dynamic>%<severity>s %<at>s %<id>s %<message>s</dynamic>"
|
146
169
|
|
147
|
-
# Universal: Specific
|
170
|
+
# Universal: Specific (uses the green color only)
|
148
171
|
"<green>%<severity>s %<at>s %<id>s %<message>s</green>"
|
149
172
|
|
150
|
-
# Individual: Dynamic
|
151
|
-
"%<severity:dynamic>s %<at:
|
173
|
+
# Individual: Dynamic (color is determined by severity)
|
174
|
+
"%<severity:dynamic>s %<at:dynamic>s %<id:dynamic>s %<message:dynamic>s"
|
152
175
|
|
153
|
-
# Individual: Specific
|
176
|
+
# Individual: Specific (uses a rainbow of colors)
|
154
177
|
"%<severity:purple>s %<at:yellow>s %<id:cyan>s %<message:green>s"
|
155
178
|
----
|
156
179
|
|
157
180
|
Here's a detailed breakdown of the above:
|
158
181
|
|
159
182
|
* *Universal*: Applies color universally to the _entire_ template and requires you to:
|
160
|
-
** Wrap your entire template in a and start (`<example>`) and end tag (`</example>`).
|
161
|
-
** Your tag names must either be `<dynamic></dynamic>`, any default color (
|
183
|
+
** Wrap your entire template in a and start (`<example>`) and end tag (`</example>`) which works much like an HTML tag in this context.
|
184
|
+
** Your tag names must either be `<dynamic></dynamic>`, any default color (example: `<green></green>`), or alias (i.e. `<your_alias></your_alias>`) as supported by the {tone_link} gem.
|
162
185
|
* *Individual*: Individual templates allow you to apply color to _specific_ attributes and require you to:
|
163
186
|
** Format your attributes as `attribute:directive`. The colon delimiter is required to separate your attribute for your color choice.
|
164
|
-
** The color value (what follows after the colon) can be `dynamic`, any default color (
|
187
|
+
** The color value (what follows after the colon) can be `dynamic`, any default color (example: `green`), or alias (i.e. `your_alias`) as supported by the {tone_link} gem.
|
165
188
|
|
166
189
|
In addition to the general categorization of universal and individual tags, each support the following directives:
|
167
190
|
|
168
191
|
* *Dynamic*: A dynamic directive means that color will be determined by severity level only. This means if info level is used, the associated color (alias) for info will be applied. Same goes for warn, error, etc.
|
169
192
|
* *Specific*: A specific directive means the color you use will be applied without any further processing regardless of the severity level. This gives you the ability to customize your colors further in situations where dynamic coloring isn't enough.
|
170
193
|
|
194
|
+
At this point, you might have gathered that there are specific keys you can use for the log event metadata in your template and everything else is up to you. This stems from the fact that {logger_link} entries always have the following metadata:
|
195
|
+
|
196
|
+
* `id`: This is the program/process ID you created your logger with (i.e. `Cogger.new id: :demo`).
|
197
|
+
* `severity`: This is the severity at which you messaged your logger (i.e. `logger.info`).
|
198
|
+
* `at`: This is the date/time as which your log event was created.
|
199
|
+
|
200
|
+
This also means if you pass in these same keys as a log event (example: `logger.info id: :bad, at: Time.now, severity: :bogus`) they will be ignored.
|
201
|
+
|
202
|
+
The last key (or keys) is variable and customizable to your needs which is the log event message. Here a couple of examples to illustrate:
|
203
|
+
|
204
|
+
[source,ruby]
|
205
|
+
----
|
206
|
+
# Available as "%<message>s" in your template.
|
207
|
+
logger.info "demo"
|
208
|
+
|
209
|
+
# Available as "%<message>s" in your template.
|
210
|
+
logger.info message: "demo"
|
211
|
+
|
212
|
+
# Available as "%<verb>s" and "%<path>s" in your template.
|
213
|
+
logger.info verb: "GET", path: "/"`
|
214
|
+
----
|
215
|
+
|
216
|
+
💡 In situations where a message hash is logged but the keys of that hash don't match the keys in the template, then an empty message will be logged. This applies to all formatters except the JSON formatter which will log any key/value that doesn't have a `nil` value.
|
217
|
+
|
171
218
|
=== Emojis
|
172
219
|
|
173
220
|
In addition to coloring to your log output, you can add emojis as well. Here are the defaults:
|
@@ -215,6 +262,31 @@ logger.info "demo"
|
|
215
262
|
|
216
263
|
Keep in mind that using a specific, non-dynamic, emoji will _always_ display no matter the current severity level.
|
217
264
|
|
265
|
+
=== Aliases
|
266
|
+
|
267
|
+
Aliases are specific to the {tone_link} gem which allows you _alias_ specific colors/styles via a new name. Here's how you can use them:
|
268
|
+
|
269
|
+
[source,ruby]
|
270
|
+
----
|
271
|
+
Cogger.add_alias :haze, :bold, :white, :on_purple
|
272
|
+
Cogger.aliases
|
273
|
+
----
|
274
|
+
|
275
|
+
The above would add a `:haze` alias which consists of bold white text on a purple background. Once added, you'd then be able to view a list of all default and custom aliases. You can also override an existing alias if you'd like something else.
|
276
|
+
|
277
|
+
Aliases are a powerful way to customize your colors and use short syntax in your templates. Building upon the alias, added above, you'd be able to use it in your templates as follows:
|
278
|
+
|
279
|
+
[source,ruby]
|
280
|
+
----
|
281
|
+
# Universal
|
282
|
+
"<haze>%<message></haze>"
|
283
|
+
|
284
|
+
# Individual
|
285
|
+
"%<message:haze>"
|
286
|
+
----
|
287
|
+
|
288
|
+
Check out the {tone_link} documentation for further examples.
|
289
|
+
|
218
290
|
=== Formatters
|
219
291
|
|
220
292
|
Multiple formatters are provided for you which can be further customized as needed. Here's what is provided by default:
|
@@ -251,7 +323,7 @@ Cogger.formatters
|
|
251
323
|
# }
|
252
324
|
----
|
253
325
|
|
254
|
-
You can add a formatter by providing a
|
326
|
+
You can add a formatter by providing a key, class, and _optional_ template. If a template isn't supplied, then the formatter's default template will be used instead (more on that shortly). Example:
|
255
327
|
|
256
328
|
[source,ruby]
|
257
329
|
----
|
@@ -263,7 +335,7 @@ Cogger.get_formatter :basic
|
|
263
335
|
# [Cogger::Formatters::Simple, "%<severity>s %<message>s"]
|
264
336
|
----
|
265
337
|
|
266
|
-
Symbols or strings can be used interchangeably when adding/getting formatters. As mentioned above, a template doesn't have to be supplied if you want to use the formatter's default template which can be inspected
|
338
|
+
Symbols or strings can be used interchangeably when adding/getting formatters. As mentioned above, a template doesn't have to be supplied if you want to use the formatter's default template which can be inspected as follows:
|
267
339
|
|
268
340
|
[source,ruby]
|
269
341
|
----
|
@@ -271,7 +343,7 @@ Cogger::Formatters::Simple::TEMPLATE
|
|
271
343
|
# "%<message>s"
|
272
344
|
----
|
273
345
|
|
274
|
-
💡 When you find yourself customizing any of the default formatters, you can reduce typing by adding your custom configuration to the registry and then referring to it via
|
346
|
+
💡 When you find yourself customizing any of the default formatters, you can reduce typing by adding your custom configuration to the registry and then referring to it via it's associated key when initializing a new logger.
|
275
347
|
|
276
348
|
==== Simple
|
277
349
|
|
@@ -308,13 +380,13 @@ Cogger.aliases
|
|
308
380
|
# info: :green,
|
309
381
|
# warn: :yellow,
|
310
382
|
# error: :red,
|
311
|
-
# fatal: %i[white
|
312
|
-
# unknown: %i[white
|
313
|
-
# any: %i[white
|
383
|
+
# fatal: %i[bold white on_red],
|
384
|
+
# unknown: %i[bold white],
|
385
|
+
# any: %i[bold white]
|
314
386
|
# }
|
315
387
|
----
|
316
388
|
|
317
|
-
This allows a color or combination of color styles (i.e. foreground + background) to be dynamically applied based on log
|
389
|
+
This allows a color -- or combination of color styles (i.e. foreground + background) -- to be dynamically applied based on log severity. You can add additional aliases via:
|
318
390
|
|
319
391
|
[source,ruby]
|
320
392
|
----
|
@@ -372,7 +444,7 @@ class MyFormatter
|
|
372
444
|
end
|
373
445
|
----
|
374
446
|
|
375
|
-
There is no restriction on what dependency you might want to initialize your custom formatter with but -- as a bare minimum -- you'll want to provide a default template and inject the sanitizer which sanitizes the raw log entry into a hash you can interact with in your implementation. The only other requirement is that you must implement `#call` which takes a log entry which is an array of positional arguments (i.e. `severity`, `at`, `id`, `message`) and answers back a formatted string. If you need more examples you can either read the link:https://rubyapi.org/o/logger/formatter#method-i-call[Logger::Formatter] or look at any of the formatters provided within this gem.
|
447
|
+
There is no restriction on what dependency you might want to initialize your custom formatter with but -- as a bare minimum -- you'll want to provide a default template and inject the sanitizer which sanitizes the raw log entry into a hash you can interact with in your implementation. The only other requirement is that you must implement `#call` which takes a log entry which is an array of positional arguments (i.e. `severity`, `at`, `id`, `message`) and answers back a formatted string. If you need more examples you can either read the link:https://rubyapi.org/o/logger/formatter#method-i-call[Logger::Formatter] documentation or look at any of the formatters provided within this gem.
|
376
448
|
|
377
449
|
=== Filters
|
378
450
|
|
@@ -415,6 +487,40 @@ logger.info login: "jayne", password: "secret"
|
|
415
487
|
# {"id":"console","severity":"INFO","at":"2023-04-09 17:33:00 -0600","login":"[FILTERED]","password":"[FILTERED]"}
|
416
488
|
----
|
417
489
|
|
490
|
+
=== Streams
|
491
|
+
|
492
|
+
You can add multiple log streams (outputs) by using:
|
493
|
+
|
494
|
+
[source,ruby]
|
495
|
+
----
|
496
|
+
logger = Cogger.new
|
497
|
+
.add_stream(io: "tmp/demo.log")
|
498
|
+
.add_stream(io: nil)
|
499
|
+
|
500
|
+
logger.info "Demo."
|
501
|
+
----
|
502
|
+
|
503
|
+
The above would log the `"Demo."` message to `$stdout` (i.e. the default stream), to the `tmp/demo.log` file, and to `/dev/null`. All of the attributes you would use to construct your default logger apply to any stream. This also means any custom template/formatter can be applied to your streams. Here's another example:
|
504
|
+
|
505
|
+
[source,ruby]
|
506
|
+
----
|
507
|
+
logger = Cogger.new.add_stream(io: "tmp/demo.log", formatter: :json)
|
508
|
+
logger.info "Demo."
|
509
|
+
----
|
510
|
+
|
511
|
+
In this situation, you'd get colorized output to `$stdout` and JSON output to the `tmp/demo.log` file.
|
512
|
+
|
513
|
+
=== Defaults
|
514
|
+
|
515
|
+
Should you ever need quick access to the defaults, you can use:
|
516
|
+
|
517
|
+
[source,ruby]
|
518
|
+
----
|
519
|
+
Cogger.defaults
|
520
|
+
----
|
521
|
+
|
522
|
+
This is primarily meant for display/inspection purposes, though.
|
523
|
+
|
418
524
|
=== Testing
|
419
525
|
|
420
526
|
When testing the Cogger client, you might find it convenient to use `StringIO`, or a file, for
|
@@ -453,7 +559,7 @@ end
|
|
453
559
|
----
|
454
560
|
|
455
561
|
Notice that when testing the instance of `Demo` and injecting a logger which logs to a string I/O
|
456
|
-
object, you can conveniently _reread_ the string -- provided by the {refinements_link} gem -- to see what was logged. This makes your specs easier to write while
|
562
|
+
object, you can conveniently _reread_ the string -- provided by the {refinements_link} gem -- to see what was logged. This makes your specs easier to write while avoiding additional noise in your test suite's output.
|
457
563
|
|
458
564
|
== Development
|
459
565
|
|
data/cogger.gemspec
CHANGED
@@ -18,7 +18,7 @@ module Cogger
|
|
18
18
|
|
19
19
|
def call(*entry)
|
20
20
|
positions = parser.call(template).last.keys
|
21
|
-
attributes = sanitizer.call(*entry)
|
21
|
+
attributes = sanitizer.call(*entry).tap(&:compact!)
|
22
22
|
"#{attributes.slice(*positions).merge!(attributes.except(*positions)).to_json}\n"
|
23
23
|
end
|
24
24
|
|
@@ -14,7 +14,7 @@ module Cogger
|
|
14
14
|
severity, at, id, message = entry
|
15
15
|
|
16
16
|
attributes = if message.is_a? Hash
|
17
|
-
{id:, severity:, at:, **message.except(:id, :severity, :at)}
|
17
|
+
{id:, severity:, at:, message: nil, **message.except(:id, :severity, :at)}
|
18
18
|
else
|
19
19
|
{id:, severity:, at:, message:}
|
20
20
|
end
|
@@ -30,9 +30,10 @@ module Cogger
|
|
30
30
|
end
|
31
31
|
|
32
32
|
def call template
|
33
|
-
return template unless template.match? pattern
|
34
|
-
|
35
33
|
attributes = {}
|
34
|
+
|
35
|
+
return [template, attributes] unless template.match? pattern
|
36
|
+
|
36
37
|
template = sanitize_and_extract template, attributes
|
37
38
|
[template, attributes]
|
38
39
|
end
|
data/lib/cogger/registry.rb
CHANGED
data.tar.gz.sig
CHANGED
Binary file
|
metadata
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: cogger
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 0.7.
|
4
|
+
version: 0.7.1
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- Brooke Kuhlmann
|
@@ -35,7 +35,7 @@ cert_chain:
|
|
35
35
|
3n5C8/6Zh9DYTkpcwPSuIfAga6wf4nXc9m6JAw8AuMLaiWN/r/2s4zJsUHYERJEu
|
36
36
|
gZGm4JqtuSg8pYjPeIJxS960owq+SfuC+jxqmRA54BisFCv/0VOJi7tiJVY=
|
37
37
|
-----END CERTIFICATE-----
|
38
|
-
date: 2023-04-
|
38
|
+
date: 2023-04-11 00:00:00.000000000 Z
|
39
39
|
dependencies:
|
40
40
|
- !ruby/object:Gem::Dependency
|
41
41
|
name: tone
|
metadata.gz.sig
CHANGED
Binary file
|