{"_id":"@adze/transport-cloudwatch-logs","name":"@adze/transport-cloudwatch-logs","dist-tags":{"latest":"1.0.2"},"versions":{"1.0.2":{"name":"@adze/transport-cloudwatch-logs","version":"1.0.2","description":"Add-on for transporting logs to AWS Cloudwatch Logs.","main":"dist/index.js","author":{"name":"Andrew Stacy","email":"ajstacy@gmail.com"},"license":"Apache-2.0","bugs":{"url":"https://github.com/AJStacy/adze-transport-cloudwatch-logs/issues"},"homepage":"https://github.com/AJStacy/adze-transport-cloudwatch-logs#readme","repository":{"type":"git","url":"git+https://github.com/AJStacy/adze-transport-cloudwatch-logs.git"},"keywords":["cloudwatch","aws","logs","transport","adze"],"types":"./dist/index.d.ts","scripts":{"prebuild":"npm run clean","build":"babel src --out-dir dist --copy-files --extensions '.ts,.js' --ignore 'src/demo.ts,src/keys.ts' --no-copy-ignored","postbuild":"tsc --project tsconfig.prod.json","clean":"rm -rf ./dist","commit":"cz","demo":"babel src --out-dir dist --copy-files --extensions '.ts,.js' && node ./dist/demo.js","lint":"eslint .","lint:fix":"eslint . --fix","peers":"peerdeps","prepack":"npm run build","prepare":"husky install","semantic-release":"semantic-release","test":"ava","watch":"tsc --watch"},"peerDependencies":{"adze":"^1.9.0"},"dependencies":{"@aws-sdk/client-cloudwatch-logs":"^3.85.0"},"devDependencies":{"@ava/typescript":"^1.1.1","@babel/cli":"^7.17.10","@babel/core":"^7.18.2","@babel/plugin-proposal-nullish-coalescing-operator":"^7.17.12","@babel/preset-env":"^7.18.2","@babel/preset-typescript":"^7.17.12","@types/lodash.clonedeep":"^4.5.6","@types/lodash.defaultsdeep":"^4.6.6","@types/node":"^12.7.5","@types/node-localstorage":"^1.3.0","@typescript-eslint/eslint-plugin":"^4.14.0","@typescript-eslint/parser":"^4.14.0","ava":"^3.15.0","aws-sdk-client-mock":"^0.6.2","commitizen":"^4.2.3","cz-conventional-changelog":"^3.2.0","eslint":"^7.18.0","eslint-config-prettier":"^7.2.0","eslint-plugin-prettier":"^3.3.1","http-server":"^0.11.1","husky":"^6.0.0","lint-staged":"^10.5.4","peerdeps":"^1.1.1","prettier":"2.2.1","semantic-release":"^17.4.2","ts-node":"^10.8.0","typescript":"^4.7.2"},"config":{"commitizen":{"path":"./node_modules/cz-conventional-changelog"}},"lint-staged":{"*.ts":"eslint --cache --cache-location .eslint_cache --fix"},"gitHead":"bc257c33e6ad73b01f533c80dc812e3b1f605dd8","_id":"@adze/transport-cloudwatch-logs@1.0.2","_nodeVersion":"14.17.0","_npmVersion":"6.14.13","dist":{"integrity":"sha512-SoD2IHjm155go9hDueTanQHX5gaYboS0DiymZ3mpbELrJJ5YwF2NbcQpabSHQji9i1Xh9k8DQLDThJZrKUsjwg==","shasum":"f00c670d9050ec24cf40e31d6e610180d57e8e90","tarball":"https://registry.npmjs.org/@adze/transport-cloudwatch-logs/-/transport-cloudwatch-logs-1.0.2.tgz","fileCount":35,"unpackedSize":64863,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQD1cdP1Rn06NJ2t9htlMyadyC35PSYJnEkayX4J2UeLKwIhAIkC6vgEy9TDMnIQ37AZCi/dANRKSkNTNZcpncrxC0kX"}],"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v4.10.10\r\nComment: https://openpgpjs.org\r\n\r\nwsFzBAEBCAAGBQJismTuACEJED1NWxICdlZqFiEECWMYAoorWMhJKdjhPU1b\r\nEgJ2VmoO/RAAosf1gDgPlGnVp3D6WdS0TAJYOKHcGLQbXw2ePc/9T76GhCdS\r\nrsysK27hpTdocqZV/nYnTLupbF789EX/jGKbae+lLgIOdVagP1oi2+2TGZFQ\r\np4VdalyS7ctHh8zJMPF85b8LdwvJzso3sKLTMInMNGNTVh3eWCs430K2KMka\r\nIouPpTX3GXqaC5tSy6h36SB0DXLBWby6VG+tRND/J4eYFfrst3TCUe1eYdn4\r\nnD72wGGiOduyGmJgV+LVo/CchSN5u/EOToLHkg2ZlwDeATyjVmSH4e181N0H\r\nQV3OxRfRMlNXra2bXuG1G3sn3OvHI8pwDcaAQsMrKhcr/oi/FaY1C+FxBHI6\r\nLjElB3BZcJpYzx+R8t6NYxnO7eMAnxOcCoHkWskKxGCdl1K07wJNDhbP9k/k\r\nfXz8w77/PyTaUA9vcYxxTTYKY+c5ydlXyYoY6EmYrKVtpCOVRfYZjOsq7wnG\r\nJ1173uF38lycE1YNPM4o1LJSGIfED87TDr5CCMNvYIzEPgBRU3W6Nf6ADpUB\r\nqkF0N/oMSCETX/tUPihYQc0o9Bz7BA2F9VXcy3bbClgW3e0/gTb8QO/qELJl\r\nXYcm8OXirB4+GS5D1A9ZofMQUpy0vxX6lOLkewsWPCgdFz0w0rdPunhoqfc5\r\n1HdYAJk+b0PiwgwGsQBBC4Sb0KbO7jSESSs=\r\n=3kbb\r\n-----END PGP SIGNATURE-----\r\n"},"_npmUser":{"name":"ajstacy","email":"ajstacy@gmail.com"},"directories":{},"maintainers":[{"name":"ajstacy","email":"ajstacy@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/transport-cloudwatch-logs_1.0.2_1655858414443_0.24560269704420334"},"_hasShrinkwrap":false}},"time":{"created":"2022-06-22T00:40:14.368Z","1.0.2":"2022-06-22T00:40:14.608Z","modified":"2022-06-22T00:40:14.766Z"},"maintainers":[{"name":"ajstacy","email":"ajstacy@gmail.com"}],"description":"Add-on for transporting logs to AWS Cloudwatch Logs.","homepage":"https://github.com/AJStacy/adze-transport-cloudwatch-logs#readme","keywords":["cloudwatch","aws","logs","transport","adze"],"repository":{"type":"git","url":"git+https://github.com/AJStacy/adze-transport-cloudwatch-logs.git"},"author":{"name":"Andrew Stacy","email":"ajstacy@gmail.com"},"bugs":{"url":"https://github.com/AJStacy/adze-transport-cloudwatch-logs/issues"},"license":"Apache-2.0","readme":"# @adze/transport-cloudwatch-logs\n\n> This add-on is in its infancy and may not be completely stable. Please open issues and contribute!\n\nThis library is an add-on for transporting logs to AWS Cloudwatch Logs via [Adze](https://adzejs.com) [log listeners](https://adzejs.com/guide/shed-concepts.html#listeners).\n\nFor API Documentation for CloudWatch Logs, please visit [https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-cloudwatch-logs/index.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-cloudwatch-logs/index.html).\n\n## Minimum Requirements\n\n**browser** - ES6 Support Recommended\n\n**node** - `12.x`, `14.x` (recommended minimum), `16.x`, and `18.x`.\n\n**adze** - `v1.9.0` recommended (peer dependency)\n\n## Install\n\n```bash\n# install with npm\nnpm install -S @adze/transport-cloudwatch-logs\n\n# install with pnpm\npnpm install -S @adze/transport-cloudwatch-logs\n\n# install with yarn\nyarn add @adze/transport-cloudwatch-logs\n```\n\n## Quick Start\n\nAs with any [Adze](https://adzejs.com) add-on, it takes advantage of log listeners by returning a log listener callback function for you to handle your logs. This allows you as the user to specify which log levels you would like the add-on to watch.\n\nHere is a basic example of setting up a CloudWatch Logs transport that listens for alerts and errors.\n\n```javascript\nimport adze, { createShed } from 'adze';\nimport TransportCloudWatchLogs from '@adze/transport-cloudwatch-logs';\n\n// First, create a new instance of the transport and provide it with CloudWatch Logs credentials.\nconst client = new TransportCloudWatchLogs(\n  {\n    region: 'us-east-1',\n    credentials: {\n      accessKeyId: 'XXXXXXXXXXXXXXXXXXXX',\n      secretAccessKey: 'XxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXx',\n    },\n  }\n);\n\n// Create our Shed\nconst shed = createShed();\n\n// Add our log listener for alert and error level logs to be transported\nshed.addListener([0, 1], client.stream('my-group', 'errors'));\n\n// Kick off our command queue to begin sending the logs to cloudwatch\nclient.processCommands();\n\nadze().alert('This log will be transported to CloudWatch Logs.');\n```\n\n## Configuration\n\nThis transport allows two configuration objects in the constructor. The first parameter configures the underlying [AWS CloudWatchLogs client](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-cloudwatch-logs/index.html). The second parameter configures the transport.\n\n### Transport Configuration Interface\n\n```javascript\n/**\n * Configuration for handling transportation of your application\n * logs to AWS CloudWatch Logs.\n *\n * @param batchSize The maximum amount of bytes to be sent in a single batch. Default is 1000000.\n * @param transportHiddenLogs Should we send logs to CloudWatch that did not print to the console? Default is false.\n * @param rate The rate at which to send commands to CloudWatch Logs. Default is 1000 (ms).\n * @param retries Number of times to retry sending a command if it fails. Default is 3.\n * @param createLogGroup When enabled, creates a log group automatically if it doesn't already exist. Default is false.\n * @param createLogStream When enabled, creates a log stream automatically if it doesn't already exist. Default is false.\n */\nexport interface Configuration {\n  batchSize: number;\n  transportHiddenLogs: boolean;\n  rate: number;\n  retries: number;\n  createLogGroup: boolean;\n  createLogStream: boolean;\n}\n```\n\n## Methods\n\nThe transport exposes a handful of methods for streaming log events and controlling the flow of the transport of logs to AWS CloudWatch.\n\n### stream\n\nThis method generates a callback function for an Adze log listener. This callback function captures logs, creates a CloudWatch Logs event, and sets them to a queue to be processed in the background of your application. You can create as many streams as you want as well as create duplicates.\n\n#### stream Example\n\n```javascript\n// Create our Shed\nconst shed = createShed();\n\n// Add our log listener for alert and error level logs to be transported\nshed.addListener([1], client.stream('my-group', 'errors'));\n\n// Let's also create a stream for warning and info logs.\nshed.addListener([2, 3], client.stream('my-group', 'warnings-info'));\n\n// We can also create multiple listeners for the same stream. Here we will add alerts to our 'errors' stream.\nshed.addListener([0], client.stream('my-group', 'errors'));\n```\n\n---\n\n### processCommands\n\nThis method kicks off an interval in the background that will periodically send log event commands that have been queued to CloudWatch Logs. Logs will **not** be sent to CloudWatch Logs unless this method is called within your application.\n\n#### processCommands Example\n\n```javascript\n// Create our Shed\nconst shed = createShed();\n\n// Add our log listener for alert and error level logs to be transported\nshed.addListener([0, 1], client.stream('my-group', 'errors'));\n\n// Kick off our command queue to begin sending the logs to cloudwatch\nclient.processCommands();\n```\n\n---\n\n### stopCommands\n\nThis method stops all command queues from processing log events and sending them to CloudWatch Logs.\n\n#### stopCommands Example\n\n```javascript\n// Create our Shed\nconst shed = createShed();\n\n// Add our log listener for alert and error level logs to be transported\nshed.addListener([0, 1], client.stream('my-group', 'errors'));\n\n// Kick off our command queue to begin sending the logs to cloudwatch\nclient.processCommands();\n\nadze().log('Writing my logs...');\n\n// Later...\nclient.stopCommands();\n```\n\n---\n\n### setClient\n\nThis method allows you to set your own instance of the CloudWatch Logs client into the transport. You will normally not need to do this as the transport creates its own instance by default (this is primarily used for unit testing).\n\n#### setClient Example\n\n```javascript\nimport adze, { createShed } from 'adze';\nimport TransportCloudWatchLogs from '@adze/transport-cloudwatch-logs';\nimport { CloudWatchLogs } from '@aws-sdk/client-cloudwatch-logs';\n\n// Create our CloudWatch Logs configuration.\nconst config = {\n  region: 'us-east-1',\n  credentials: {\n    accessKeyId: 'XXXXXXXXXXXXXXXXXXXX',\n    secretAccessKey: 'XxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXx',\n  },\n};\n\n// First, create a new instance of the transport and provide it with CloudWatch Logs credentials.\nconst client = new TransportCloudWatchLogs(config);\n\n// Create our own instance of CloudWatchLogs\nconst cloudwatch = new CloudWatchLogs(config);\n\n// Set our own instance of CloudWatchLogs as the instance to be used by TransportCloudWatchLogs\nclient.setClient(cloudwatch);\n```\n\n---\n\n## Stream Hooks\n\nWhen creating a stream you can provide a configuration object that contains callback functions for hooking into successful log event commands and for handling failed log event commands.\n\nThe `failure` hook is fired when a sending a log event command fails. The `data` parameter is the log event data used to create the failed command and the `error` parameter is the JavaScript `Error` object that was thrown with the failure.\n\nThe `success` hook is fired when a sending a log event command has succeeded. The `data` parameter is the log event data used to create the successful command and the `response` parameter is the response from AWS CloudWatch Logs ([PutLogEventsCommandOutput](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-cloudwatch-logs/interfaces/putlogeventscommandoutput.html)).\n\n### Stream Hooks Example\n\n```javascript\n// Let's create our stream configuration.\nconst streamConfig = {\n  failure: (data, error) => {\n    // Handle our errors...\n  },\n  success: (data, response) => {\n    // Handle successful commands...\n  },\n};\n\n// Add our stream configuration when creating our stream.\nshed.addListener([0], client.stream('my-group', 'errors', streamConfig));\n```\n\n## Stream Group Tags\n\nWhen an instance of the transport has been configured to automatically create new log groups if they do not already exist, you can apply tags to these new log groups through the stream configuration object.\n\n```javascript\n// Let's create our stream configuration.\nconst streamConfig = {\n  groupTags: {\n    foo: 'bar',\n  },\n};\n\n// Add our stream configuration when creating our stream.\nshed.addListener([0], client.stream('my-group', 'errors', streamConfig));\n```\n","readmeFilename":"README.md"}