![](\"https://raw.githubusercontent.com/logdna/artwork/master/logo%2Bnode.png\")
\n \n \n \n \n \n
Node.js Winston library for logging to LogDNA
\n\n\n---\n\n\n[](#contributors-)\n\n\n* **[Install](#install)**\n* **[API](#api)**\n* **[Winston Transport](#winston-transport)**\n* **[License](#license)**\n\n\n## Install\n\n```sh\n$ npm install --save logdna-winston\n```\n\n## API\n\nPlease see [@logdna/logger](https://www.npmjs.com/package/@logdna/logger#createloggerkey-options) for\ninstantiation options to passthrough to LogDNA's logger client.\n\n## Winston Transport\n\nThis module also provides a transport object, which can be added to winston using:\n\n```javascript\nconst logdnaWinston = require('logdna-winston');\nconst winston = require('winston');\nconst logger = winston.createLogger({});\nconst options = {\n key: apikey,\n hostname: myHostname,\n ip: ipAddress,\n mac: macAddress,\n app: appName,\n env: envName,\n level: level, // Default to debug, maximum level of log, doc: https://github.com/winstonjs/winston#logging-levels\n indexMeta: true // Defaults to false, when true ensures meta object will be searchable\n}\n\n// Only add this line in order to track exceptions\noptions.handleExceptions = true;\n\nlogger.add(new logdnaWinston(options));\n\n\n// log with meta\nlogger.log({\n level: 'info'\n, message: 'Log from LogDNA-winston'\n, indexMeta: true // Optional. If not provided, it will use the default.\n, data:'Some information' // Properties besides level, message and indexMetaare considered as \"meta\"\n, error: new Error(\"It's a trap.\") // Transport will parse the error object under property 'error'\n})\n\n// log without meta\nlogger.info('Info: Log from LogDNA-winston');\n\n// A payload without 'message' will log the stringified object as the message\nlogger.info({\n key: 'value'\n, text: 'This is some text to get logged'\n, bool: true\n})\n```\n\n## Custom Log Levels\n\nAs per the Winston documentation, [custom log levels](https://github.com/winstonjs/winston#using-custom-logging-levels) may be used. In order to use such\nlevels in LogDNA, [custom levels must be defined](https://github.com/logdna/logger-node#custom-log-levels) for that logger as well. If `levels` is passed to this transport, they\nwill **automatically** be configured as custom levels for the LogDNA logger.\n\nSimilarly, if no custom winston levels are used, then the Winston [default of \"npm\" levels](https://github.com/winstonjs/winston#logging-levels) will be automatically configured for LogDNA to understand. \n\n**NOTE:** The \"levels\" parameter is in the context of Winston, thus it should be an object where the keys are the level names, and the values are a numeric priority.\n\n```javascript\n const levels = {\n error: 0\n , warn: 1\n , info: 2\n , http: 3\n , verbose: 4\n , loquacious: 5\n , ludicrous: 6\n }\n const logger = winston.createLogger({\n levels\n , level: 'ludicrous' // needed, or else it won't log levels <= to 'info'\n })\n\n const logdna_options = {\n key: 'abc123'\n }\n logger.add(new logdnaWinston(logdna_options))\n\n // Now the custom levels can be logged in Winston and LogDNA\n logger.ludicrous('Some text')\n\n logger.log({\n msg: 'Custom level log message'\n , key: 'value'\n , bool: true\n , level: 'loquacious'\n })\n```\n\n## The `maxLevel` Parameter\n\nBoth the Winston logger and the LogDNA logger accept a `level` parameter, but they mean different things:\n\n* For Winston, `level` represents the maximum log level by priority. In other words, anything \"higher\" in priority number WILL NOT be logged.\n* In LogDNA, `level` represents a default log level which is used in the absence of a level being defined for each log entry. Since Winston always passed a log level, this parameter is not usable in this transport.\n\nTo disambiguate the two `level` parameters (even though the LogDNA one cannot be used), this custom transport will accept the `maxLevel` parameter to be used as Winston's `level` parameter. This is **only needed if** `level` has not been defined during Winston's `createLogger` call prior to adding this custom transport.\n\n```js\nconst winston = require('winston')\nconst logdnaTransport = require('logdna-winston')\n\nconst logger = winston.createLogger({\n level: 'verbose'\n, transports:[new logdnaTransport({key: 'abc123'})]\n})\nlogger.silly('This will not be logged')\nlogger.verbose('This will be logged')\n\n// ...is the same as this\n const logger = winston.createLogger({\n transports:[\n new logdnaTransport({\n key: 'abc123'\n , maxLevel: 'verbose'\n })\n ]\n})\nlogger.silly('This will not be logged')\nlogger.verbose('This will be logged')\n```\n## Contributors ✨\n\nThanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):\n\n\n\n\n![\"\"/](\"https://avatars.githubusercontent.com/u/1046364?v=4?s=100\") Muaz Siddiqui 💻 📖 | \n ![\"\"/](\"https://avatars.githubusercontent.com/u/34287490?v=4?s=100\") Samir Musali 💻 📖 | \n ![\"\"/](\"https://avatars.githubusercontent.com/u/1874788?v=4?s=100\") Darin Spivey 💻 📖 | \n ![\"\"/](\"https://avatars.githubusercontent.com/u/14082239?v=4?s=100\") Mike Huang 💻 📖 | \n ![\"\"/](\"https://avatars.githubusercontent.com/u/1328448?v=4?s=100\") Brian Conn 📖 | \n ![\"\"/](\"https://avatars.githubusercontent.com/u/105319?v=4?s=100\") Mario Casciaro 💻 | \n ![\"\"/](\"https://avatars.githubusercontent.com/u/17367511?v=4?s=100\") vilyapilya 🔧 | \n
![\"\"/](\"https://avatars.githubusercontent.com/u/69520?v=4?s=100\") Mike Del Tito 💻 🔧 | \n