[READ-ONLY] Mirror of https://github.com/FoxxMD/logging. A typed, opinionated, batteries-included, Pino-based logging solution for backend TS/JS projects
foxxmd.github.io/logging
child-logger
logging
logging-library
nodejs
pinojs
typescript-library
docs: Add typedoc links to readme
+19
-19
+19
-19
README.md
+19
-19
README.md
···
66
66
67
67
These are the loggers that should be used for the majority of your application. They accept an optional configuration object for configuring log destinations.
68
68
69
-
* `loggerApp` - Logs to console and a fixed file destination
70
-
* `loggerAppRolling` - Logs to console and a rolling file destination
69
+
* [`loggerApp`](https://foxxmd.github.io/logging/functions/index.loggerApp.html) - Logs to console and a fixed file destination
70
+
* [`loggerAppRolling`](https://foxxmd.github.io/logging/functions/index.loggerAppRolling.html) - Logs to console and a rolling file destination
71
71
72
72
### Helper Loggers
73
73
74
74
These loggers are pre-defined for specific use cases:
75
75
76
-
* `loggerDebug` - Logs ONLY to console at minimum `debug` level. Can be used during application startup before a logger app configuration has been parsed.
77
-
* `loggerTest` - A noop logger (will not log anywhere) for use in tests/mockups.
76
+
* [`loggerDebug`](https://foxxmd.github.io/logging/variables/index.loggerDebug.html) - Logs ONLY to console at minimum `debug` level. Can be used during application startup before a logger app configuration has been parsed.
77
+
* [`loggerTest`](https://foxxmd.github.io/logging/variables/index.loggerTest.html) - A noop logger (will not log anywhere) for use in tests/mockups.
78
78
79
79
## Configuring
80
80
81
-
The [App Loggers](#app-loggers) take an optional config object.
81
+
The [App Loggers](#app-loggers) take an optional config object [`LogOptions`](https://foxxmd.github.io/logging/interfaces/index.LogOptions.html):
82
82
83
83
```ts
84
84
interface LogOptions {
···
100
100
file?: LogLevel | false | FileLogOptions
101
101
}
102
102
```
103
-
Available `LogLevel` levels, from lowest to highest:
103
+
Available [`LogLevel`](https://foxxmd.github.io/logging/types/index.LogLevel.html) levels, from lowest to highest:
104
104
105
105
* `debug`
106
106
* `verbose`
···
124
124
125
125
### File Options
126
126
127
-
`file` in `LogOptions` may be an object that specifies more behavior log files.
127
+
[`file` in `LogOptions`](https://foxxmd.github.io/logging/interfaces/index.FileLogOptions.html) may be an object that specifies more behavior log files.
128
128
129
129
<details>
130
130
···
154
154
* This determines the format of the datetime inserted into the log file name:
155
155
*
156
156
* * `unix` - unix epoch timestamp in milliseconds
157
-
* * `iso` - Full ISO8601 datetime IE '2024-03-07T20:11:34Z'
157
+
* * `iso` - Full ISO8601 datetime IE '2024-03-07T20:11:34-00:00'
158
158
* * `auto`
159
159
* * When frequency is `daily` only inserts date IE YYYY-MM-DD
160
160
* * Otherwise inserts full ISO8601 datetime
···
208
208
209
209
```ts
210
210
import { loggerApp } from '@foxxmd/logging';
211
-
import {
211
+
import {
212
212
PRETTY_ISO8601, // replaces standard timestamp with ISO8601 format
213
-
buildDestinationFile
213
+
buildDestinationFile
214
214
} from "@foxxmd/logging/factory";
215
215
216
216
const warnFileDestination = buildDestinationFile('warn', {path: './myLogs/warn.log'});
···
231
231
232
232
### Child Loggers
233
233
234
-
[Pino Child loggers](https://getpino.io/#/docs/child-loggers) can be created using the `childLogger` function with the added ability to inherit **Labels** from their parent loggers.
234
+
[Pino Child loggers](https://getpino.io/#/docs/child-loggers) can be created using the [`childLogger`](https://foxxmd.github.io/logging/functions/index.childLogger.html) function with the added ability to inherit **Labels** from their parent loggers.
235
235
236
236
**Labels** are inserted between the log level and message contents of a log. The child logger inherits **all** labels from **all** its parent loggers.
237
237
···
301
301
302
302
# Building A Logger
303
303
304
-
All the functionality required to build your own logger is exported by `@foxxmd/logging/factory`. You can customize almost every facet of logging.
304
+
All the functionality required to build your own logger is exported by [`@foxxmd/logging/factory`](https://foxxmd.github.io/logging/modules/factory.html). You can customize almost every facet of logging.
305
305
306
-
A logger is composed of a minimum default level and array of objects that implement `StreamEntry`, the same interface used by [`pino.multistream`](https://getpino.io/#/docs/api?id=pino-multistream). The only constraint is that your streams must accept the same levels as `@foxxmd/logging` using the `LogLevelStreamEntry` interface that extends `StreamEntry`.
306
+
A logger is composed of a minimum default level and array of objects that implement [`StreamEntry`](https://foxxmd.github.io/logging/interfaces/index._internal_.StreamEntry-1.html), the same interface used by [`pino.multistream`](https://getpino.io/#/docs/api?id=pino-multistream). The only constraint is that your streams must accept the same levels as `@foxxmd/logging` using the [`LogLevelStreamEntry`](https://foxxmd.github.io/logging/types/index.LogLevelStreamEntry.html) interface that extends `StreamEntry`.
307
307
308
308
```ts
309
309
import {LogLevelStreamEntry} from '@foxxmd/logging';
···
332
332
All `buildDestination` functions take args:
333
333
334
334
* `level` (first arg) - minimum level to log at
335
-
* `options` (second arg) - an object extending [`pino-pretty` options](https://github.com/pinojs/pino-pretty?tab=readme-ov-file#options)
335
+
* `options` (second arg) - an object extending [`pino-pretty` options](https://github.com/pinojs/pino-pretty?tab=readme-ov-file#options), [`PrettyOptions`](https://foxxmd.github.io/logging/interfaces/factory._internal_.PrettyOptions_.html)
336
336
337
-
`options` inherits a default `pino-pretty` configuration that comprises `@foxxmd/logging`'s opinionated logging format. The common default config can be generated using `prettyOptsFactory` which accepts an optional [`pino-pretty` options](https://github.com/pinojs/pino-pretty?tab=readme-ov-file#options) object to override defaults:
337
+
`options` inherits a default `pino-pretty` configuration that comprises `@foxxmd/logging`'s opinionated logging format. The common default config can be generated using [`prettyOptsFactory`](https://foxxmd.github.io/logging/functions/factory.prettyOptsFactory.html) which accepts an optional `PrettyOptions` object to override defaults:
338
338
339
339
```ts
340
340
import { prettyOptsFactory } from "@foxxmd/logging/factory";
···
356
356
357
357
Specific buildDestinations also require passing a stream or path:
358
358
359
-
`buildDestinationStream` must pass a `NodeJS.WriteableStream` or SonicBoom `DestinationStream` to options as `destination`
359
+
[`buildDestinationStream`](https://foxxmd.github.io/logging/functions/factory.buildDestinationStream.html) must pass a `NodeJS.WriteableStream` or SonicBoom `DestinationStream` to options as [`destination`](https://foxxmd.github.io/logging/types/factory.StreamDestination.html)
360
360
361
361
```ts
362
362
import {buildDestinationStream} from "@foxxmd/logging/factory";
···
365
365
const dest = buildDestinationStream('debug', {destination: myStream});
366
366
```
367
367
368
-
`buildDestinationStdout` and `buildDestinationStderr` do not require a destination as they are fixed to STDOUT/STDERR
368
+
[`buildDestinationStdout`](https://foxxmd.github.io/logging/functions/factory.buildDestinationStdout.html) and [`buildDestinationStderr`](https://foxxmd.github.io/logging/functions/factory.buildDestinationStderr.html) do not require a destination as they are fixed to STDOUT/STDERR
369
369
370
-
`buildDestinationFile` and `buildDestinationRollingFile` must pass a `path` to options
370
+
[`buildDestinationFile`](https://foxxmd.github.io/logging/functions/factory.buildDestinationFile.html) and [`buildDestinationRollingFile`](https://foxxmd.github.io/logging/functions/factory.buildDestinationRollingFile.html) must pass a [`path`](https://foxxmd.github.io/logging/types/factory.FileDestination.html) to options
371
371
372
372
```ts
373
373
import {buildDestinationFile} from "@foxxmd/logging/factory";
···
414
414
415
415
### Parsing LogOptions
416
416
417
-
If you wish to use [`LogOptions`](#configuring) to get default log levels for your destinations use `parseLogOptions`:
417
+
If you wish to use [`LogOptions`](#configuring) to get default log levels for your destinations use [`parseLogOptions`](https://foxxmd.github.io/logging/functions/index.parseLogOptions.html):
418
418
419
419
```ts
420
420
import {parseLogOptions, LogOptions} from '@foxxmd/logging';