Create a wrapper library to tag span with API metadata

backend/base-backend-package/README.md

@@ -5,3 +5,14 @@ This package provides the base setup to build a new backend package at Buffer:
 - TypeScript
 - Jest
 - Package commands
+
+## How to use
+
+For now, simply copy-paste this folder, then manually edit the package.json:
+- name
+- version
+- description
+- homepage
+- keywords
+
+In the future, we should write a `npx` script instead of having to copy-paste.

backend/base-backend-package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bufferapp/base-backend-package",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "description": "A base package for writing new backend packages.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",

backend/bufftracer/.eslintrc.json

@@ -0,0 +1,37 @@
+{
+    "env": {
+        "browser": true,
+        "es6": true,
+        "jest": true
+    },
+    "extends": [
+        "standard",
+        "eslint:recommended",
+        "prettier",
+        "plugin:@typescript-eslint/recommended",
+        "plugin:prettier/recommended"  // Enables eslint-plugin-prettier and displays prettier errors as ESLint errors. Make sure this is always the last configuration in the extends array.
+    ],
+    "ignorePatterns": ["node_modules/*", "lib/*"],
+    "parser": "@typescript-eslint/parser",
+    "parserOptions": {
+        "ecmaVersion": 2018,
+        "sourceType": "module"
+    },
+    "plugins": [
+        "prettier",
+        "@typescript-eslint",
+        "jest"
+    ],
+    "rules": {
+        "@typescript-eslint/no-unused-vars": "error",
+        "@typescript-eslint/explicit-function-return-type": "error",
+        "@typescript-eslint/explicit-module-boundary-types": "error",
+        "jest/no-disabled-tests": "warn",
+        "jest/no-focused-tests": "error",
+        "jest/no-identical-title": "error",
+        "jest/prefer-to-have-length": "warn",
+        "jest/valid-expect": "error",
+        "no-underscore-dangle": "off"
+    }
+}
+

backend/bufftracer/.prettierrc.json

@@ -0,0 +1,7 @@
+{
+  "trailingComma": "all",
+  "tabWidth": 2,
+  "semi": false,
+  "singleQuote": true,
+  "bracketSpacing": true
+}

backend/bufftracer/README.md

@@ -0,0 +1,57 @@
+# BuffTracer
+
+A Datadog wrapper library to enable DD APM and tag API traces
+
+## Getting Started
+
+### Install npm package
+```shell
+npm install --save-exact @bufferapp/bufftracer
+```
+
+### Initialize tracer at the start of the service
+This should be the first import in your `index.ts`file.
+```typescript
+import '@bufferapp/bufftracer'
+```
+
+### Declare the following required env variables in the helm charts of each service
+```yaml
+  // core-api.yaml
+
+  - name: DD_ENABLE_TRACING
+    value: 'true'
+  - name: DD_SERVICE_NAME
+    value: 'core-api'
+  - name: DD_TRACE_AGENT_HOSTNAME
+    valueFrom:
+      fieldRef:
+        fieldPath: status.hostIP
+  - name: DD_TRACE_AGENT_PORT
+    value: '8126'
+  - name: NODE_ENV # or APP_STAGE
+    value: production
+```
+
+## What it does
+
+The library parses the incoming request, generates metadata, sets DD resource name to be the edge/endpoint and tags the DD span with the metadata.
+
+#### API metadata format
+
+```typescript
+type APIRequestMetadata = {
+  name: 'core-api' | string
+  type: 'graphql' | 'rpc' | 'rest'
+  client: 'buffertools-graphql-playground' | string
+  edge: string
+  fields: Array<string>
+  deprecatedFields: Array<string>
+  args: Array<string>
+}
+```
+
+#### Datadog APM tag
+![image](https://user-images.githubusercontent.com/727592/135768930-aee25005-4af3-49f9-b34a-bbcf0646f320.png)
+
+The DD APM tags are then used to generate DD custom metrics named `api.request`, which we can use to build dashboard and know who is consuming which parts of our API.

backend/bufftracer/jest.config.ts

@@ -0,0 +1,12 @@
+import type { Config } from '@jest/types'
+
+const config: Config.InitialOptions = {
+  verbose: true,
+  modulePathIgnorePatterns: ['node_modules/'],
+  preset: 'ts-jest',
+  setupFilesAfterEnv: ['./jest.env.ts'],
+  testEnvironment: 'node',
+  testMatch: ['**/*.test.ts'],
+}
+
+export default config

backend/bufftracer/jest.env.ts

@@ -0,0 +1,6 @@
+process.env.DD_SERVICE_NAME = 'foo-api'
+process.env.DD_TRACE_AGENT_HOSTNAME = 'localhost'
+process.env.DD_TRACE_AGENT_PORT = '80'
+process.env.DD_ENABLE_TRACING = 'true'
+process.env.APP_STAGE = 'test'
+process.env.NODE_ENV = 'test'