{"id":26267264,"url":"https://github.com/oslabs-beta/cat-a-log","last_synced_at":"2025-04-30T19:08:26.502Z","repository":{"id":264377989,"uuid":"893199673","full_name":"oslabs-beta/cat-a-log","owner":"oslabs-beta","description":"Add Embedded Metric Formatting to Structured logs for easy visualization in AWS Cloudwatch Metrics.","archived":false,"fork":false,"pushed_at":"2025-04-07T22:39:24.000Z","size":3677,"stargazers_count":25,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"dev","last_synced_at":"2025-04-30T19:07:05.173Z","etag":null,"topics":["aws","aws-emf","aws-lambda","cats","embedded-metric-format","log","logs","metrics","structured-logging"],"latest_commit_sha":null,"homepage":"","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/oslabs-beta.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,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"open-source-labs","custom":["https://donorbox.org/donations-to-oslabs-inc"]}},"created_at":"2024-11-23T19:47:00.000Z","updated_at":"2025-04-07T22:39:28.000Z","dependencies_parsed_at":"2024-12-12T05:18:44.155Z","dependency_job_id":"9406a868-afc8-4f0c-9729-a9f85f526cec","html_url":"https://github.com/oslabs-beta/cat-a-log","commit_stats":null,"previous_names":["oslabs-beta/cat-a-log"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oslabs-beta%2Fcat-a-log","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oslabs-beta%2Fcat-a-log/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oslabs-beta%2Fcat-a-log/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oslabs-beta%2Fcat-a-log/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oslabs-beta","download_url":"https://codeload.github.com/oslabs-beta/cat-a-log/tar.gz/refs/heads/dev","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251767192,"owners_count":21640468,"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-emf","aws-lambda","cats","embedded-metric-format","log","logs","metrics","structured-logging"],"created_at":"2025-03-14T04:16:20.342Z","updated_at":"2025-04-30T19:08:26.496Z","avatar_url":"https://github.com/oslabs-beta.png","language":"JavaScript","readme":" \u003cp align=\"center\"\u003e\n  \u003cimg src=\"./snapshots/Catalog_art.png\" width=\"200\" /\u003e\n  \u003c/p\u003e\n\n# Welcome to Cat-A-Log!\nThis npm package helps you integrate AWS CloudWatch with AWS Embedded Metric Format (EMF) Logs and publish them to Cloudwatch using AWS Lambda Powertools. EMF formatting will allow for chosen metrics to be automatically visualized in Cloudwatch metrics for centralized observability of your application KPIs. Read Our Medium article to learn more about the Cat-A-Log story:\n\u003ca href=\"https://medium.com/cat-a-log/adding-embedded-metric-formatting-to-aws-lambda-logs-for-simplified-debugging-ee388fdfd3db\" target=\"_blank\"\u003eEasily Automate Custom Metrics in CloudWatch with EMF in Lambda\u003c/a\u003e\n\n## Table of Contents\n- [Cat-A-Log](#why-use-cat-a-log)\n- [EMF](#about-embedded-metric-formatting-emf)\n- [Instructions](#instructions)\n- [How to Contribute](#open-source-contributions)\n- [Contributors](#contributor-information)\n\n\n  \u003c!-- \u003cp align=\"center\"\u003e\n  \u003cimg src=\"./snapshots/Catalog_art.png\" width=\"200\" /\u003e\n  \u003c/p\u003e --\u003e\n\n## Why use Cat-A-Log?\nWhy use a washing machine when you can do them by hand? Because it saves you time and makes your job way easier! Leveraging AWS Lambda Powertools we can use the cat-a-log function to invoke and format logs into AWS Embedded Metric Format. By publishing these logs to AWS Cloudwatch, we are able to provide engineers with automatic metric visualization to make the process of debugging logs much more efficient. Cat-a-log utilizes a cache to make efficient work of sending logs to Cloudwatch.\n\n## About Embedded Metric Formatting (EMF):\nEMF is a JSON specification that enables CloudWatch Logs to automatically extract embedded metric values from structured log events. It simplifies real-time monitoring by reducing complexity and cost for applications needing custom metrics and structured logging. For more information please visit the following link:\n\u003ca href=\"https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format_Specification.html\" target=\"_blank\"\u003eAWS Documentation on EMF Formatting\u003c/a\u003e\n\n\n\n## Instructions\n**Prerequisites:**\nYour chosen Integrated Development Environment (i.e. VS Code) must already be connected to AWS Lambda. For more guidance on setting up AWS Lambda we recommend following this helpful tutorial from AWS: \u003ca href=\"https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-getting-started-hello-world.html\" target=\"_blank\"\u003eDeploy Hello World Application with AWS SAM\u003c/a\u003e\n\n**Installation:**\n1. Install our package using the command `npm install cat-a-logs` then import the functions into your js file that connects to AWS Lambda `import { deployCatalog, catalog } from \"cat-a-logs/index.js\";` Check out Cat-A-Log on npm using the attached link:\n\u003ca href=\"https://www.npmjs.com/package/cat-a-logs?activeTab=readme\" target=\"_blank\"\u003eCat-A-Log\u003c/a\u003e\n\n2. Now enter your arguments into the catalog function! Let's go through each parameter one at a time and see what this looks like. First let's take a look at the function definition:\n\n      ```\n      function catalog(\n        trackedVariable: number | Array\u003cnumber\u003e,\n        metricName: string,\n        metricNamespace: string = \"CatALog-Default-Metrics\",\n        metricUnitLabel: string = \"None\",\n        CustomerDefinedDimension: { [key: string]: string } = {},\n        resolution: 1 | 60 = 60,\n        deploy: boolean = false)\n      ```\n\n    - **trackedVariable**: This variable represents the numerical value (or an Array containing a maximum of 100 numerical values) of the metric that will appear under the category \"Custom namespace\" in Cloudwatch Metrics. This is AWS Cloudwatch\u003eMetrics\u003eAll metrics\u003eCustom namespaces(ex. CatALog)\u003eDimensions(ex. Server, functionVersion)\n\n    \u003cp align=\"center\"\u003e\n    \u003cimg src=\"./snapshots/trackedVariable.png\" width=\"600\" /\u003e\n    \u003c/p\u003e\n\n\n    - **metricName**: This is a unique label of the tracked variable that will be reflected inside AWS Cloudwatch. Must be written as a `string`. \n      In the below image this corresponds to `Latency` --\u003e AWS Cloudwatch\u003eMetrics\u003eAll metrics\u003eCustom namespaces\n\n    \u003cp align=\"center\"\u003e\n    \u003cimg src=\"./snapshots/metricName.png\" width=\"600\"/\u003e\n    \u003c/p\u003e\n\n    - **metricNamespace**: This will be your \"Custom namespace\" in AWS Cloudwatch\u003eMetrics\u003eAll metrics\u003eCustom namespaces. In the below image this is represented by CatALog\n\n    \u003cp align=\"center\"\u003e\n    \u003cimg src=\"./snapshots/customNameSpace.png\" width=\"600\"/\u003e\n    \u003c/p\u003e\n\n    - **metricUnitLabel**: The explicit unit that Cloudwatch uses for EMF Configuration. Please note - must be one of the following as a `string`:\n      - Seconds | Microseconds | Milliseconds | Bytes | Kilobytes | Megabytes | Gigabytes | Terabytes | Bits | Kilobits | Megabits | Gigabits | Terabits | Percent | Count | Bytes/Second | Kilobytes/Second | Megabytes/Second | Gigabytes/Second | Terabytes/Second | Bits/Second | Kilobits/Second | Megabits/Second | Gigabits/Second | Terabits/Second | Count/Second | None\n\n      - To read more about Metric Datum see this \u003ca href=\"https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_MetricDatum.html\" target=\"_blank\"\u003elink\u003c/a\u003e\n    - **CustomerDefinedDimension**: This is an object - `{'functionVersion': '$LATEST', 'Server': 'Prod'}` functionVersion \u0026 Server is the dimension label/key - when you click on it see the value `$LATEST` and `Prod` is the value of the dimension\n\n        - The key will show up in AWS Cloudwatch as below:\n\n          \u003cp align=\"center\"\u003e\n          \u003cimg src=\"./snapshots/keyDefined.png\" width=\"600\"/\u003e\n          \u003c/p\u003e\n\n        - If the user clicks on the Server, functionVersion Dimension then you will see the value - in this example `$LATEST` \u0026 `Prod` reflected as below:\n\n          \u003cp align=\"center\"\u003e\n          \u003cimg src=\"./snapshots/metricName.png\" width=\"600\"/\u003e\n          \u003c/p\u003e\n\n\n    - **resolution**: This parameter can only be set to the numericalthe numerical val.uA of 1 OR 60 , theically set to  is setdefault value to 60. If you would like to learn more about High Resolution Metrics please follow the attached \u003ca href= \"https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/publishingMetrics.html#high-resolution-metrics\" target=\"_blank\"\u003elink\u003c/a\u003e\n    - **deploy**: Automatically set to false. The final catalog call you make has to switch deploy flag to true. Failure to do so will cause the cache to grow without bound and use up memory\n\n3. Start Building your Embedded Metric Formatted Logs. Call `catalog` as many times as needed. \n\u003c!-- You can also `console.log(cache)` at any time to see your EMF formatted logs being built in real time.  --\u003e\n\n\n4. ON the very last function call - it is important to change the deploy parameter to `true`. \n     - Alternative approach is to deploy your Lambda function with the `deployCatalog()` function call. This will automatically publish to CloudWatch without the need to use the entire arguments required in Cat-A-Log. Place `deployCatalog()` after you last catalog function call.\n\n5. Deploy your code with AWS SAM. This will place the file in AWS Lambda waiting for invocation. If you would like to learn more about deploying with SAM please follow the attached\n          \u003ca href= \"https://docs.aws.amazon.com/lambda/latest/dg/testing-functions.html\" target=\"_blank\"\u003elink\u003c/a\u003e\n6. Invoke your AWS Lambda Function\n\n7. See your metrics and structured in CloudWatch! \n \u003cp align=\"center\"\u003e\n          \u003cimg src=\"./snapshots/7.2.png\" width=\"600\"/\u003e\n          \u003c/p\u003e\n          \n## Open Source Contributions:\nWe are actively looking for contributors to our project! In order to get started we ask that you follow the below guidelines:\n\n  - Clone our Repository from GitHub \u003ca href=\"https://github.com/oslabs-beta/cat-a-log\" target=\"_blank\"\u003ehere\u003c/a\u003e \n  - Make a Feature Branch \n  - Make your contributions\n  - Push to your Feature Branch in GitHub\n  - Make a Pull Request to our Repository!\n\n\n| AWS MicroService Support                                                              | Status    |\n|---------------------------------------------------------------------------------------|-----------|\n| Lambda                                                                                 | ✅        |\n| EC2                                                                                   | ⏳        |\n\n\n\n|Feature                                                                                |Status     |\n|---------------------------------------------------------------------------------------|-----------|\n| TypeScript                                                                            | ✅        |\n| Embedded Metric Format Object Caching                                                 | ✅        |\n| Winston                                                                                | ⏳        |\n| Adding front end for Cat-A-Log                                                        | 🙏🏻        |\n\n\n- ✅ = Ready to use\n- ⏳ = In progress\n- 🙏🏻 = Looking for contributors\n\n## License Information:\nThis project is licensed under the MIT License -  see the [LICENSE](LICENSE) file for details\n\n\n## Contributor Information:\n \u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003cimg src=\"https://avatars.githubusercontent.com/u/161962009?v=4\" width=\"140px;\" alt=\"\"/\u003e\n      \u003cbr /\u003e\n      \u003csub\u003e\u003cb\u003eClara Regula\u003c/b\u003e\u003c/sub\u003e\n      \u003cbr /\u003e\n      \u003ca href=\"http://www.linkedin.com/in/clara-regula\"\u003e🖇️\u003c/a\u003e\n      \u003ca href=\"https://github.com/clararegula\"\u003e🐙\u003c/a\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003cimg src=\"https://avatars.githubusercontent.com/u/170294267?v=4\" width=\"140px;\" alt=\"\"/\u003e\n      \u003cbr /\u003e\n      \u003csub\u003e\u003cb\u003eBrian Anderson\u003c/b\u003e\u003c/sub\u003e\n      \u003cbr /\u003e\n      \u003ca href=\"https://www.linkedin.com/in/brian-anderson-24370630/\"\u003e🖇️\u003c/a\u003e\n      \u003ca href=\"https://github.com/brianmichaelanderson\"\u003e🐙\u003c/a\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003cimg src=\"https://avatars.githubusercontent.com/u/167483334?v=4\" width=\"140px;\" alt=\"\"/\u003e\n      \u003cbr /\u003e\n      \u003csub\u003e\u003cb\u003eHarris Awan\u003c/b\u003e\u003c/sub\u003e\n      \u003cbr /\u003e\n      \u003ca href=\"http://www.linkedin.com/in/harrawan123/\"\u003e🖇️\u003c/a\u003e\n      \u003ca href=\"https://github.com/HarrAwa\"\u003e🐙\u003c/a\u003e\n    \u003c/td\u003e\n     \u003ctd align=\"center\"\u003e\n      \u003cimg src=\"https://avatars.githubusercontent.com/u/106503739?v=4\" width=\"140px;\" alt=\"\"/\u003e\n      \u003cbr /\u003e\n      \u003csub\u003e\u003cb\u003eCurran Lee\u003c/b\u003e\u003c/sub\u003e\n      \u003cbr /\u003e\n      \u003ca href=\"https://www.linkedin.com/in/curranjlee/\"\u003e🖇️\u003c/a\u003e\n      \u003ca href=\"https://github.com/CJLee5\"\u003e🐙\u003c/a\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003cimg src=\"https://avatars.githubusercontent.com/u/142838412?v=4\" width=\"140px;\" alt=\"\"/\u003e\n      \u003cbr /\u003e\n      \u003csub\u003e\u003cb\u003eJacob Alexander\u003c/b\u003e\u003c/sub\u003e\n      \u003cbr /\u003e\n      \u003ca href=\"https://www.linkedin.com/in/jacoblanealexander/\"\u003e🖇️\u003c/a\u003e\n      \u003ca href=\"https://github.com/jacob-jpg1\"\u003e🐙\u003c/a\u003e\n    \u003c/td\u003e\n\u003c/table\u003e\n\n\n- 🖇️ = LinkedIn\n- 🐙 = Github","funding_links":["https://github.com/sponsors/open-source-labs","https://donorbox.org/donations-to-oslabs-inc"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foslabs-beta%2Fcat-a-log","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foslabs-beta%2Fcat-a-log","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foslabs-beta%2Fcat-a-log/lists"}