@commercetools/ts-sdk-apm 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# @commercetools/ts-sdk-apm
+
+## 1.0.0
+
+### Major Changes
+
+- [#458](https://github.com/commercetools/commercetools-sdk-typescript/pull/458) [`c2bf0a5`](https://github.com/commercetools/commercetools-sdk-typescript/commit/c2bf0a5cac18fdcf181dacc8c6714eb760704523) Thanks [@ajimae](https://github.com/ajimae)! - - add newrelic `APM` (application performance monitoring) to the sdk
+  - add `withTelemetryMiddleware()` middleware creator method to ClientBuilder class
+  - add basic `newrelic` application configuration module
+  - add examples to repository example folder to demonstrate how this feature can be used

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 commercetools
+
+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.

package/README.md

@@ -0,0 +1,75 @@
+# @commercetools/ts-sdk-apm
+
+_commercetools Typescript SDK Application Performance Monitoring._
+
+This package is used to monitor the application performance of the Typescript SDK. It exposes a middleware creator method that accepts some options for monitoring and tracing the SDK performance.
+
+## Installation
+
+To use this package we need to install the package and add the newrelic configuration file.
+
+Using npm
+
+```bash
+$ npm install @commercetools/ts-sdk-apm
+```
+
+or using yarn
+
+```bash
+$ yarn add @commercetools/ts-sdk-apm
+```
+
+## Usage
+
+Import the package and add it to the SDK client using `withTelemetryMiddleware()` method.
+
+```typescript
+// import the @commercetools/ts-sdk-apm package
+import { ClientBuilder } from '@commercetools/sdk-client-v2'
+import { createTelemetryMiddleware } from '@commercetools/ts-sdk-apm'
+
+// newrelic options
+const telemetryOptions = {
+  createTelemetryMiddleware
+}
+
+// create the client and include the telemetry middleware
+const client = new ClientBuilder()
+  .withClientCredentialsFlow(...)
+  .withHttpMiddleware(...)
+  .withTelemetryMiddleware(telemetryOptions) // telemetry middleware
+  ...
+  .build()
+...
+
+```
+
+## Using a custom (user-defined options)
+
+All the monitoring and tracing functionality has been implemented by default however, the `telemetryOptions` accepts three function parameters `createTelemetryMiddleware`, `apm` and `tracer`, the `createTelemetryMiddleware` and `tracer` can be custom implemented.
+
+```typescript
+type telemetryOptions = {
+  createTelemetryMiddleware: (options: Omit<telemetryOptions, 'createTelemetryMiddleware'>) => Middleware;
+  apm?: () => typeof require('newrelic');
+  tracer?: () => typeof require('/absolute-path-to-a-tracer(opentelemetry)-module')
+}
+```
+
+Example
+
+```typescript
+const telemetryOptions = {
+  createTelemetryMiddleware, // coming from the `@commercetools/ts-sdk-apm or a custom implementation
+  tracer: () =>
+    require(require('path').join(
+      __dirname,
+      '..',
+      '..',
+      'custom-telemetry-module.js'
+    )), // make sure the require takes in an absolute path to the custom tracer module.
+}
+```
+
+The tracer is responsible for tracing `http` calls right from the resource request call to the external commercetools backend service and everything that goes on in-between.

package/dist/commercetools-ts-sdk-apm.browser.cjs.js

@@ -0,0 +1,36 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+/**
+ * default newrelic APM and
+ * opentelemetry tracer modules
+ */
+const defaultOptions = {
+  apm: () => require('newrelic'),
+  tracer: () => require('../opentelemetry')
+};
+function createTelemetryMiddleware(options) {
+  // trace
+  function trace() {
+    // validate apm and tracer
+    if (!(options !== null && options !== void 0 && options.apm && typeof options.apm == 'function')) {
+      options.apm = defaultOptions.apm;
+    }
+    if (!(options !== null && options !== void 0 && options.tracer && typeof options.tracer == 'function')) {
+      options.tracer = defaultOptions.tracer;
+    }
+    options.apm();
+    options.tracer();
+  }
+  trace(); // expose tracing modules
+  return next => (request, response) => {
+    const nextRequest = {
+      ...request,
+      ...options
+    };
+    next(nextRequest, response);
+  };
+}
+
+exports.createTelemetryMiddleware = createTelemetryMiddleware;

package/dist/commercetools-ts-sdk-apm.browser.esm.js

@@ -0,0 +1,32 @@
+/**
+ * default newrelic APM and
+ * opentelemetry tracer modules
+ */
+const defaultOptions = {
+  apm: () => require('newrelic'),
+  tracer: () => require('../opentelemetry')
+};
+function createTelemetryMiddleware(options) {
+  // trace
+  function trace() {
+    // validate apm and tracer
+    if (!(options !== null && options !== void 0 && options.apm && typeof options.apm == 'function')) {
+      options.apm = defaultOptions.apm;
+    }
+    if (!(options !== null && options !== void 0 && options.tracer && typeof options.tracer == 'function')) {
+      options.tracer = defaultOptions.tracer;
+    }
+    options.apm();
+    options.tracer();
+  }
+  trace(); // expose tracing modules
+  return next => (request, response) => {
+    const nextRequest = {
+      ...request,
+      ...options
+    };
+    next(nextRequest, response);
+  };
+}
+
+export { createTelemetryMiddleware };

package/dist/commercetools-ts-sdk-apm.cjs.d.ts

@@ -0,0 +1 @@
+export * from "./declarations/src/index";

package/dist/commercetools-ts-sdk-apm.cjs.dev.js

@@ -0,0 +1,36 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+/**
+ * default newrelic APM and
+ * opentelemetry tracer modules
+ */
+const defaultOptions = {
+  apm: () => require('newrelic'),
+  tracer: () => require('../opentelemetry')
+};
+function createTelemetryMiddleware(options) {
+  // trace
+  function trace() {
+    // validate apm and tracer
+    if (!(options !== null && options !== void 0 && options.apm && typeof options.apm == 'function')) {
+      options.apm = defaultOptions.apm;
+    }
+    if (!(options !== null && options !== void 0 && options.tracer && typeof options.tracer == 'function')) {
+      options.tracer = defaultOptions.tracer;
+    }
+    options.apm();
+    options.tracer();
+  }
+  trace(); // expose tracing modules
+  return next => (request, response) => {
+    const nextRequest = {
+      ...request,
+      ...options
+    };
+    next(nextRequest, response);
+  };
+}
+
+exports.createTelemetryMiddleware = createTelemetryMiddleware;

package/dist/commercetools-ts-sdk-apm.cjs.js

@@ -0,0 +1,7 @@
+'use strict';
+
+if (process.env.NODE_ENV === "production") {
+  module.exports = require("./commercetools-ts-sdk-apm.cjs.prod.js");
+} else {
+  module.exports = require("./commercetools-ts-sdk-apm.cjs.dev.js");
+}

package/dist/commercetools-ts-sdk-apm.cjs.prod.js

@@ -0,0 +1,36 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+/**
+ * default newrelic APM and
+ * opentelemetry tracer modules
+ */
+const defaultOptions = {
+  apm: () => require('newrelic'),
+  tracer: () => require('../opentelemetry')
+};
+function createTelemetryMiddleware(options) {
+  // trace
+  function trace() {
+    // validate apm and tracer
+    if (!(options !== null && options !== void 0 && options.apm && typeof options.apm == 'function')) {
+      options.apm = defaultOptions.apm;
+    }
+    if (!(options !== null && options !== void 0 && options.tracer && typeof options.tracer == 'function')) {
+      options.tracer = defaultOptions.tracer;
+    }
+    options.apm();
+    options.tracer();
+  }
+  trace(); // expose tracing modules
+  return next => (request, response) => {
+    const nextRequest = {
+      ...request,
+      ...options
+    };
+    next(nextRequest, response);
+  };
+}
+
+exports.createTelemetryMiddleware = createTelemetryMiddleware;

package/dist/commercetools-ts-sdk-apm.esm.js

@@ -0,0 +1,32 @@
+/**
+ * default newrelic APM and
+ * opentelemetry tracer modules
+ */
+const defaultOptions = {
+  apm: () => require('newrelic'),
+  tracer: () => require('../opentelemetry')
+};
+function createTelemetryMiddleware(options) {
+  // trace
+  function trace() {
+    // validate apm and tracer
+    if (!(options !== null && options !== void 0 && options.apm && typeof options.apm == 'function')) {
+      options.apm = defaultOptions.apm;
+    }
+    if (!(options !== null && options !== void 0 && options.tracer && typeof options.tracer == 'function')) {
+      options.tracer = defaultOptions.tracer;
+    }
+    options.apm();
+    options.tracer();
+  }
+  trace(); // expose tracing modules
+  return next => (request, response) => {
+    const nextRequest = {
+      ...request,
+      ...options
+    };
+    next(nextRequest, response);
+  };
+}
+
+export { createTelemetryMiddleware };

package/dist/declarations/src/apm.d.ts

@@ -0,0 +1,2 @@
+import type { Middleware, OTelemetryMiddlewareOptions } from '../types/types';
+export default function createTelemetryMiddleware(options: OTelemetryMiddlewareOptions): Middleware;

package/dist/declarations/src/index.d.ts

@@ -0,0 +1,2 @@
+export { default as createTelemetryMiddleware } from './apm';
+export * from '../types/types.d';

package/dist/declarations/types/types.d.ts

@@ -0,0 +1,103 @@
+export type JsonObject<T = unknown> = { [key: string]: T }
+export type MiddlewareRequest = ClientRequest
+export type Middleware = (next: Dispatch) => Dispatch
+
+export type Dispatch = (
+  request: MiddlewareRequest,
+  response: MiddlewareResponse
+) => unknown
+
+export type Next = (
+  request: MiddlewareRequest,
+  response: MiddlewareResponse
+) => unknown
+
+export type MiddlewareResponse = {
+  resolve(response: JsonObject): void
+  reject(error: JsonObject): void
+  body?: JsonObject
+  error?: HttpErrorType
+  statusCode: number
+  headers?: JsonObject<string>
+  request?: JsonObject
+}
+
+export interface ClientRequest {
+  baseUri?: string
+  uri?: string
+  headers?: VariableMap
+  method: MethodType
+  uriTemplate?: string
+  pathVariables?: VariableMap
+  queryParams?: VariableMap
+  body?: any,
+}
+
+export type HttpErrorType = {
+  name: string
+  message: string
+  code: number
+  status: number
+  statusCode: number
+  originalRequest: ClientRequest
+  body?: JsonObject
+  retryCount?: number
+  headers?: JsonObject<string>
+}
+
+export type VariableMap = {
+  [key: string]: QueryParam
+}
+
+export type QueryParam =
+  | string
+  | string[]
+  | number
+  | number[]
+  | boolean
+  | boolean[]
+  | undefined
+
+export type MethodType =
+  | 'ACL'
+  | 'BIND'
+  | 'CHECKOUT'
+  | 'CONNECT'
+  | 'COPY'
+  | 'DELETE'
+  | 'GET'
+  | 'HEAD'
+  | 'LINK'
+  | 'LOCK'
+  | 'M-SEARCH'
+  | 'MERGE'
+  | 'MKACTIVITY'
+  | 'MKCALENDAR'
+  | 'MKCOL'
+  | 'MOVE'
+  | 'NOTIFY'
+  | 'OPTIONS'
+  | 'PATCH'
+  | 'POST'
+  | 'PROPFIND'
+  | 'PROPPATCH'
+  | 'PURGE'
+  | 'PUT'
+  | 'REBIND'
+  | 'REPORT'
+  | 'SEARCH'
+  | 'SOURCE'
+  | 'SUBSCRIBE'
+  | 'TRACE'
+  | 'UNBIND'
+  | 'UNLINK'
+  | 'UNLOCK'
+  | 'UNSUBSCRIBE'
+
+export type TelemetryMiddlewareOptions = {
+  apm?: Function,
+  tracer?: Function,
+  createTelemetryMiddleware: (options?: OTelemetryMiddlewareOptions) => Middleware
+}
+
+export type OTelemetryMiddlewareOptions = Omit<TelemetryMiddlewareOptions, 'createTelemetryMiddleware'>

package/opentelemetry.js

@@ -0,0 +1,90 @@
+'use strict'
+require('dotenv').config()
+
+const process = require('process')
+const { v4: uuidv4 } = require('uuid')
+const opentelemetry = require('@opentelemetry/sdk-node')
+const {
+  getNodeAutoInstrumentations,
+} = require('@opentelemetry/auto-instrumentations-node')
+const { Resource } = require('@opentelemetry/resources')
+const {
+  SemanticResourceAttributes,
+} = require('@opentelemetry/semantic-conventions')
+const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http')
+const {
+  OTLPMetricExporter,
+} = require('@opentelemetry/exporter-metrics-otlp-http')
+const {
+  AggregationTemporality,
+  PeriodicExportingMetricReader,
+} = require('@opentelemetry/sdk-metrics')
+const api = require('@opentelemetry/api')
+
+// enable logging ONLY for developement
+// this is useful for debugging instrumentation issues
+// remove from production after issues (if any) are resolved
+// view more logging levels here: https://github.com/open-telemetry/opentelemetry-js-api/blob/main/src/diag/types.ts#L67
+
+if (process.env.NODE_ENV == 'development') {
+  api.diag.setLogger(
+    new api.DiagConsoleLogger(),
+    api.DiagLogLevel.INFO,
+    api.DiagLogLevel.ERROR
+  )
+}
+
+// Declare the resource to be used.
+//    A resource represents a collection of attributes describing the
+//    service. This collection of attributes will be associated with all
+//    telemetry generated from this service (traces, metrics, logs).
+const resource = new Resource({
+  [SemanticResourceAttributes.SERVICE_INSTANCE_ID]: uuidv4(),
+  [SemanticResourceAttributes.SERVICE_NAME]: process.env['NEW_RELIC_APP_NAME'],
+})
+
+// Enable auto-instrumentation from the meta package.
+const instrumentations = [getNodeAutoInstrumentations()]
+
+// Configure the OTLP/HTTP exporters.
+//    The following assumes you've set the OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_EXPORTER_OLTP_HEADERS
+//    environment variables.
+const traceExporter = new OTLPTraceExporter()
+const metricExporter = new OTLPMetricExporter({
+  temporalityPreference: AggregationTemporality.DELTA,
+})
+
+// If you haven't set the OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_EXPORTER_OLTP_HEADERS
+// environment variables, you can configure the OTLP exporter programmatically by
+// uncommenting the following code:
+
+// this endpoint contains a path since this exporter is signal specific (traces)
+// see more details here: https://docs.newrelic.com/docs/more-integrations/open-source-telemetry-integrations/opentelemetry/opentelemetry-quick-start/#note-endpoints
+// const url = "https://otlp.nr-data.net:4317/v1/traces";
+
+// Configure PeriodicMetricReader
+const metricReader = new PeriodicExportingMetricReader({
+  exporter: metricExporter,
+  exportIntervalMillis: 5000,
+})
+
+// Configure the OpenTelemetry NodeSDK
+const sdk = new opentelemetry.NodeSDK({
+  resource,
+  traceExporter,
+  metricReader,
+  instrumentations,
+})
+
+// Initialize the SDK and register with the OpenTelemetry API:
+//    this enables the API to record telemetry
+sdk.start()
+
+// Gracefully shut down the SDK on process exit
+process.on('SIGTERM', () => {
+  sdk
+    .shutdown()
+    .then(() => console.log('OpenTelemetry terminated'))
+    .catch((error) => console.log('Error terminating OpenTelemetry', error))
+    .finally(() => process.exit(0))
+})

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@commercetools/ts-sdk-apm",
+  "version": "1.0.0",
+  "description": "commercetools typescript SDK application performance monitoring.",
+  "main": "dist/commercetools-ts-sdk-apm.cjs.js",
+  "module": "dist/commercetools-ts-sdk-apm.esm.js",
+  "author": "Chukwuemeka Ajima <meeky.ae@gmail.com>",
+  "license": "MIT",
+  "private": false,
+  "dependencies": {
+    "@opentelemetry/api": "^1.4.1",
+    "@opentelemetry/auto-instrumentations-node": "^0.36.6",
+    "@opentelemetry/exporter-metrics-otlp-http": "^0.38.0",
+    "@opentelemetry/sdk-node": "^0.38.0",
+    "newrelic": "^9.15.0",
+    "uuid": "9.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=14"
+  },
+  "keywords": [
+    "commercetools",
+    "composable commerce",
+    "typescript",
+    "sdk",
+    "apm",
+    "telemetry",
+    "opentelemetry",
+    "tracing"
+  ],
+  "homepage": "https://github.com/commercetools/commercetools-typescript-sdks",
+  "bugs": "https://github.com/commercetools/commercetools-typescript-sdks/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/commercetools/commercetools-typescript-sdks.git"
+  },
+  "files": ["dist", "CHANGELOG.md", "opentelemetry.js"],
+  "browser": {
+    "./dist/commercetools-ts-sdk-apm.cjs.js": "./dist/commercetools-ts-sdk-apm.browser.cjs.js",
+    "./dist/commercetools-ts-sdk-apm.esm.js": "./dist/commercetools-ts-sdk-apm.browser.esm.js"
+  },
+  "scripts": {
+    "organize_imports": "find src -type f -name '*.ts' | xargs organize-imports-cli",
+    "postbuild": "yarn organize_imports",
+    "post_process_generate": "yarn organize_imports"
+  }
+}