docs: Add examples · foxxmd.dev/logging@d778c2f

+196

1 changed file

Expand all

README.md

+196

README.md

··· 333 333 334 334 const parsedOptions: LogOptions = parseLogOptions(myConfig); 335 335 ``` 336 + 337 + # Examples 338 + 339 + Various use-cases for `@foxxmd/logging` and how to configure a logger for them. 340 + 341 + Remember, `loggerApp` and `loggerAppRolling` **accept the same arguments.** The examples below use `loggerApp` but `loggerAppRolling` can be used as a drop-in replacement in order to use a rolling log file. 342 + 343 + #### Log to Console and File 344 + 345 + ```ts 346 + import {loggerApp, loggerAppRolling} from '@foxxmd/logging'; 347 + 348 + // static log file at ./logs/app.log 349 + const staticLogger = loggerApp(); 350 + 351 + // rolling log file at ./logs/app.1.log 352 + const rollingLogger = loggerAppRolling(); 353 + ``` 354 + 355 + #### Log At Specific Level Or Higher for Console and File 356 + 357 + ```ts 358 + import {loggerApp} from '@foxxmd/logging'; 359 + 360 + // INFO is the default level 361 + // when 'console' is not specified it logs to 'info' or higher 362 + // when 'file' is not specified it logs to 'info' or higher 363 + const infoLogger = loggerApp(); 364 + 365 + // logs to console and log at 'debug' level and higher 366 + const debugLogger = loggerApp({level: 'debug'}); 367 + ``` 368 + 369 + #### Log At `debug` for Console and `warn` for File 370 + 371 + ```ts 372 + import {loggerApp} from '@foxxmd/logging'; 373 + 374 + const logger = loggerApp({ 375 + console: 'debug', 376 + file: 'warn' 377 + }); 378 + ``` 379 + 380 + #### Do not log to File 381 + 382 + ```ts 383 + import {loggerApp} from '@foxxmd/logging'; 384 + 385 + // also logs to console at 'info' level 386 + const logger = loggerApp({ 387 + file: false 388 + }); 389 + ``` 390 + 391 + #### Log to Specific File 392 + 393 + ```ts 394 + import {loggerApp} from '@foxxmd/logging'; 395 + 396 + // also logs to console at 'info' level 397 + const logger = loggerApp({ 398 + file: { 399 + path: './path/to/file.log' 400 + } 401 + }); 402 + ``` 403 + 404 + #### Log to Rolling File with Unix Timestamp 405 + 406 + ```ts 407 + import {loggerApp} from '@foxxmd/logging'; 408 + 409 + // also logs to console at 'info' level 410 + const logger = loggerApp({ 411 + file: { 412 + timestamp: 'unix' 413 + } 414 + }); 415 + ``` 416 + 417 + #### Log to Rolling File with no timestamp 418 + 419 + ```ts 420 + import {loggerApp} from '@foxxmd/logging'; 421 + 422 + // also logs to console at 'info' level 423 + const logger = loggerApp({ 424 + file: { 425 + // specify size but NOT 'frequency' to disable timestamps in filename 426 + size: '10M' 427 + } 428 + }); 429 + ``` 430 + 431 + #### Log to additional File for 'error' only 432 + 433 + ```ts 434 + import {loggerApp} from '@foxxmd/logging'; 435 + import { buildDestinationFile } from "@foxxmd/logging/factory"; 436 + 437 + const errorFileDestination = buildDestinationFile('error', {path: './myLogs/warn.log'}); 438 + 439 + // also logs to console and file at 'info' level 440 + const logger = loggerApp({}, { 441 + destinations: [errorFileDestination] 442 + }); 443 + ``` 444 + 445 + #### Log raw, newline-delimited json logs to additional File 446 + 447 + ```ts 448 + import {loggerApp} from '@foxxmd/logging'; 449 + import { buildDestinationFile } from "@foxxmd/logging/factory"; 450 + import fs from 'node:fs'; 451 + 452 + const rawFile = fs.createWriteStream('myRawFile.log'); 453 + 454 + // also logs to console and file at 'info' level 455 + const logger = loggerApp({}, { 456 + destinations: [ 457 + { 458 + level: 'debug', 459 + stream: rawFile // logs are NOT prettified, only raw data from pino 460 + } 461 + ] 462 + }); 463 + ``` 464 + 465 + #### Log prettified data to additional stream 466 + 467 + This could be used to trigger something when a log object with a specific property is found. Or to stream prettified log json to a client over websockets. 468 + 469 + To emit data as an object ([`LogDataPretty`](https://foxxmd.github.io/logging/types/index.LogDataPretty.html)) set `objectMode` and `object` to true. 470 + 471 + ```ts 472 + import {loggerApp} from '@foxxmd/logging'; 473 + import { buildDestinationJsonPrettyStream } from "@foxxmd/logging/factory"; 474 + import { PassThrough } from "node:stream"; 475 + 476 + const prettyObjectStream = new Passthrough({objectMode: true}); // objectMode MUST be true to get objects from the stream 477 + const prettyObjectDestination = buildDestinationJsonPrettyStream('debug', { 478 + destination: prettyObjectStream, 479 + object: true, // must be set to true to use with objectMode stream 480 + colorize: true 481 + }); 482 + 483 + const prettyStringStream = new Passthrough(); // will emit data as a json string 484 + const prettyStringDestination = buildDestinationJsonPrettyStream('debug', { 485 + destination: prettyStringStream, 486 + object: false, 487 + colorize: true 488 + }); 489 + 490 + // also logs to console and file at 'info' level 491 + const logger = loggerApp({}, { 492 + destinations: [ 493 + prettyObjectDestination, 494 + prettyStringDestination 495 + ] 496 + }); 497 + 498 + prettyObjectStream.on('data', (log) => { 499 + // do something with log object (LogDataPretty) 500 + }); 501 + 502 + prettyStringStream.on('data', (log) => { 503 + // do something with log string 504 + }); 505 + ``` 506 + 507 + #### Log to additional Pino Transports 508 + 509 + Log to a [Pino Transport](https://getpino.io/#/docs/transports) like [pino-elasticsearch](https://getpino.io/#/docs/transports?id=pino-elasticsearch): 510 + 511 + ```ts 512 + import {loggerApp} from '@foxxmd/logging'; 513 + import pinoElastic from 'pino-elasticsearch' 514 + 515 + const streamToElastic = pinoElastic({ 516 + index: 'an-index', 517 + node: 'http://localhost:9200', 518 + esVersion: 7, 519 + flushBytes: 1000 520 + }); 521 + 522 + // also logs to console and file at 'info' level 523 + const logger = loggerApp({}, { 524 + destinations: [ 525 + { 526 + level: 'debug', 527 + stream: streamToElastic 528 + } 529 + ] 530 + }); 531 + ```

Configure Feed

Configure Feed