@edirect/trace 10.0.0 → 11.0.25

package/dist/README.md

@@ -0,0 +1,381 @@
+# Open Telemetry Trace
+
+## Background
+
+Based on application logs and a sales checker service that triggers alerts on a slack channel, the current solution offers some insight into the application but falls short when it comes to deep understanding of exceptions and the general business flow.
+
+Due to the sheer amount of logs and complex integrations between the application microservices, it is not uncommon to find scenarios where the development team can spend hours tracing the problem back to its origin.
+
+- Non-standard logs
+  - The log format and content depends on implementation and log uniformity is a challenge by itself.
+- Logs might be outdated or absent
+  - As services shift, evolve and so should logs. This can be a source for inconsistencies as logs may not be updated or can be wrongly removed during the feature implementation.
+- Logs are difficult to query and trace
+  - Even with the help of tools such Elasticsearch, querying and tracing logs can be a difficult task due to complex interactions among different services in the application.
+  - As an example, an error response from quote-engine but we only dispose of the policy number to find the root cause. The data provided is not enough for a complete investigation, which may lead to long research.
+- Not able to trace all exception occurrences
+  - In the case shown by the previous item the error was not logged or at least not easily accessible.
+  - Sales triggers are not flexible
+  - Triggers are configured as code in the sales checker service. Any change to the logic must be implemented, tested and deployed.
+  - Sales alert do not provide insight into root causes
+  - The alert contains only the basic information necessary for an investigation to start. It contains the lead, partner, vertical and a brief description of the problem.
+- Limited business process visibility
+  - As the alerts are based on sale statuses, we have limited insight into the process. With such a limited view we cannot verify which steps represent bottlenecks or are more prone to errors. Useful information for maintaining and improving the system.
+- No concise view of the business flow
+  - Currently there are no dashboards or easily accessible views that can provide correlated information about the many steps that compose the Bolttech business flow.
+
+## Detailed Design
+
+To fill the gaps that the current approach, the proposed solution must fulfill some requirements:
+
+- Requires minimal code and service changes
+- Must be flexible and configurable
+- Must capable of querying multiple data sources
+- Must be an evolutive tool that can help multiple types of users
+- Must have a dashboard that shows useful information about business flow
+
+Taking the requirements in consideration, the proposed solutions employs an application monitoring tool named Open Telemetry, a microservice responsible for correlating the data captured by the tool and a comprehensive dashboard for the final user.
+
+![image](./docs/architecture.png)
+
+## Usage
+
+- Tracing Apps
+  - Datadog
+- Services and Observability
+  - [Service Visibility Frontend](https://bitbucket.org/gofrank/service-visibility-frontend/src/main/)
+  - [Service Visibility Backend](https://bitbucket.org/gofrank/service-visibility-backend/src/main/)
+
+## Sample application
+
+- [Service Visibility Samples](https://bitbucket.org/gofrank/service-visibility-samples/src/master/)
+  1. Expressjs Sample
+
+     https://bitbucket.org/gofrank/service-visibility-samples/src/master/samples/api/
+
+  2. Nest-app Sample
+
+     https://bitbucket.org/gofrank/service-visibility-samples/src/master/samples/quote-nestapp/
+
+## NestJS Applications
+
+NestJs applications **should be upgraded to version 9.**
+
+- Just the fact of upgrade the nest-app to version 9 will able the service to ship all logs to the service visibility
+
+  As we applied the `@edirect/trace` to the nest-app, we dont need to have the trace part of code on nest-app applications with nest-app version 9
+
+  In case of impossibility to upgrade, use the "Other" instructions using `@edirect/trace` directly
+
+  Integration Service was not able to upgrade because it uses a react-ssr that does not have compatibility with nestjs 9, so, even as a nestjs application, we implemented the "Other" way
+
+- [@edirect/nest-app:9](https://bitbucket.org/gofrank/nest-app/src/master/)
+  1. Upgrade nest-app, all edirect dependencies and all nestjs dependencies
+
+  2. We should initialize our application with `otel` as a requirement for node startup command:
+
+     ```bash
+         node --require ./node_modules/@edirect/trace/dist/otel.js dist/main
+     ```
+
+     (dist/main or your application entrypoint)
+
+  3. Remove the old client initialization as we moved it to the node require
+
+     If the service was using old trace version
+
+     ```js
+     const config = require('config');
+     const {
+       services: { APM },
+       middlewares: traceMiddlewares,
+     } = require('@edirect/trace');
+     const apmConfig = config.get('apm');
+
+     if (apmConfig.enabled) {
+       const apm = new APM(
+         apmConfig.service,
+         apmConfig.url,
+         apmConfig.traceServer,
+       );
+       apm.startTrace();
+     }
+     ```
+
+  4. Remove the middleware usage
+
+     If the service was using old trace version
+
+     Remove it completely as we moved it to inside of `@edirect/trace`:
+
+     ```js
+     if (apmConfig.enabled) {
+       app.use(new traceMiddlewares.Body().body);
+     }
+     ```
+
+## NextJS Applications
+
+NextJS applications **should be upgraded to version 12 or above**.
+
+1.  Install the trace package:
+
+    ```bash
+    npm install --save @edirect/trace
+    ```
+
+2.  Create a middleware
+    - When you upgrade the NextJS application to the version 12(or above) you will be able
+      to use [Middlewares](https://nextjs.org/docs/advanced-features/middleware).
+
+          Create a file called as `middleware.ts(or .js)` inside of the `src` folder.
+
+          ```ts
+          import { NextResponse } from 'next/server';
+          import type { NextRequest } from 'next/server';
+          import NextJsTracer from '@edirect/trace/dist/middlewares/nextjs';
+
+          // This function can be marked `async` if using `await` inside
+          export function middleware(request: NextRequest) {
+          // @edirect/trace
+          new NextJsTracer().body(req as unknown as Request & Record<string, unknown>);
+          NextResponse.next();
+          }
+          ```
+
+3.  Install dotenv and create a dotenv.config
+
+    ```bash
+    npm install --save dotenv
+    ```
+
+    `dotenv.config.js`
+
+    ```js
+    const dotenv = require('dotenv');
+    const nodeEnv = process.env.NODE_ENV || 'development';
+
+    dotenv.config({ path: `.${nodeEnv}.env` });
+    ```
+
+4.  Add the environment variables to your NextJS app:
+    **Example:**`.development.env`
+
+    ```yml
+    ## OPEN TELEMETRY
+    TRACE_TAG_OWNER=OWNER
+    TRACE_TAG_SCOPE=ie
+    TRACE_TAG_SERVICENAME=frontend-v2
+    TRACE_TAG_TENANT={STAGE}-{INSTANCE}
+    TRACE_SERVER_URL={URL}
+    TRACE_TAG_SERVICE=frontend-v2-{STAGE}-{INSTANCE}
+    TRACE_TAG_VERSION=1.0.0
+    TRACE_TAG_CLUSTER=stag-ie
+    TRACE_TAG_ENV=ie-stag-broker
+    ```
+
+5.  Serve your production build on the standalone mode. Add this line to your `next.config.js` file
+
+    ```js
+    module.exports = {
+      // ...myOtherSettings
+      output: 'standalone',
+    };
+    ```
+
+6.  Change the **start** and **dev** command:
+    ```json
+    {
+      "scripts": {
+        "dev": "cross-env NODE_ENV=development node --require ./dotenv.config.js  --require ./node_modules/@edirect/trace/dist/otel.js ./node_modules/next/dist/bin/next -p 3100",
+        "start": "cross-env NODE_ENV=production node --require ./dotenv.config.js --require ./node_modules/@edirect/trace/dist/otel.js ./build/client/standalone/server.js -p 3100"
+      }
+    }
+    ```
+
+## Other (Not nest-app:9)
+
+### If you are unable to update to nest 9 or is not nest (express)
+
+- [@edirect/trace](https://bitbucket.org/gofrank/trace/src/master/)
+
+  The usage of `@edirect/trace` will need your care to inject our middleware to log all requests from the app
+  1. Install the trace package
+
+     ```bash
+     npm install --save @edirect/trace
+     ```
+
+  2. Import the trace package
+
+     ```js
+     import { middlewares as traceMiddlewares } from '@edirect/trace';
+     ```
+
+  3. Add the trace middleware to your application routes
+
+     Express:
+
+     ```js
+     app.use(new traceMiddlewares.Body().body);
+     ```
+
+     NestJs with nest-app:
+
+     ```js
+     consumer
+       .apply(new traceMiddlewares.Body().body)
+       .forRoutes({ path: '/**', method: RequestMethod.ALL });
+     ```
+
+  4. We should initialize our application with `otel` as a requirement for node startup command:
+
+     ```bash
+     node --require ./node_modules/@edirect/trace/dist/otel.js dist/main
+     ```
+
+     (dist/main or your application entrypoint)
+
+  5. Remove the old client initialization as we moved it to the node require
+
+     If the service was using old trace version
+
+     ```js
+     const config = require('config');
+     const {
+       services: { APM },
+       middlewares: traceMiddlewares,
+     } = require('@edirect/trace');
+     const apmConfig = config.get('apm');
+
+     if (apmConfig.enabled) {
+       const apm = new APM(
+         apmConfig.service,
+         apmConfig.url,
+         apmConfig.traceServer,
+       );
+       apm.startTrace();
+     }
+     ```
+
+  6. Clean the middleware usage
+
+     If the service was using old trace version
+
+     Replace:
+
+     ```js
+     if (apmConfig.enabled) {
+       app.use(new traceMiddlewares.Body().body);
+     }
+     ```
+
+     with:
+
+     ```js
+     app.use(new traceMiddlewares.Body().body);
+     ```
+
+## Applying k8s configurations (Required)
+
+We created a standard way to deploy our application configurations and simplify its configurations:
+
+- Sometimes it could be already done by another team and you don't need to manage the configuration, just generate the configurations and apply it
+- `bolttech-broker-asia\staging\config-map.yaml` (or your environment config-map)
+
+  ```yaml
+  auth: #or your service
+    trace:
+    tags:
+      scope: ie #your tech center
+      env: ie-stag-broker #current k8s cluster environment
+      cluster: stag-ie #current k8s cluster
+      tenant: ${namespace}
+      service: ${name}-${namespace}
+      servicename: ${name}
+      version: '1.0.0'
+      owner: OWNER
+      server: opentelemetry-collector.stag.bolttechbroker.net #cluster opentelemetry server
+  ```
+
+Then you should generate and apply your brand new configurations:
+
+1. Generate
+
+   This command will generate the new configuration files for the services.
+
+   ```bash
+   # Staging Clusters
+   edi infra bolttech-broker-asia k8s generate <ENVIRONMENT> <SERVICE>
+   edi infra bolttech-broker-asia k8s generate stage1-vnbroker rules-engine # VN Example
+
+   # Production Clusters
+   edi infra <PRODUCTION_BROKER> k8s generate <ENVIRONMENT> <SERVICE>
+   edi infra bolttech-broker-asia-hk k8s generate live-hkbroker-a policy-issuing-service --prod # HK Example
+   ```
+
+2. Apply
+
+   This command will apply the new configurations and **redeploy** the service on the cluster.
+
+   ```bash
+   # Staging Clusters
+   edi infra bolttech-broker-asia k8s apply staging <STAGE/RC> <SERVICE> --redeploy
+   edi infra bolttech-broker-asia k8s apply staging rc-vnbroker frontend-service --redeploy # VN Example
+
+   # Production Clusters
+   edi infra <PRODUCTION_BROKER> k8s apply <CLUSTER> <ENVIRONMENT> <SERVICE>
+   edi infra bolttech-broker-asia-hk k8s apply cluster-a live-hkbroker-a plan-service --prod --redeploy # HK Example
+   ```
+
+- Key notes when using the infrastructure repositories:
+  - Before running any command make sure you have completed the setup of the `edi-cli` tool and that you have all the related projects (`infrastructure` and `k8s-templates`) inside the same root folder.
+  - Make sure to have the most recent version of the `master` branch before running any commands.
+  - Remember to **ALWAYS COMMIT AND PUSH YOUR CHANGES TO THE REPOSITORIES, OTHERWISE THE NEW CONFIGURATIONS WILL NOT BE APPLIED TO SERVICES WHEN THEY ARE DEPLOYED USING THE JENKINS PIPELINES**.
+  - To make things easier, make sure to check the helper script on `edi-cli` project. Located at the `edi-cli-cli` folder.
+  - Consider hiding the folders of the brokers you will not need to work with. This will greatly improve your navigation inside the project.
+
+## Debugging
+
+- How to debug it on vscode:
+
+  As we don't debug using node command directly, we suggest you to use this in your `.vscode/launch.json`
+
+  ```json
+  {
+    "version": "0.2.0",
+    "configurations": [
+      {
+        "type": "node",
+        "request": "launch",
+        "name": "Debug with OTEL",
+        "args": ["${workspaceFolder}/src/main.ts"],
+        "runtimeArgs": [
+          "--inspect",
+          "-r",
+          "./node_modules/@edirect/trace/dist/otel.js",
+          "-r",
+          "tsconfig-paths/register",
+          "-r",
+          "ts-node/register"
+        ],
+        "console": "integratedTerminal",
+        "envFile": "${workspaceFolder}/.development.env"
+      }
+    ]
+  }
+  ```
+
+  and append the OTEL environment variables to your local environments file:
+
+  ```conf
+  TRACE_TAG_OWNER=OWNER
+  TRACE_TAG_SCOPE=pgw
+  TRACE_TAG_SERVICENAME=payment-gateway
+  TRACE_TAG_TENANT=local-paythbroker
+  TRACE_SERVER_URL=opentelemetry-collector.stag.bolttechpay.net
+  TRACE_TAG_SERVICE=payment-gateway-local-paythbroker
+  TRACE_TAG_VERSION=1.0.0
+  TRACE_TAG_CLUSTER=localhost
+  TRACE_TAG_ENV=development
+  ```

package/dist/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@edirect/trace",
+  "version": "11.0.25",
+  "description": "Edirect trace",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "default": "./dist/src/index.js",
+      "require": "./dist/src/index.js",
+      "types": "./dist/src/index.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "author": "EDirectInsure",
+  "license": "ISC",
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/auto-instrumentations-node": "^0.62.2",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.203.0",
+    "@opentelemetry/instrumentation": "^0.203.0",
+    "@opentelemetry/instrumentation-express": "^0.52.0",
+    "@opentelemetry/instrumentation-http": "^0.203.0",
+    "@opentelemetry/resources": "^2.0.1",
+    "@opentelemetry/sdk-node": "^0.203.0",
+    "@opentelemetry/sdk-trace-base": "^2.0.1",
+    "@opentelemetry/sdk-trace-node": "^2.0.1",
+    "@opentelemetry/semantic-conventions": "^1.37.0",
+    "cls-hooked": "^4.2.2",
+    "express-mung": "^0.5.1",
+    "reflect-metadata": "^0.2.2",
+    "uuid": "^11.1.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.3",
+    "@types/node": "^24.3.0",
+    "typescript": "^5.9.2"
+  },
+  "type": "commonjs"
+}

package/package.json

@@ -1,43 +1,68 @@
 {
   "name": "@edirect/trace",
-  "version": "10.0.0",
+  "version": "11.0.25",
   "description": "Edirect trace",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "scripts": {
-    "prebuild": "node -p \"'export const LIB_VERSION = ' + JSON.stringify(require('./package.json').version) + ';'\" > src/version.ts",
-    "build": "tsc --build ./tsconfig.build.json"
+  "packageScope": "@edirect",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "default": "./dist/src/index.js",
+      "require": "./dist/src/index.js",
+      "types": "./dist/src/index.d.ts"
+    },
+    "./package.json": "./package.json"
   },
+  "files": [
+    "dist"
+  ],
   "author": "EDirectInsure",
   "license": "ISC",
-  "devDependencies": {
-    "@types/express": "^4.17.14",
-    "@types/node": "^16.3.2",
-    "@typescript-eslint/eslint-plugin": "^4.19.0",
-    "@typescript-eslint/parser": "^4.19.0",
-    "eslint": "^7.22.0",
-    "eslint-config-prettier": "^8.1.0",
-    "eslint-plugin-prettier": "^3.3.1",
-    "husky": "^3.1.0",
-    "prettier": "^2.2.1",
-    "typescript": "^4.9.5"
-  },
   "dependencies": {
     "@opentelemetry/api": "^1.9.0",
-    "@opentelemetry/auto-instrumentations-node": "^0.53.0",
-    "@opentelemetry/exporter-trace-otlp-http": "^0.55.0",
-    "@opentelemetry/instrumentation": "^0.55.0",
-    "@opentelemetry/instrumentation-express": "^0.45.0",
-    "@opentelemetry/instrumentation-http": "^0.55.0",
-    "@opentelemetry/resources": "^1.28.0",
-    "@opentelemetry/sdk-node": "^0.55.0",
-    "@opentelemetry/sdk-trace-base": "^1.28.0",
-    "@opentelemetry/sdk-trace-node": "^1.28.0",
-    "@opentelemetry/semantic-conventions": "^1.28.0",
+    "@opentelemetry/auto-instrumentations-node": "^0.62.2",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.203.0",
+    "@opentelemetry/instrumentation": "^0.203.0",
+    "@opentelemetry/instrumentation-express": "^0.52.0",
+    "@opentelemetry/instrumentation-http": "^0.203.0",
+    "@opentelemetry/resources": "^2.0.1",
+    "@opentelemetry/sdk-node": "^0.203.0",
+    "@opentelemetry/sdk-trace-base": "^2.0.1",
+    "@opentelemetry/sdk-trace-node": "^2.0.1",
+    "@opentelemetry/semantic-conventions": "^1.37.0",
     "cls-hooked": "^4.2.2",
     "express-mung": "^0.5.1",
-    "querystring": "^0.2.1",
     "reflect-metadata": "^0.2.2",
-    "uuid": "^10.0.0"
+    "uuid": "^11.1.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.3",
+    "@types/node": "^24.3.0",
+    "@typescript-eslint/eslint-plugin": "^8.42.0",
+    "@typescript-eslint/parser": "^8.42.0",
+    "eslint": "^9.34.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.4",
+    "husky": "^9.1.7",
+    "prettier": "^3.6.2",
+    "typescript": "^5.9.2"
+  },
+  "nx": {
+    "name": "@edirect/trace",
+    "targets": {
+      "build": {
+        "executor": "@nx/js:tsc",
+        "options": {
+          "main": "{workspaceRoot}/packages/edirect-trace/src/index.ts",
+          "tsConfig": "{workspaceRoot}/packages/edirect-trace/tsconfig.lib.json",
+          "outputPath": "{workspaceRoot}/packages/edirect-trace/dist",
+          "assets": [
+            "{workspaceRoot}/packages/edirect-trace/package.json",
+            "{workspaceRoot}/packages/edirect-trace/README.md"
+          ]
+        }
+      }
+    }
   }
-}
+}

package/.editorconfig

@@ -1,14 +0,0 @@
-root = true
-
-[*]
-end_of_line = lf
-insert_final_newline = true
-charset = utf-8
-
-[*.js]
-indent_style = space
-indent_size = 2
-trim_trailing_whitespace = true
-
-[*.md]
-trim_trailing_whitespace = false

package/.eslintignore

@@ -1 +0,0 @@
-/node_modules

package/.eslintrc.js

@@ -1,44 +0,0 @@
-module.exports = {
-  env: {
-    browser: true,
-    es6: true,
-    node: true,
-  },
-  extends: [
-    'plugin:@typescript-eslint/recommended',
-    'prettier'
-  ],
-  globals: {
-    Atomics: 'readonly',
-    SharedArrayBuffer: 'readonly',
-  },
-  parser: '@typescript-eslint/parser',
-  parserOptions: {
-    ecmaFeatures: {
-      jsx: true,
-    },
-    ecmaVersion: 2018,
-    sourceType: 'module',
-    project: './tsconfig.json',
-    tsconfigRootDir: __dirname,
-  },
-  plugins: ['@typescript-eslint', 'prettier'],
-  rules: {
-    'no-unused-vars': 0,
-    '@typescript-eslint/no-unused-vars': [
-      'error',
-      { argsIgnorePattern: '^_', varsIgnorePattern: '^_' },
-    ],
-    '@typescript-eslint/no-explicit-any': 0,
-    '@typescript-eslint/ban-ts-ignore': 0,
-    '@typescript-eslint/explicit-function-return-type': [
-      'warn',
-      {
-        allowExpressions: true,
-        allowTypedFunctionExpressions: true,
-        allowHigherOrderFunctions: true,
-      },
-    ],
-    '@typescript-eslint/no-floating-promises': 1,
-  },
-};