{"id":21070377,"url":"https://github.com/stencila/logga","last_synced_at":"2025-05-16T05:30:46.100Z","repository":{"id":34917616,"uuid":"189489362","full_name":"stencila/logga","owner":"stencila","description":"🌲 Emit log events from anywhere. Consistently.","archived":false,"fork":false,"pushed_at":"2025-05-07T03:59:27.000Z","size":1998,"stargazers_count":5,"open_issues_count":22,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-05-07T04:33:48.489Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/stencila.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-05-30T22:14:46.000Z","updated_at":"2023-09-27T01:21:47.000Z","dependencies_parsed_at":"2023-10-11T06:36:02.945Z","dependency_job_id":"cda3150d-33e6-4a0c-bcf2-e9f66b6fcf12","html_url":"https://github.com/stencila/logga","commit_stats":{"total_commits":193,"total_committers":10,"mean_commits":19.3,"dds":0.5803108808290156,"last_synced_commit":"9fe75f37e725b6b2fdcd3b52929cbaaab07ff374"},"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stencila%2Flogga","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stencila%2Flogga/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stencila%2Flogga/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stencila%2Flogga/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stencila","download_url":"https://codeload.github.com/stencila/logga/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254473763,"owners_count":22077165,"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":[],"created_at":"2024-11-19T18:46:43.549Z","updated_at":"2025-05-16T05:30:44.304Z","avatar_url":"https://github.com/stencila.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Logga\n\n🌲 Emit log events from anywhere. Consistently.\n\n[![Build status](https://travis-ci.org/stencila/logga.svg?branch=master)](https://travis-ci.org/stencila/logga)\n[![Code coverage](https://codecov.io/gh/stencila/logga/branch/master/graph/badge.svg)](https://codecov.io/gh/stencila/logga)\n[![NPM](https://img.shields.io/npm/v/@stencila/logga.svg?style=flat)](https://www.npmjs.com/package/@stencila/logga)\n[![Docs](https://img.shields.io/badge/docs-latest-blue.svg)](https://stencila.github.io/logga/)\n\n## Why?\n\nWe wanted to have a unified, consistent mechanism for emitting log event data across libraries. We wanted to decouple log event emission from log event consumption. We didn't want to have to pass `log` objects around everywhere. We wanted type safety. We wanted something lightweight.\n\n## Approach\n\nThe approach used in `logga` is to use `process` (in Node) or `window` (in browsers) as a bus for log events. It's a simple approach, described in [this gist](https://gist.github.com/constantology/5f04d5782c1cc019722f), that combines emitting events using `process.emit()` or `window.dispatchEvent()` and registering log handlers as event listeners.\n\n## Install\n\n```bash\nnpm install --save @stencila/logga\n```\n\n## Usage\n\n### Emitting log events\n\nCreate a new logger by calling `getLogger` with a unique tag to identify your app and/or module. Then emit log events using the `debug`, `info`, `warn` and `error` functions. You can pass them a message string or a `LogInfo` object.\n\n```js\nconst { getLogger } = require('@stencila/logga')\n\nconst log = getLogger('example')\n\nlog.debug('This is line five.')\nlog.info('Everything is just fine.')\nlog.warn('Oh, oh, not no much.')\nlog.error('Aaargh, an error!')\n\ntry {\n  throw new Error('I am an error object.')\n} catch (error) {\n  const { message, stack } = error\n  log.error({\n    message: 'Woaaah something bad happened! ' + message,\n    stack,\n  })\n}\n```\n\nSee [this post](https://reflectoring.io/logging-levels/) for advice on when to use the alternative log levels. In summary,\n\n- The `ERROR` level should only be used when the application really is in trouble. Users are being affected without having a way to work around the issue.\n\n- The `WARN` level should be used when something bad happened, but the application still has the chance to heal itself or the issue can wait a day or two to be fixed.\n\n- The `INFO` level should be used to document state changes in the application or some entity within the application.\n\n- The `DEBUG` level should be used to log any information that helps us identify what went wrong.\n\n### Handling log events\n\nThe default log handler prints log data to `console.error`. If `stderr` is TTY log data is formatted for human consumption with emoji, colours and stack trace (for errors):\n\n![](screenshot.png)\n\nIf `stderr` is not TTY log data is formatted for machine consumption (e.g. for log files) as [ndjson](http://ndjson.org/), with a time stamp, if `stderr` (for machine consumption e.g. log files):\n\n```json\n{\"time\":\"2019-07-02T21:19:24.872Z\",\"tag\":\"example\",\"level\":3,\"message\":\"This is line five.\",\"stack\":\"Error\\n    at Object.\u003canonymous\u003e (/home/nokome/stencila/source/logga/example.js:21:5)\\n    at Module._compile (internal/modules/cjs/loader.js:689:30)\\n    at Object.Module._extensions..js (internal/modules/cjs/loader.js:700:10)\\n    at Module.load (internal/modules/cjs/loader.js:599:32)\\n    at tryModuleLoad (internal/modules/cjs/loader.js:538:12)\\n    at Function.Module._load (internal/modules/cjs/loader.js:530:3)\\n    at Function.Module.runMain (internal/modules/cjs/loader.js:742:12)\\n    at startup (internal/bootstrap/node.js:266:19)\"}\n{\"time\":\"2019-07-02T21:19:24.875Z\",\"tag\":\"example\",\"level\":2,\"message\":\"Everything is just fine.\",\"stack\":\"Error\\n    at Object.\u003canonymous\u003e (/home/nokome/stencila/source/logga/example.js:22:5)\\n    at Module._compile (internal/modules/cjs/loader.js:689:30)\\n    at Object.Module._extensions..js (internal/modules/cjs/loader.js:700:10)\\n    at Module.load (internal/modules/cjs/loader.js:599:32)\\n    at tryModuleLoad (internal/modules/cjs/loader.js:538:12)\\n    at Function.Module._load (internal/modules/cjs/loader.js:530:3)\\n    at Function.Module.runMain (internal/modules/cjs/loader.js:742:12)\\n    at startup (internal/bootstrap/node.js:266:19)\"}\n{\"time\":\"2019-07-02T21:19:24.875Z\",\"tag\":\"example\",\"level\":1,\"message\":\"Oh, oh, not no much.\",\"stack\":\"Error\\n    at Object.\u003canonymous\u003e (/home/nokome/stencila/source/logga/example.js:23:5)\\n    at Module._compile (internal/modules/cjs/loader.js:689:30)\\n    at Object.Module._extensions..js (internal/modules/cjs/loader.js:700:10)\\n    at Module.load (internal/modules/cjs/loader.js:599:32)\\n    at tryModuleLoad (internal/modules/cjs/loader.js:538:12)\\n    at Function.Module._load (internal/modules/cjs/loader.js:530:3)\\n    at Function.Module.runMain (internal/modules/cjs/loader.js:742:12)\\n    at startup (internal/bootstrap/node.js:266:19)\"}\n{\"time\":\"2019-07-02T21:19:24.875Z\",\"tag\":\"example\",\"level\":0,\"message\":\"Aaargh, an error!\",\"stack\":\"Error\\n    at Object.\u003canonymous\u003e (/home/nokome/stencila/source/logga/example.js:24:5)\\n    at Module._compile (internal/modules/cjs/loader.js:689:30)\\n    at Object.Module._extensions..js (internal/modules/cjs/loader.js:700:10)\\n    at Module.load (internal/modules/cjs/loader.js:599:32)\\n    at tryModuleLoad (internal/modules/cjs/loader.js:538:12)\\n    at Function.Module._load (internal/modules/cjs/loader.js:530:3)\\n    at Function.Module.runMain (internal/modules/cjs/loader.js:742:12)\\n    at startup (internal/bootstrap/node.js:266:19)\"}\n{\"time\":\"2019-07-02T21:19:24.875Z\",\"tag\":\"example\",\"level\":0,\"message\":\"Woaaah something bad happened! I am an error object.\",\"stack\":\"Error: I am an error object.\\n    at Object.\u003canonymous\u003e (/home/nokome/stencila/source/logga/example.js:27:9)\\n    at Module._compile (internal/modules/cjs/loader.js:689:30)\\n    at Object.Module._extensions..js (internal/modules/cjs/loader.js:700:10)\\n    at Module.load (internal/modules/cjs/loader.js:599:32)\\n    at tryModuleLoad (internal/modules/cjs/loader.js:538:12)\\n    at Function.Module._load (internal/modules/cjs/loader.js:530:3)\\n    at Function.Module.runMain (internal/modules/cjs/loader.js:742:12)\\n    at startup (internal/bootstrap/node.js:266:19)\\n    at bootstrapNodeJSCore (internal/bootstrap/node.js:596:3)\"}\n```\n\nSee [`index.test.html`](index.test.html) for example usage in the browser.\n\nYou can register a new handler by calling `addHandler` with a handling function. Or use `replaceHandlers` to replace any existing log handlers (including the default). If you don't want any log handling at all, remove the default handler using `removeHandlers`.\n\nLogga can be used with a log handling library e.g. Winston, Pino.\n\n```javascript\n// In library, create a named logger\nconst logger = getLogger('encoda')\n```\n\n```javascript\n// Handle the log messages in application code\naddHandler((data: LogData) =\u003e {\n  // Send off to log output function\n  winstonLogger.log(LogLevel[data.level], data.message)\n\n  // or filter on tag\n  if (data.tag === 'encoda') {\n    // do something different\n  }\n})\n```\n\n### Exiting the process\n\nWhen in Node.js, the `defaultHandler` will exit the process, with code 1, on the first error event. To disable this behavior set the option `exitOnError: false` e.g.\n\n```js\nreplaceHandlers((data) =\u003e defaultHandler(data, { exitOnError: false }))\n```\n\n## See also\n\nSee this [issue in `node-bunyan`](https://github.com/trentm/node-bunyan/issues/116) describing the use case for, and approaches to, a global, shared logger in Node.\n\n\u003e I guess this is similar to the idea in log4j (likewise clones like log4js, Python's logging module, etc.) where logger objects are global to the process such that, e.g., log = logging.getLogger(\"foo\") used in two separate modules gets the same logger.\n\n[`bole`](https://www.npmjs.com/package/bole) has the same goals as `logga` (but uses a singleton object instead of events)\n\n\u003e `bole` is designed for global singleton use. Your application has many log sources, but they all aggregate to the same sources. You configure output in one place for an application, regardless of how many modules and dependencies are also using `bole` for logging.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstencila%2Flogga","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstencila%2Flogga","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstencila%2Flogga/lists"}