{"id":21140653,"url":"https://github.com/bdfoster/nomatic-logging","last_synced_at":"2026-05-20T03:36:08.230Z","repository":{"id":143901450,"uuid":"86256611","full_name":"bdfoster/nomatic-logging","owner":"bdfoster","description":"Seriously awesome logging library built for Node.js","archived":false,"fork":false,"pushed_at":"2019-08-26T15:35:24.000Z","size":6355,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-07T22:02:08.357Z","etag":null,"topics":["logger","logging","node-js"],"latest_commit_sha":null,"homepage":"https://bdfoster.github.io/nomatic-logging","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bdfoster.png","metadata":{"files":{"readme":"README.md","changelog":null,"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}},"created_at":"2017-03-26T18:50:23.000Z","updated_at":"2017-04-03T15:32:02.000Z","dependencies_parsed_at":"2023-05-27T20:00:08.736Z","dependency_job_id":null,"html_url":"https://github.com/bdfoster/nomatic-logging","commit_stats":null,"previous_names":["bdfoster/nomatic-logger"],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bdfoster%2Fnomatic-logging","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bdfoster%2Fnomatic-logging/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bdfoster%2Fnomatic-logging/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bdfoster%2Fnomatic-logging/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bdfoster","download_url":"https://codeload.github.com/bdfoster/nomatic-logging/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243581092,"owners_count":20314167,"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":["logger","logging","node-js"],"created_at":"2024-11-20T07:17:05.706Z","updated_at":"2026-05-20T03:36:03.212Z","avatar_url":"https://github.com/bdfoster.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# nomatic-logging\n\n[![Greenkeeper badge](https://badges.greenkeeper.io/bdfoster/nomatic-logging.svg)](https://greenkeeper.io/)\n[![Semantic Release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)\n[![GitHub release](https://img.shields.io/github/release/bdfoster/nomatic-logging.svg)](https://github.com/bdfoster/nomatic-logging/releases)\n[![npm](https://img.shields.io/npm/v/nomatic-logging.svg)](https://www.npmjs.com/package/nomatic-logging)\n[![Build Status](https://travis-ci.org/bdfoster/nomatic-logging.svg?branch=greenkeeper%2Finitial)](https://travis-ci.org/bdfoster/nomatic-logging)\n[![Coverage Status](https://coveralls.io/repos/github/bdfoster/nomatic-logging/badge.svg)](https://coveralls.io/github/bdfoster/nomatic-logging)\n[![Known Vulnerabilities](https://snyk.io/test/github/bdfoster/nomatic-logging/badge.svg)](https://snyk.io/test/github/bdfoster/nomatic-logging)\n[![dependencies Status](https://david-dm.org/bdfoster/nomatic-logging/status.svg)](https://david-dm.org/bdfoster/nomatic-logging)\n[![devDependencies Status](https://david-dm.org/bdfoster/nomatic-logging/dev-status.svg)](https://david-dm.org/bdfoster/nomatic-logging?type=dev)\n[![License](https://img.shields.io/github/license/bdfoster/nomatic-logging.svg)](https://github.com/bdfoster/nomatic-logging/blob/master/LICENSE)\n\n### Overview\n**Get serious about logging.** This library takes the best concepts of\n[winston](https://github.com/winstonjs/winston) and [bunyan](https://github.com/trentm/node-bunyan) to create a flexible\nyet elegant logging solution for any Node.js library or application. You decide what to do with generated logs by using\nthe included transports or creating your own, very easily. You can even decide how to manage logs from your project's\ndependencies (if they are using this library, of course). A log doesn't have to be just a message, either. You can\ndata to the log message or have a message generated for you from the data via templates.\n\n### Goals\n* **Reliable**: It should fail predictably, and with valid cause. Log data is sensitive and important to determining the\nstatus of the dependent application. This is done with extensive unit and integration testing along with proper\nsemantic versioning.\n* **Flexible**: Each dependent package will use this in a different way. Design it in a way that will fit most use \ncases.\n* **Elegant**: It should be easy to get started, yet support complex use cases when needed.\n* **Fast**: Logging is boring, but essential. Do what we need to do, quickly, and get out of the way.\n\n### Installation\nYou can install from [npm](https://www.npmjs.com/package/nomatic-logging) by doing:\n```bash\nnpm install --save nomatic-logging\n```\n\n### Basic Usage\nTo get the default ```Logger```:\n```javascript\nconst logger = require('nomatic-logging');\n```\n...which is equivalent to (if the namespace is not already taken):\n```javascript\nconst logging = require('nomatic-logging');\nconst Logger = logging.Logger;\nconst ConsoleTransport = logging.ConsoleTransport;\nconst logger = new Logger('root', {\n    transports: [\n        new ConsoleTransport({\n            level: 'info'\n        })\n    ]\n});\n```\nNow, ```logger``` has a name of ```root``` and a way to send logs of level ```info``` and above to the console.\n\nThen, to use it:\n```javascript\nlogger.info('test');\n// with data:\nlogger.info('test', {\n    isTest: true\n});\n```\nYou read that right. You can send data with your message. As a matter of fact, you can just send data with your log and\nhave the ```Logger``` parse it into a message for you:\n```javascript\nlogger.template = '{method} {url} {status} {length} {ms}';\nlogger.info({\n    method: 'GET',\n    url: '/path/to/resource',\n    status: 200,\n    length: '1214',\n    ms: 22\n});\n```\n\nTo listen for all entries generated on `logger`:\n```javascript\nlogger.on('entry', (entry) =\u003e {\n    /* `entry` is an object with `namespace`, `message`, `level`,\n    * `hostname`, `createdAt`, and optional `data` fields.\n    */\n    console.log(`[${entry.level}]\\t${entry.message}`);\n});\n```\n\nTo listen for the 'info' log level entries:\n```javascript\nlogger.on('info', (entry) =\u003e {\n    console.log(`[INFO]\\t${entry.message}`);\n});\n```\nBecause we are using ```EventEmitter``` from [```nomatic-events```](https://www.npmjs.com/package/nomatic-events), you can also use a regex:\n```javascript\nlogger.on(/(info|debug)/, (entry) =\u003e {\n    console.log(`[${entry.level}]\\t${entry.message}`);\n})\n```\n\nYou can create your own transport very easily:\n```javascript\nconst Transport = require('nomatic-logging').Transport;\nclass DatabaseTransport extends Transport {\n    public execute(entry) {\n        /// do something here\n    }\n}\n\nconst myTransport = new DatabaseTransport({\n    level: 'debug'\n});\n```\nYou can send log entries to a database, a file, a remote server, whatever you want. This is where `nomatic-logging`\nbecomes very powerful, and not just a complicated replacement for `console.log()`.\n\nYou can then subscribe `myTransport` to a logger:\n```javascript\nlogger.use(myTransport);\n```\n\nA log `entry` object looks like this:\n```typescript\ninterface Entry {\n  namespace?: string;\n  level: string;\n  message: string;\n  createdAt: Date;\n  hostname: string;\n  data?: Object;\n}\n```\nAs you can see, the only two properties that are optional are `namespace` and `data`. `namespace` is optional because\nit is optional in the `Logger` class. You can use the `Logger` class directly, and potentially export it as part of your\nlibrary or module:\n```javascript\nconst Logger = logging.Logger;\nmodule.exports.logger = new Logger();\n```\nThe `Logger` class uses no transport(s) by default. You can specify one (or more) when instantiating or do:\n```javascript\nmodule.exports.logger.configure({\n    transports: [\n        logging.transport.console,\n        myTransport,\n    ] \n});\n```\nThis will override properties at a top-level basis (i.e. if you specify `transports`, any other transports specified\nwill no longer be used by the logger).\n\nAnything you can configure via `configure`, you can pass on instantiation:\n```javascript\nconst myLogger = new Logger({\n    transports: [\n        logging.transport.console,\n        myTransport,\n    ]\n});\n```\nA logger can also have child loggers:\n```javascript\nlogger.create('app');\n```\n...which have all the same levels and transports of the parent. If you try to create another logger with the same name\non this parent, it will throw an exception. When you configure the parent, the parent will push the same configuration\nall child loggers.\n\nLoggers also have a `get` method, which will either return a logger or create one if it does not exist:\n```javascript\nlogger.get('app'); // returns the previously created Logger instance of the same name\nlogger.get('app2'); // creates then returns a Logger instance with `name` of 'app2'\n```\n\n### TypeScript\nThis library is developed with [TypeScript](http://www.typescriptlang.org/), and as such, includes definitions.\nHowever, you do not even need to know what TypeScript is to use this package. The compiled project is included in the\n[npm package](http://npmjs.com/package/nomatic-logging).\n\n### Testing\nYou can run tests by doing:\n```bash\nnpm test\n```\nA summary of code coverage shows up at the end of the output, but if you want the HTML site, do:\n```bash\nnpm run coverage\n```\nI do strive for 100% code coverage since this is a very small library. I would ask for the same when submitting a PR.\nIf you need help with writing tests, ping me and I will either write them for you (if it's small enough) or give you\nguidance on how to do so.\n\n### Future Plans\n* Make usable in both Node.js and the browser (currently only supported in Node.js)\n* Add more transports (either included in the main project or as plugins), including:\n  - HTTP (sending log entries via JSON or text to a remote server)\n  - File (with log-rotate capabilities)\n  - Node.js streams\n* Improve test cases, remove clutter, etc. to build even more confidence in the project\n\n### Contributing / Support\nPlease note that this software is in the early stages of development, but is in production use in several of my\npersonal projects and university/work endeavors.\n\nPull requests are absolutely welcome, and issues can be raised for questions or bugs. I do understand the documentation is a\nlittle sparse at the moment, and I'm certainly working to expand that very, very soon. If you need help using the\nlibrary, submit an issue for it and I'll be sure to document it (first in the issue itself, then in the actual\ndocumentation).\n\nPlease remember that this is something I maintain and build upon in my spare time. If you need paid support for a\nparticular solution, feature, or bug, please feel free to send me a message. Generally speaking, I'm very responsive\nduring the work week.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbdfoster%2Fnomatic-logging","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbdfoster%2Fnomatic-logging","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbdfoster%2Fnomatic-logging/lists"}