{"id":13484067,"url":"https://github.com/lazywithclass/winston-cloudwatch","last_synced_at":"2025-04-11T22:30:17.298Z","repository":{"id":24220045,"uuid":"27612143","full_name":"lazywithclass/winston-cloudwatch","owner":"lazywithclass","description":"Send logs to Amazon Cloudwatch using Winston.","archived":false,"fork":false,"pushed_at":"2024-04-30T15:17:08.000Z","size":697,"stargazers_count":257,"open_issues_count":55,"forks_count":103,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-05-22T00:04:04.614Z","etag":null,"topics":["aws","aws-sdk","javascript","logging","winston"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","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/lazywithclass.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}},"created_at":"2014-12-05T22:03:25.000Z","updated_at":"2024-05-31T23:48:38.283Z","dependencies_parsed_at":"2023-01-14T00:36:12.981Z","dependency_job_id":"3785d940-5a5f-4dd7-ad13-736fef726139","html_url":"https://github.com/lazywithclass/winston-cloudwatch","commit_stats":{"total_commits":265,"total_committers":45,"mean_commits":5.888888888888889,"dds":"0.25283018867924534","last_synced_commit":"72b4c9d81540efd3c574fcbb667d07fed7162f78"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lazywithclass%2Fwinston-cloudwatch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lazywithclass%2Fwinston-cloudwatch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lazywithclass%2Fwinston-cloudwatch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lazywithclass%2Fwinston-cloudwatch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lazywithclass","download_url":"https://codeload.github.com/lazywithclass/winston-cloudwatch/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248489396,"owners_count":21112563,"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":["aws","aws-sdk","javascript","logging","winston"],"created_at":"2024-07-31T17:01:18.939Z","updated_at":"2025-04-11T22:30:17.246Z","avatar_url":"https://github.com/lazywithclass.png","language":"JavaScript","readme":"# winston-cloudwatch [v6.3.0](https://github.com/lazywithclass/winston-cloudwatch/blob/master/CHANGELOG.md#630)\n\n| :warning: WARNING          |\n|:---------------------------|\n| I realised I don't have time anymore to work on this. It's very likely no more updates will be made on this project. |\n\n[![Build Status](https://travis-ci.org/lazywithclass/winston-cloudwatch.svg?branch=master)](https://travis-ci.org/lazywithclass/winston-cloudwatch) [![Coverage Status](https://coveralls.io/repos/github/lazywithclass/winston-cloudwatch/badge.svg?branch=master)](https://coveralls.io/github/lazywithclass/winston-cloudwatch?branch=master)\n==================\n\nSend logs to Amazon Cloudwatch using [Winston](https://github.com/winstonjs/winston)\n\nStarting from version 3.0.0 we moved aws-sdk into devDependencies to reduce the size of the package, so if you're not using this on AWS Lambda make sure you add aws-sdk dependency into your application package.json.\n\nIf you were using this library before version 2.0.0 have a look at the \n[migration guide for Winston](https://github.com/winstonjs/winston/blob/master/UPGRADE-3.0.md) and at the updated\n[examples](examples).\n\n * [Features](#features)\n * [Installing](#installing)\n * [Configuring](#configuring)\n * [Usage](#usage)\n * [Options](#options)\n * [Examples](#examples)\n * [Simulation](#simulation)\n\n### Features\n\n * logging to AWS CloudWatchLogs\n * [logging to multiple streams](#logging-to-multiple-streams)\n * [programmatically flush logs and exit](#programmatically-flush-logs-and-exit)\n * logging with multiple levels\n * creates group / stream if they don't exist\n * waits for an upload to suceed before trying the next\n * truncates messages that are too big\n * batches messages taking care of the AWS limit (you should use more streams if you hit this a lot)\n * support for Winston's uncaught exception handler\n * support for TypeScript, see [TypeScript definition](https://github.com/lazywithclass/winston-cloudwatch/blob/master/typescript/winston-cloudwatch.d.ts)\n * [see options for more](#options)\n\n### Installing\n\n```sh\n$ npm install --save winston winston-cloudwatch @aws-sdk/client-cloudwatch-logs\n```\n\nAlso consider that we have both winston and @aws-sdk/client-cloudwatch-logs configured as peerDependencies.\n\n### Configuring\n\nAWS configuration works using `~/.aws/credentials` as written in [AWS JavaScript SDK guide](http://docs.aws.amazon.com/AWSJavaScriptSDK/guide/node-configuring.html#Setting_AWS_Credentials).\n\nAs a best practice remember to use one stream per resource, so for example if you have 4 servers you should setup 4 streams\non AWS CloudWatch Logs, this is a general best practice to avoid incurring in token clashes and to avoid limits of the service (see [usage](#usage) for more).\n\n#### Credentials\n\nUse `awsOptions` to set your credentials, like so:\n\n```JavaScript\nnew WinstonCloudWatch({\n  ...,\n  awsOptions: {\n    credentials: {\n      accessKeyId,\n      secretAccessKey,\n    },\n    region,\n  }\n})\n```\n\n#### Region note\n\nAs specified [in the docs](http://docs.aws.amazon.com/AWSJavaScriptSDK/guide/node-configuring.html#Setting_the_Region):\n\n \u003e The AWS SDK for Node.js doesn't select the region by default.\n\nso you should take care of that. See the [examples](#examples) below.\n\nIf either the group or the stream do not exist they will be created for you.\n\n#### AWS UI\n\nFor displaying time in AWS CloudWatch UI you should click on the gear in the top right corner in the page with your logs and enable checkbox \"Creation Time\".\n\n##### TypeScript\n\nRemember to install types for both winston and this library.\n\n### Usage\n\nPlease refer to [AWS CloudWatch Logs documentation](http://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutLogEvents.html) for possible contraints that might affect you.\nAlso have a look at [AWS CloudWatch Logs limits](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/cloudwatch_limits_cwl.html).\n\nIn ES5\n```js\nvar winston = require('winston'),\n    WinstonCloudWatch = require('winston-cloudwatch');\n```\n\nIn ES6\n\n```js\nimport { createLogger, format } from 'winston';\nimport * as WinstonCloudWatch from 'winston-cloudwatch';\n\nexport const log = createLogger({\n  level: 'debug',\n  format: format.json(),\n  transports: [\n    new WinstonCloudWatch({\n      level: 'error',\n      logGroupName: 'groupName',\n      logStreamName: 'errors',\n      awsRegion: 'eu-west-3'\n      }),\n  ]\n});\n```\n\nYou can also specify a function for the `logGroupName` and `logStreamName` options. This is handy if you are using this module in a server, say with [express](https://github.com/bithavoc/express-winston), as it enables you to easily split streams across dates, for example. There is an example of this [here](https://github.com/lazywithclass/winston-cloudwatch/blob/master/examples/function-config.js).\n\n#### Logging to multiple streams\n\nYou could also log to multiple streams with / without different log levels, have a look at [this example](https://github.com/lazywithclass/winston-cloudwatch/blob/master/examples/multiple-loggers.js).\n\nConsider that when using this feature you will have two instances of winston-cloudwatch, each with its own `setInterval` running.\n\n#### Programmatically flush logs and exit\n\nThink AWS Lambda for example, you don't want to leave the process running there for ever waiting for logs to arrive.\n\nYou could have winston-cloudwatch to flush and stop the setInterval loop (thus exiting), have a look\nat [this example](https://github.com/lazywithclass/winston-cloudwatch/blob/master/examples/flush-and-exit.js).\n\n#### Custom AWS.CloudWatchLogs instance\n\n```js\nconst AWS = require('aws-sdk');\n\nAWS.config.update({\n  region: 'us-east-1',\n});\n\nwinston.add(new WinstonCloudWatch({\n  cloudWatchLogs: new AWS.CloudWatchLogs(),\n  logGroupName: 'testing',\n  logStreamName: 'first'\n}));\n\n```\n\n### Options\n\nThis is the list of options you could pass as argument to `winston.add`:\n\n * name - `string`\n * level - defaults to `info`\n * logGroupName - `string` or `function`\n * logStreamName - `string` or `function`\n * cloudWatchLogs - `AWS.CloudWatchLogs` instance, used to set custom AWS instance.\n * awsOptions - `object`, params as per [docs](http://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/CloudWatchLogs.html#constructor-property), values in `awsOptions` are overridden by any other if specified, run [this example](https://github.com/lazywithclass/winston-cloudwatch/blob/master/examples/simple-with-aws-options.js) to have a look; you should put your `accessKeyId` and `secretAccessKey` under a nexted `credentials` property, specify `region` under `awsOptions`\n * jsonMessage - `boolean`, format the message as JSON\n * messageFormatter - `function`, format the message the way you like. This function will receive a `log` object that has the following properties: `level`, `message`, and `meta`, which are passed by winston to the `log` function (see [CustomLogger.prototype.log as an example](https://github.com/winstonjs/winston#adding-custom-transports))\n * uploadRate - `Number`, how often logs have to be sent to AWS. Be careful of not hitting [AWS CloudWatch Logs limits](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/cloudwatch_limits_cwl.html), the default is 2000ms.\n * errorHandler - `function`, invoked with an error object, if not provided the error is sent to `console.error`\n * retentionInDays - `Number`, defaults to `0`, if set to one of the possible values `1, 3, 5, 7, 14, 30, 60, 90, 120, 150, 180, 365, 400, 545, 731, 1827, and 3653` the retention policy on the log group written will be set to the value provided.\n\nAWS keys are usually picked by `aws-sdk` so you don't have to specify them, I provided the option just in case. Remember that `awsRegion` should still be set if you're using IAM roles.\n\n### Examples\n\nPlease refer to [the provided examples](https://github.com/lazywithclass/winston-cloudwatch/blob/master/examples) for more hints.\n\nNote that when running the examples the process will not exit because of the [`setInterval`](https://github.com/lazywithclass/winston-cloudwatch/blob/master/index.js#L73)\n\n### Simulation\n\nYou could simulate how winston-cloudwatch runs by using the files in \n`examples/simulate`:\n\n * `running-process.js` represents a winston-cloudwatch process that sits there,\n sends a couple logs then waits for a signal to send more\n * `log.sh` is a script that you could run to send logs to the above\n \nAt this point you could for example run `log.sh` in a tight loop, like so\n\n```bash\n$ while true; do ./examples/simulate/log.sh $PID; sleep 0.2; done\n```\n\nand see what happens in the library, this might be useful to test if you need\nmore streams for example, all you need to do is change `running-process.js` to\nbetter reflect your needs.\n\nIf you want more detailed information you could do\n\n```bash\n$ WINSTON_CLOUDWATCH_DEBUG=true node examples/simulate/running-process.js\n```\n\nwhich will print lots of debug statements as you might've guessed.\n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flazywithclass%2Fwinston-cloudwatch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flazywithclass%2Fwinston-cloudwatch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flazywithclass%2Fwinston-cloudwatch/lists"}