{"id":19417994,"url":"https://github.com/americanexpress/lumberjack","last_synced_at":"2025-04-24T13:34:15.486Z","repository":{"id":38175367,"uuid":"223456299","full_name":"americanexpress/lumberjack","owner":"americanexpress","description":"✨ Lumberjack is a minimal, configurable Console with utilities.","archived":false,"fork":false,"pushed_at":"2024-06-16T10:13:04.000Z","size":1071,"stargazers_count":16,"open_issues_count":2,"forks_count":5,"subscribers_count":18,"default_branch":"main","last_synced_at":"2025-04-19T09:04:45.752Z","etag":null,"topics":["logging","lumberjack","nodejs-console","one-app","stream"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/americanexpress.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-11-22T17:49:19.000Z","updated_at":"2025-04-09T10:15:04.000Z","dependencies_parsed_at":"2023-02-05T02:45:49.075Z","dependency_job_id":"3a583dc1-314f-418f-b023-12c9ad99b90d","html_url":"https://github.com/americanexpress/lumberjack","commit_stats":{"total_commits":36,"total_committers":11,"mean_commits":3.272727272727273,"dds":0.5277777777777778,"last_synced_commit":"6076ebfa3eab3bdd8b66870effb7b44adc3c2789"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/americanexpress%2Flumberjack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/americanexpress%2Flumberjack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/americanexpress%2Flumberjack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/americanexpress%2Flumberjack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/americanexpress","download_url":"https://codeload.github.com/americanexpress/lumberjack/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250636522,"owners_count":21463097,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["logging","lumberjack","nodejs-console","one-app","stream"],"created_at":"2024-11-10T13:12:20.257Z","updated_at":"2025-04-24T13:34:14.969Z","avatar_url":"https://github.com/americanexpress.png","language":"JavaScript","readme":"\u003ch1 align=\"center\"\u003e\n  \u003cimg src='https://github.com/americanexpress/lumberjack/raw/main/lumberjack.png' alt=\"Lumberjack - One Amex\" width='50%'/\u003e\n\u003c/h1\u003e\n\n[![npm](https://img.shields.io/npm/v/@americanexpress/lumberjack)](https://www.npmjs.com/package/@americanexpress/lumberjack)\n![Health Check](https://github.com/americanexpress/lumberjack/workflows/Health%20Check/badge.svg)\n\n\u003e `lumberjack` is a minimal and configurable [`Console`](https://nodejs.org/api/console.html) with utilities.\n\n## 👩‍💻 Hiring 👨‍💻\n\nWant to get paid for your contributions to `lumberjack`?\n\u003e Send your resume to oneamex.careers@aexp.com\n\n## 📖 Table of Contents\n\n* [Features](#-features)\n* [Usage](#-usage)\n* [API](#-api)\n* [Contributing](#-contributing)\n\n## ✨ Features\n\n* minimal and configurable  [`Console`](https://nodejs.org/api/console.html) with utilities.\n* Log formating using `formatter` depending on the log level.\n* Invoke callback functions before and after writing to stream.\n* Replace global `console` object using lumberjack\n\n## 🤹‍ Usage\n\n### Installation\n\n```bash\nnpm i @americanexpress/lumberjack\n```\n\n### Invocation\n\n#### How to use Lumberjack\n\nRead more about this in the [Lumberjack](#Lumberjack) API section.\n\n```javascript\nimport Lumberjack from '@americanexpress/lumberjack';\n\nfunction createLogger(simple = true) {\n  return new Lumberjack({\n    formatter: simple\n      // your formatter function can be as simple as:\n      ? (level, ...args) =\u003e `${level}: ${args}`\n      // or can be more complex, like stringifying as JSON:\n      : (level, ...messages) =\u003e JSON.stringify(\n        {\n          level,\n          messages,\n          time: new Date().toISOString(),\n        },\n        null,\n        2\n      ),\n  });\n}\n\nconst logger = createLogger();\n\nlogger.error(new Error('sample error'));\nlogger.warn(\"you're gonna have a bad time\");\nlogger.info('%d', 42);\nlogger.log({ its: 'complicated' });\nlogger.dir(document.location); // lists properties of an object\nlogger.table(['apples', 'oranges', 'bananas']); // expects array\n```\n\n#### How to use monkeypatches\n\nRead more about this in the [monkeypatches](#monkeypatches) API section.\n\n```javascript\nimport Lumberjack, { monkeypatches } from '@americanexpress/lumberjack';\n\nconst logger = new Lumberjack();\n\nmonkeypatches.replaceGlobalConsole(logger);\n\nconsole.log('This is now invoking logger.log');\n```\n\n## 🎛️ API\n\n### Lumberjack\n\nCreating a new console/Lumberjack is _similar_ to creating a [new nodejs Console](https://nodejs.org/api/console.html#console_new_console_stdout_stderr_ignoreerrors), but slightly different:\n\n* pass a single object with named options\n\n``` javascript\nconst logger = new Lumberjack({\n  // options are added here\n});\n```\n\n`Options` are:\n\n* `stdout`: stream to write to, defaults to `process.stdout`\n* `stderr`: defaults to the `stdout` option\n* `formatter`: an optional function that gets the log level and raw input arguments to return a string that is written to the stream (either `stdout` or `stderr` depending on log level)\n  * defaults to `util.format` (nodejs Console's formatter)\n  * can return `null` to skip writing to the stream\n* `beforeWrite`: callback function invoked before writing to the stream\n* `afterWrite`: callback function invoked after writing to the stream\n\nThe `Lumberjack` instance has four methods: `error`, `warn`, `info`, and `log`.\n\n### monkeypatches\n\n\u003eA monkey patch is a way for a program to extend or modify supporting system software locally (affecting only the running instance of the program).\n\u003e\n\u003ehttps://en.wikipedia.org/wiki/Monkey_patch\n\nUse monkeypatches with care and be aware of [pitfalls](https://en.wikipedia.org/wiki/Monkey_patch#Pitfalls).\n\n#### replaceGlobalConsole\n\nReplaces the `error`, `warn`, `info`, and `log` methods on the global `console` object with those of the `logger` argument provided.\n\n```javascript\nimport Lumberjack, { monkeypatches } from '@americanexpress/lumberjack';\n\nconst logger = new Lumberjack();\n\nmonkeypatches.replaceGlobalConsole(logger);\n\nconsole.log('This is now invoking logger.log');\n```\n\n#### attachSpy\n\nSpy on invocations of methods, ex: on native packages.\n\nArguments:\n\n* object the method exists on\n* method name to spy on\n* spy function, receives\n  * an array of the original arguments\n  * a function to invoke the original method and get the return value, this will be invoked automatically if not done by the spy function\n\nSee also [attachHttpRequestSpy](#monkeypatches.attachHttpRequestSpy) and [attachHttpsRequestSpy](#monkeypatches.attachHttpsRequestSpy)\n\n```javascript\nimport { monkeypatches } from '@americanexpress/lumberjack';\n\nmonkeypatches.attachSpy(http, 'request', (args, callOriginal) =\u003e {\n  console.log('starting http request', args);\n  const returnValue = callOriginal(); // spy, not an interceptor, so args handled automatically\n  console.log('http request started', returnValue);\n});\n```\n\n#### attachHttpRequestSpy\n\nSpy on the beginning and end of an `http.request`.\n\nArguments:\n\n* spy for the invocation of `http.request`\n* spy for the close of the socket used in the `http.request`\n\nBoth spies receive the return value of `http.request` and a normalized parsed URL requested (via `url.parse`).\n\n```javascript\nimport { monkeypatches } from '@americanexpress/lumberjack';\n\nmonkeypatches.attachHttpRequestSpy(\n  (clientRequest, parsedUrl) =\u003e console.info(`started request to ${parsedUrl.href}`),\n  (clientRequest, parsedUrl) =\u003e console.info(`request to ${parsedUrl.href} finished`)\n);\n```\n\n#### attachHttpsRequestSpy\n\nThe same thing as [attachHttpRequestSpy](#monkeypatches.attachHttpRequestSpy) but for the `https` native package.\n\nNote that for nodejs versions before 6.0.0 and earlier `https.request` called `http.request` so adding spys for both\n`http` and `https` will result in both spies being called.\n\n## 🏆 Contributing\n\nWe welcome Your interest in the American Express Open Source Community on Github.\nAny Contributor to any Open Source Project managed by the American Express Open\nSource Community must accept and sign an Agreement indicating agreement to the\nterms below. Except for the rights granted in this Agreement to American Express\nand to recipients of software distributed by American Express, You reserve all\nright, title, and interest, if any, in and to Your Contributions. Please [fill\nout the Agreement](https://cla-assistant.io/americanexpress/lumberjack).\n\nPlease feel free to open pull requests and see [CONTRIBUTING.md](./CONTRIBUTING.md) to learn how to get started contributing.\n\n## 🗝️ License\n\nAny contributions made under this project will be governed by the [Apache License\n2.0](https://github.com/americanexpress/lumberjack/blob/main/LICENSE.txt).\n\n## 🗣️ Code of Conduct\n\nThis project adheres to the [American Express Community Guidelines](./CODE_OF_CONDUCT.md).\nBy participating, you are expected to honor these guidelines.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famericanexpress%2Flumberjack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famericanexpress%2Flumberjack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famericanexpress%2Flumberjack/lists"}