Remove global version tag and CloudWatch client (#310)

BREAKING CHANGE: The following clients have breaking changes:

- CloudWatch client has been removed. It was deprecated in [v4.2.0](https://github.com/seek-oss/datadog-custom-metrics/releases/tag/v4.2.0) (March 2023) and there is very limited usage remaining at SEEK. Migrate to the Lambda Extension client.
- StatsD client no longer attaches the global `version` tag to custom metrics, and `env` is now optional. These tags are automatically applied via telemetry agents in SEEK's typical container workload hosting environments.

  | Environment | `env` | `version`
  | :-- | :-- | :--
  | Automat | Automat environment name (`development` \| `production`) | `{deployment}-{version}`, e.g. `myDeploymentName-abcdefa.123`
  | Gantry | Gantry environment name | `VERSION` environment variable, e.g. `abcdefa.123`

  Some Gantry services may have a Gantry environment name like `prod-1` and then supply a different value like `createStatsDClient({ environment: 'production' })` in code. This behaviour has been retained. It results in metrics that are tagged with both `env:prod-1` and `env:production`, and may be useful for forward compatibility with Automat's `development` | `production`.

Author: 72636c

README.md

@@ -14,26 +14,34 @@ yarn add seek-datadog-custom-metrics
 
 ## Tagging convention
 
-All custom metrics are prefixed by `AppConfig.name`.
-Two global tags are also added to every custom metric:
+All custom metrics are prefixed by `{config.name}.`.
+
+One global tag may be optionally added to every custom metric:
 
 - `AppConfig.environment` becomes `env:${value}`
-- `AppConfig.version` becomes `version:${value}`
 
-These tags are consistent with tags sent by [Gantry](https://github.com/SEEK-Jobs/gantry) via Datadog's AWS integration.
+  This behaviour has been retained for compatibility.
+  Review whether you can rely on the `env` set by your Datadog agent;
+  this will be the Automat or Gantry environment name at SEEK.
+
+  In some scenarios, you may still want to manually set a different environment.
+  Some Gantry services may have a Gantry environment name like `prod-1` and then supply a different value like `production` here.
+  This behaviour has been retained.
+  It results in metrics that are tagged with both `env:prod-1` and `env:production`,
+  and may be useful for forward compatibility with Automat's `development` | `production`.
 
 ## API reference
 
 ### `createStatsDClient`
 
-`createStatsDClient` creates a [hot-shots](https://github.com/brightcove/hot-shots) client configured with our [tagging convention](#tagging-convention).
+`createStatsDClient` creates a [hot-shots](https://github.com/brightcove/hot-shots) client.
 This is intended for containerized services, particularly those deployed with [Gantry](https://github.com/SEEK-Jobs/gantry).
 
 ```typescript
 import { StatsD } from 'hot-shots';
 import { createStatsDClient } from 'seek-datadog-custom-metrics';
 
-// Expects `name`, `version`, `environment` and `metricsServer` properties
+// Expects `name` and `metricsServer` properties
 import config from '../config';
 
 // This example assumes Bunyan/pino

src/AppConfig.ts

@@ -3,25 +3,26 @@
  */
 export interface AppConfig {
   /**
-   * Name of the application
+   * Environment of the application
    *
-   * This is used to prefix custom metric names. It will typically be the name
-   * of the app's GitHub repository.
-   */
-  name: string;
-
-  /**
-   * Version of the application
+   * @deprecated Review whether you can rely on the `env` set by your Datadog
+   * agent; this will be the Automat or Gantry environment name at SEEK.
    *
-   * This is used to tag custom metrics. It will typically include a CI build
-   * number and/or a commit hash.
+   * In some scenarios, you may still want to manually set a different
+   * environment here. Some Gantry services may have a Gantry environment name
+   * like `prod-1` and then supply a different value like `production` here.
+   * This behaviour has been retained. It results in metrics that are tagged
+   * with both `env:prod-1` and `env:production`, and may be useful for forward
+   * compatibility with Automat's `development` | `production`.
    */
-  version?: string | null | undefined;
+  environment?: string;
 
   /**
-   * Environment of the application
+   * Name of the application
    *
-   * This is used to tag custom metrics. Typical examples are `prod` and `dev`.
+   * This is used to prefix custom metric names. It should typically be the name
+   * of the component that is being instrumented and match the Datadog `service`
+   * tag and/or `DD_SERVICE` environment variable.
    */
-  environment: string;
+  name: string;
 }

src/MetricsClient.ts

@@ -1,9 +1,9 @@
 /**
  * Abstract interface for recording metrics
  *
- * This was intended to cover both the StatsD and CloudWatch clients. As the
- * CloudWatch client type is now deprecated, consumers can use the richer
- * `StatsD` type from `hot-shots` instead.
+ * @deprecated This was initially intended to cover both the StatsD and
+ * CloudWatch clients. As the CloudWatch client is now removed, consumers can
+ * use the richer `StatsD` type from `hot-shots` instead.
  */
 export interface MetricsClient {
   /**

src/createCloudWatchClient.test.ts

@@ -7,8 +7,7 @@ describe('createStatsDClient', () => {
     expect(
       createStatsDClient(StatsD, {
         name: 'test',
-        environment: 'jest',
-        version: '0',
+        environment: 'deprecated-but-still-here',
       }),
     ).toBeInstanceOf(Object);
   });
@@ -17,9 +16,6 @@ describe('createStatsDClient', () => {
     expect(
       createStatsDClient(StatsD, {
         name: 'test',
-        environment: 'jest',
-        version: null,
-
         metricsServer: null,
       }),
     ).toBeInstanceOf(Object);

src/createCloudWatchClient.ts

@@ -5,8 +5,6 @@ import { createTimedSpan } from './createTimedSpan';
 
 const metricsClient = createStatsDClient(StatsD, {
   name: 'jest',
-  version: '0.0.1',
-  environment: 'dev',
 });
 
 const timedSpan = createTimedSpan(metricsClient);

src/createStatsDClient.test.ts

@@ -1,15 +1,13 @@
 import { globalTags } from './globalTags';
 
 describe('globalTags', () => {
-  it('should generate `env` and `version` tags', () => {
-    expect(
-      globalTags({ name: 'unused', environment: 'prod', version: '1234' }),
-    ).toEqual(['env:prod', 'version:1234']);
+  it('should generate `env` tag when environment is supplied', () => {
+    expect(globalTags({ name: 'unused', environment: 'prod' })).toStrictEqual([
+      'env:prod',
+    ]);
   });
 
-  it("should generate only `env` when `version` isn't specified", () => {
-    expect(globalTags({ name: 'unused', environment: 'dev' })).toEqual([
-      'env:dev',
-    ]);
+  it('should generate no tags when environment is not specified', () => {
+    expect(globalTags({ name: 'unused' })).toStrictEqual([]);
   });
 });

src/createTimedSpan.test.ts

@@ -1,7 +1,7 @@
 import type { AppConfig } from './AppConfig';
 
 export const globalTags = (config: AppConfig): string[] => {
-  const { environment, version } = config;
+  const { environment } = config;
 
-  return [`env:${environment}`, ...(version ? [`version:${version}`] : [])];
+  return environment ? [`env:${environment}`] : [];
 };

src/globalTags.test.ts

@@ -1,5 +1,4 @@
 import {
-  createCloudWatchClient,
   createLambdaExtensionClient,
   createNoOpClient,
   createStatsDClient,
@@ -12,10 +11,6 @@ describe('index', () => {
     expect(createStatsDClient).toBeInstanceOf(Function);
   });
 
-  it('should export a createCloudWatchClient function', () => {
-    expect(createCloudWatchClient).toBeInstanceOf(Function);
-  });
-
   it('should export a createLambdaExtensionClient function', () => {
     expect(createLambdaExtensionClient).toBeInstanceOf(Function);
   });