Noop Observability Manager

README.md

@@ -5,6 +5,7 @@ Core libraries for Node.js backend services.
 - [Default Logging Configuration](#default-logging-configuration)
 - [ConfigScope](#configscope)
 - [Error Handling](#error-handling)
+- [Observability](#observability)
 
 See [docs](/docs) for further instructions on how to use.
 
@@ -209,3 +210,43 @@ expect(someEventEmitter.emittedEvents.length).toBe(1)
 
 - `StreamUtils` - utils for temporary persisting of streams for length calculation and reuse
 - `streamToBuffer` - utility for converting a stream to a buffer
+
+## Observability
+
+The library provides utilities for transaction observability management through the `TransactionObservabilityManager` interface.
+
+### TransactionObservabilityManager
+
+An interface for tracking background transactions with the following methods:
+
+- `start(transactionName, uniqueTransactionKey)` - Creates and starts a background transaction
+- `startWithGroup(transactionName, uniqueTransactionKey, transactionGroup)` - Creates and starts a background transaction related to a specified group
+- `stop(uniqueTransactionKey, wasSuccessful?)` - Ends the transaction
+- `addCustomAttributes(uniqueTransactionKey, atts)` - Adds custom attributes to the current transaction
+
+### MultiTransactionObservabilityManager
+
+Groups multiple `TransactionObservabilityManager` instances into one to facilitate tracking transactions across multiple observability tools.
+
+```ts
+import { MultiTransactionObservabilityManager } from '@lokalise/node-core'
+
+const multiManager = new MultiTransactionObservabilityManager([
+  newRelicManager,
+  datadogManager,
+])
+
+multiManager.start('processOrder', 'order-123')
+```
+
+### NoopObservabilityManager
+
+A no-operation implementation of `TransactionObservabilityManager`. All methods are implemented but do nothing. Use this when you need to satisfy a `TransactionObservabilityManager` dependency but don't want any actual observability tracking to occur.
+
+```ts
+import { NoopObservabilityManager } from '@lokalise/node-core'
+
+const noopManager = new NoopObservabilityManager()
+// Pass to any component requiring a TransactionObservabilityManager
+const service = new MyService({ observabilityManager: noopManager })
+```

src/index.ts

@@ -107,6 +107,7 @@ export { waitAndRetry } from './utils/waitUtils'
 
 export type { TransactionObservabilityManager } from './observability/observabilityTypes'
 export { MultiTransactionObservabilityManager } from './observability/MultiTransactionObservabilityManager'
+export { NoopObservabilityManager } from './observability/NoopObservabilityManager'
 
 export {
   generateChecksumForReadable,

src/observability/NoopObservabilityManager.ts

@@ -0,0 +1,61 @@
+import type { TransactionObservabilityManager } from './observabilityTypes'
+
+/**
+ * A no-operation implementation of TransactionObservabilityManager.
+ * All methods are implemented but do nothing.
+ *
+ * Use this implementation when you need to satisfy a TransactionObservabilityManager
+ * dependency but don't want any actual observability tracking to occur.
+ *
+ * @example
+ * ```typescript
+ * const noopManager = new NoopObservabilityManager()
+ * // Pass to any component requiring a TransactionObservabilityManager
+ * const service = new MyService({ observabilityManager: noopManager })
+ * ```
+ */
+export class NoopObservabilityManager implements TransactionObservabilityManager {
+  /**
+   * No-op implementation of start. Does nothing.
+   * @param _transactionName - Ignored
+   * @param _uniqueTransactionKey - Ignored
+   */
+  start(_transactionName: string, _uniqueTransactionKey: string): void {
+    // noop
+  }
+
+  /**
+   * No-op implementation of startWithGroup. Does nothing.
+   * @param _transactionName - Ignored
+   * @param _uniqueTransactionKey - Ignored
+   * @param _transactionGroup - Ignored
+   */
+  startWithGroup(
+    _transactionName: string,
+    _uniqueTransactionKey: string,
+    _transactionGroup: string,
+  ): void {
+    // noop
+  }
+
+  /**
+   * No-op implementation of stop. Does nothing.
+   * @param _uniqueTransactionKey - Ignored
+   * @param _wasSuccessful - Ignored
+   */
+  stop(_uniqueTransactionKey: string, _wasSuccessful?: boolean): void {
+    // noop
+  }
+
+  /**
+   * No-op implementation of addCustomAttributes. Does nothing.
+   * @param _uniqueTransactionKey - Ignored
+   * @param _atts - Ignored
+   */
+  addCustomAttributes(
+    _uniqueTransactionKey: string,
+    _atts: { [key: string]: string | number | boolean },
+  ): void {
+    // noop
+  }
+}

vitest.config.mts

@@ -20,6 +20,7 @@ export default defineConfig({
         'src/errors/publicErrors.ts',
         'src/errors/globalErrorHandler.ts',
         'src/config/configTransformers.ts',
+        'src/observability/NoopObservabilityManager.ts',
       ],
       reporter: ['text'],
       all: true,