bunyarrs 0.3.0

Opinionated bunyan-like logger for small tools/apps
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106

## bunyarrs

`bunyarrs` is a very opinionated, low performance logging library,
modelled on [node bunyan](https://www.npmjs.com/package/bunyan).

```rust
let logger = Bunyarr::with_name("my-module");

let foo = init_foo();
let bar = init_bar();

logger.info(vars! { foo, bar }, "initialisation complete");
```

Will print, to stdout, on one line (whitespace added for the docs):

```json
{
  "time":"2022-09-11T15:19:33.166395524Z",
  "level":30,
  "msg":"initialisation complete",
  "name":"my-module",
  "foo": 5,
  "bar": {
    "baz": 5,
    "badger": "mushroom"
  },
  "hostname":"conqueeftador",
  "pid":1337,
  "v":0
}
```


### Configuration

The default log level is `info`, so `info` or higher will be generated.
This can be controlled with the environment variable `LOG_LEVEL`, for example,
`LOG_LEVEL=error` will hide any `debug`, `info`, or `warn` logs, but still
show `error` and `fatal` logs.


### ...why?

It's better than `eprintln!` and easier to get going with than `slog`.

This "bunyan" format is supported by a number of log ingest tools. Using it
saves you from attempting to handle objects, multi-line strings and the like
during your log search.

The library is designed to encourage good use of this format, specifically,
there is no support for format strings, or dynamic strings at all, on purpose.

Other tools, such as the [bunyan rust port](https://crates.io/crates/bunyan)
and [pino-pretty](https://www.npmjs.com/package/pino-pretty) exist to turn
these logs back into text, if you want to view them as text. Piping the above
output through `pino-pretty` results in:

```text
[16:19:33.166] INFO (my-module/1337): initialisation complete
    foo: 5
    bar: {
      "baz": 5,
      "badger": "mushroom"
    }
    v: 0
```


### I need support for...

Files, rotation? Nope. Write to stdout, it's well-supported by all orchestration tools.

Threads, performance? Nope. Use the [`slog`](https://crates.io/crates/slog) ecosystem,
and see their justification for the complexities.

Objects, naming? Use the `serde` ecosystem tools.

The existing rust-log ecosystem? Sorry, they use format strings, which is banned.

Custom formatters? Maybe you want to write your own `vars!` macro?


### How slow is it?

`Bunyarr::with_name()` tries not to do work, e.g. it pre-loads the hostname.

`logger.info()` is probably more efficient than you building an object and writing it
yourself, but probably less efficient than you typing out an object, and writing it
yourself, if you're careful. Bunyarr tries to be very careful, but is not willing to
sacrifice the interface for speed.


### Should I use this in a rust *library* I want people to use?

No.


### Contributing

`cargo fmt`, `cargo test`, github PRs or issues, please.


### License

MIT OR Apache-2.0