Initial commit

.eslintignore

@@ -0,0 +1,2 @@
+node_modules
+dist

.eslintrc

@@ -0,0 +1,32 @@
+{
+  "root": true,
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "project": "./tsconfig.json"
+  },
+  "plugins": ["@typescript-eslint", "prettier"],
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/eslint-recommended",
+    "plugin:@typescript-eslint/recommended",
+    "prettier"
+  ],
+  "env": {
+    "jest": true
+  },
+  "rules": {
+    "no-console": 1, // Means warning
+    "prettier/prettier": 2, // Means error
+    "@typescript-eslint/ban-ts-comment": "off",
+    "@typescript-eslint/no-floating-promises": ["error"],
+    "@typescript-eslint/no-misused-promises": ["error"],
+    "@typescript-eslint/promise-function-async": ["error"],
+    "@typescript-eslint/require-await": ["error"],
+    // note you must disable the base rule as it can report incorrect errors
+    "no-return-await": "off",
+    "@typescript-eslint/return-await": ["error"],
+    // Don't allow awaiting non-Promises
+    "@typescript-eslint/await-thenable": "error"
+  },
+  "ignorePatterns": ["dist", "cdk.out"]
+}

.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: Build - CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+
+      - name: Use Node.js 16
+        uses: actions/setup-node@v3
+        with:
+          node-version: 16
+
+      - name: Install Modules
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Build Docs
+        run: npm run build:docs
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Test
+        run: npm run test

.github/workflows/docs.yml

@@ -0,0 +1,31 @@
+name: Publish Docs
+
+on:
+  release:
+    types: [published]
+
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+
+      - name: Use Node.js 16
+        uses: actions/setup-node@v3
+        with:
+          node-version: 16
+
+      - name: Install Modules
+        run: npm ci
+
+      - name: Build Docs
+        run: npm run build:docs
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs

.github/workflows/publish.yml

@@ -0,0 +1,40 @@
+name: Package and Publish
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+
+      - name: Use Node.js 16
+        uses: actions/setup-node@v3
+        with:
+          node-version: 16
+
+      - name: Use the Release Tag Version
+        run: |
+          npm version from-git --allow-same-version --no-git-tag-version
+
+      - name: Install Modules
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Test
+        run: npm run test
+
+      - name: NPM registry authentication
+        run: npm set //registry.npmjs.org/:_authToken ${{ secrets.NPMJSORG_PUBLISH_TOKEN }}
+
+      - name: Publish with CLI to Code Artifact
+        run: |
+          npm publish --access public --ignore-scripts

.gitignore

@@ -0,0 +1,8 @@
+.idea/
+node_modules
+dist/
+*.tsbuildinfo
+*.log
+.nyc_output/
+coverage/
+.DS_Store

.nvmrc

@@ -0,0 +1 @@
+v16.17.1

.prettierrc

@@ -0,0 +1,6 @@
+{
+  "semi": true,
+  "trailingComma": "all",
+  "singleQuote": true,
+  "printWidth": 100
+}

.vscode/settings.json

@@ -0,0 +1,50 @@
+{
+  "files.exclude": {
+    // "**/node_modules/*": true,
+    // "cdk.out": true
+    // "node_modules": true,
+    // "**/node_modules": true
+  },
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "editor.formatOnSave": true,
+  "editor.insertSpaces": true,
+  "editor.tabSize": 2,
+  "files.associations": {
+    "Dockerfile*": "dockerfile"
+  },
+  "[typescript]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "yaml.customTags": [
+    "!And",
+    "!And sequence",
+    "!If",
+    "!If sequence",
+    "!Not",
+    "!Not sequence",
+    "!Equals",
+    "!Equals sequence",
+    "!Or",
+    "!Or sequence",
+    "!FindInMap",
+    "!FindInMap sequence",
+    "!Base64",
+    "!Join",
+    "!Join sequence",
+    "!Cidr",
+    "!Ref",
+    "!Sub",
+    "!Sub sequence",
+    "!GetAtt",
+    "!GetAZs",
+    "!ImportValue",
+    "!ImportValue sequence",
+    "!Select",
+    "!Select sequence",
+    "!Split",
+    "!Split sequence"
+  ],
+  "[xml]": {
+    "editor.defaultFormatter": "DotJoshJohnson.xml"
+  }
+}

CODE_OF_CONDUCT.md

@@ -0,0 +1,5 @@
+# Contributor Code of Conduct
+
+The Shutterstock team is committed to fostering a welcoming community.
+
+This project is governed by Shutterstock’s [Code of Conduct](https://github.com/shutterstock/code-of-conduct). All contributors and participants agree to abide by its terms.

ISSUE_TEMPLATE.md

@@ -0,0 +1,8 @@
+### Expected behavior
+
+### Actual behavior
+
+### Steps to reproduce the behavior
+
+### Additional specs (e.g. browser, version, etc.)
+

LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+=====================
+Copyright (c) `2022` `Shutterstock, Inc.`
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,64 @@
+[![npm (scoped)](https://img.shields.io/npm/v/%40shutterstock/aws-embedded-metrics-flatten)](https://www.npmjs.com/package/@shutterstock/aws-embedded-metrics-flatten) [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT) [![API Docs](https://img.shields.io/badge/API%20Docs-View%20Here-blue)](https://tech.shutterstock.com/aws-embedded-metrics-flatten/) [![Build - CI](https://github.com/shutterstock/aws-embedded-metrics-flatten/actions/workflows/ci.yml/badge.svg)](https://github.com/shutterstock/aws-embedded-metrics-flatten/actions/workflows/ci.yml) [![Package and Publish](https://github.com/shutterstock/aws-embedded-metrics-flatten/actions/workflows/publish.yml/badge.svg)](https://github.com/shutterstock/aws-embedded-metrics-flatten/actions/workflows/publish.yml) [![Publish Docs](https://github.com/shutterstock/aws-embedded-metrics-flatten/actions/workflows/docs.yml/badge.svg)](https://github.com/shutterstock/aws-embedded-metrics-flatten/actions/workflows/docs.yml)
+
+# Overview
+
+Extensions for the [aws-embedded-metrics](https://www.npmjs.com/package/aws-embedded-metrics) npm module, adding flatcount metrics that emit a total count instead of an array of each individual count, and the ability to disable metrics without removing metrics method calls.
+
+## Installation
+
+The package is available on npm as [@shutterstock/aws-embedded-metrics-flatten](https://www.npmjs.com/package/@shutterstock/aws-embedded-metrics-flatten)
+
+`npm i @shutterstock/aws-embedded-metrics-flatten`
+
+## Importing
+
+```typescript
+import { FlatCountMetrics, metricScopeDummy } from '@shutterstock/aws-embedded-metrics-flatten';
+```
+
+# Features
+
+- Flattens count metrics into a single emitted line
+  - This works around the max length limitation of CloudWatch Embedded Metrics log messages
+  - Rather than emitting an array, such as `[1, 1, 1, 1, 1]`, it emits a single count of `[5]`, dramatically reducing the size of the log message when counting thousands of iterations in a Lambda function
+- Gives the ability to disable the metrics without having to protect each metric emit with a conditional
+
+# Flattening Count Metrics
+
+CloudWatch embedded metrics (parsed from CloudWatch logs) have a limit of something like 1,000 items in a metrics log statement. Metrics beyond that point will be ignored.
+
+`aws-embedded-metrics` will emit metrics with `10,000` calls to `.putMetric('MyMetric', 1, metricUnit.Count);` as an array with 10,000 elements all with the value of `1`... and about `9,000` of those will get ignored as a result.
+
+# Optional Metrics
+
+`metricScopeDummy` is a replacement for `metricScope` that will pass an `MetricsLoggerDummy` instance instead of a `MetricsLogger` instance to the callback function. `MetricsLoggerDummy` implements the same interface as `MetricsLogger` but it does not accumulate data and does not emit any logs.
+
+Coupled with a configuration setting / env var it is possible to emit metrics or not emit metrics by changing which function is used to create the `metrics` object.
+
+# Contributing
+
+## Setting up Build Environment
+
+- `nvm use`
+- `npm i`
+- `npm run build`
+- `npm run lint`
+- `npm run test`
+
+## Running Examples
+
+### metrics-flatten
+
+1. `npm run example:metrics-flatten`
+   1. Will print 2 lines of metrics
+   2. `MyFlatMetric` will have a single value of `10000`
+2. `FLATTEN_METRICS=false npm run example:metrics-flatten`
+   1. Will print many lines of metrics
+   2. `MyFlatMetric` will have 10,000 values of `1` across many different lines
+
+### metrics-optional
+
+1. `npm run example:metrics-optional`
+   1. Metrics will print
+2. `EMIT_METRICS=false npm run example:metrics-optional`
+   1. Metrics will not print

examples/metrics-flatten.ts

@@ -0,0 +1,63 @@
+import type * as lambda from 'aws-lambda';
+import { metricScope, Unit as metricUnit } from 'aws-embedded-metrics';
+import { FlatCountMetrics } from '@shutterstock/aws-embedded-metrics-flatten';
+
+const { FLATTEN_METRICS = 'true' } = process.env;
+const config = {
+  flattenMetrics: FLATTEN_METRICS === 'true',
+};
+
+export const handler = metricScope(
+  (metrics) =>
+    async (payload: lambda.MSKEvent, context?: lambda.Context): Promise<void> => {
+      const flatMetrics = new FlatCountMetrics();
+
+      metrics.putMetric('SomeCriticalMetric', 1, metricUnit.Count);
+
+      // Write this metric right away so we see it even if we crash later
+      await metrics.flush();
+
+      try {
+        for (let i = 0; i < 10000; i++) {
+          // Do some work
+
+          if (config.flattenMetrics) {
+            flatMetrics.putMetric('MyFlatMetric', 1, metricUnit.Count);
+          } else {
+            metrics.putMetric('MyFlatMetric', 1, metricUnit.Count);
+          }
+        }
+      } finally {
+        // Flush the flattened metrics
+        // This will result in a single `MyFlatMetric` item with a count of 10,000 in
+        // embedded metrics output instead of a 10,000 element array of 1's
+        flatMetrics.flush(metrics);
+      }
+    },
+);
+
+// Allow this code to be copy/pasted into a Lambda function
+// Only call the handler if we're being invoked on a TTY
+if (process.stdout.isTTY) {
+  void handler({
+    records: {
+      'some-topic': [
+        {
+          topic: 'some-topic',
+          partition: 0,
+          offset: 0,
+          timestamp: 1234567890,
+          timestampType: 'CREATE_TIME',
+          headers: [],
+          key: 'key',
+          value: 'some-value',
+        },
+      ],
+    },
+    eventSource: 'aws:kafka',
+    eventSourceArn:
+      'arn:aws:kafka:us-east-1:123456789012:cluster/my-cluster/12345678-1234-1234-1234-123456789012-1',
+    bootstrapServers:
+      'b-1.my-cluster.1234.abcd.us-east-1.amazonaws.com:9092,b-2.my-cluster.1234.abcd.us-east-1.amazonaws.com:9092',
+  });
+}