feat(txm): instrumentation is configurable

GabrielMartinezRodriguez · GabrielMartinezRodriguez · commit ddfe09e16f92 · 2025-03-17T16:25:03.000+01:00
diff --git a/packages/txm/lib/BlockMonitor.ts b/packages/txm/lib/BlockMonitor.ts
@@ -2,7 +2,7 @@ import { LogTag, Logger } from "@happy.tech/common"
 import type { Block } from "viem"
 import { Topics, eventBus } from "./EventBus.js"
 import type { TransactionManager } from "./TransactionManager.js"
-import { currentBlockGauge, newBlockDelayHistogram, resetBlockMonitorCounter } from "./telemetry/metrics"
+import { TxmMetrics } from "./telemetry/metrics"
 
 /**
  * A type alias for {@link Block} with the `blockTag` set to `"latest"`, ensuring type definitions correspond to the latest block.
@@ -38,8 +38,8 @@ export class BlockMonitor {
         if (this.blockTimeout) clearTimeout(this.blockTimeout)
         eventBus.emit(Topics.NewBlock, block)
 
-        currentBlockGauge.record(Number(block.number))
-        newBlockDelayHistogram.record(Date.now() - Number(block.timestamp) * 1000)
+        TxmMetrics.getInstance().currentBlockGauge.record(Number(block.number))
+        TxmMetrics.getInstance().newBlockDelayHistogram.record(Date.now() - Number(block.timestamp) * 1000)
 
         this.scheduleTimeout()
     }
@@ -52,7 +52,7 @@ export class BlockMonitor {
     }
 
     private resetBlockSubscription() {
-        resetBlockMonitorCounter.add(1)
+        TxmMetrics.getInstance().resetBlockMonitorCounter.add(1)
         if (this.unwatch) {
             this.unwatch()
         }
diff --git a/packages/txm/lib/NonceManager.ts b/packages/txm/lib/NonceManager.ts
@@ -1,6 +1,6 @@
 import { LogTag, Logger } from "@happy.tech/common"
 import type { TransactionManager } from "./TransactionManager"
-import { nonceManagerGauge, returnedNonceCounter, returnedNonceQueueGauge } from "./telemetry/metrics"
+import { TxmMetrics } from "./telemetry/metrics"
 
 /*
 /*
@@ -66,13 +66,13 @@ export class NonceManager {
     public requestNonce(): number {
         if (this.returnedNonceQueue.length > 0) {
             const nonce = this.returnedNonceQueue.shift()!
-            returnedNonceQueueGauge.record(this.returnedNonceQueue.length)
+            TxmMetrics.getInstance().returnedNonceQueueGauge.record(this.returnedNonceQueue.length)
             return nonce
         }
 
         const requestedNonce = this.nonce
         this.nonce = this.nonce + 1
-        nonceManagerGauge.record(this.nonce)
+        TxmMetrics.getInstance().nonceManagerGauge.record(this.nonce)
         return requestedNonce
     }
 
@@ -86,8 +86,8 @@ export class NonceManager {
             this.returnedNonceQueue.splice(index, 0, nonce)
         }
 
-        returnedNonceCounter.add(1)
-        returnedNonceQueueGauge.record(this.returnedNonceQueue.length)
+        TxmMetrics.getInstance().returnedNonceCounter.add(1)
+        TxmMetrics.getInstance().returnedNonceQueueGauge.record(this.returnedNonceQueue.length)
     }
 
     public async resync() {
diff --git a/packages/txm/lib/Transaction.ts b/packages/txm/lib/Transaction.ts
@@ -4,7 +4,7 @@ import type { Address, ContractFunctionArgs, Hash } from "viem"
 import type { LatestBlock } from "./BlockMonitor"
 import { Topics, eventBus } from "./EventBus.js"
 import type { TransactionTable } from "./db/types.js"
-import { attemptsUntilFinalization, transactionStatusChangeCounter } from "./telemetry/metrics"
+import { TxmMetrics } from "./telemetry/metrics"
 
 export enum TransactionStatus {
     /**
@@ -206,11 +206,11 @@ export class Transaction {
         this.status = status
         this.markUpdated()
 
-        transactionStatusChangeCounter.add(1, {
+        TxmMetrics.getInstance().transactionStatusChangeCounter.add(1, {
             status: this.status,
         })
 
-        attemptsUntilFinalization.record(this.attempts.length)
+        TxmMetrics.getInstance().attemptsUntilFinalization.record(this.attempts.length)
 
         eventBus.emit(Topics.TransactionStatusChanged, {
             transaction: this,
diff --git a/packages/txm/lib/TransactionCollector.ts b/packages/txm/lib/TransactionCollector.ts
@@ -3,7 +3,7 @@ import type { LatestBlock } from "./BlockMonitor.js"
 import { Topics, eventBus } from "./EventBus.js"
 import { AttemptType, TransactionStatus } from "./Transaction.js"
 import type { TransactionManager } from "./TransactionManager.js"
-import { transactionCollectedCounter } from "./telemetry/metrics"
+import { TxmMetrics } from "./telemetry/metrics"
 
 /**
  * This module is responsible for retrieving transactions from the originators when a new block is received.
@@ -42,7 +42,7 @@ export class TransactionCollector {
             return
         }
 
-        transactionCollectedCounter.add(transactionsBatch.length)
+        TxmMetrics.getInstance().transactionCollectedCounter.add(transactionsBatch.length)
 
         await Promise.all(
             transactionsBatch.map(async (transaction) => {
diff --git a/packages/txm/lib/TransactionManager.ts b/packages/txm/lib/TransactionManager.ts
@@ -6,6 +6,7 @@ import {
     convertToSafeViemWalletClient,
     getUrlProtocol,
 } from "@happy.tech/common"
+import type { MetricReader } from "@opentelemetry/sdk-metrics"
 import type { Result } from "neverthrow"
 import {
     type Abi,
@@ -31,7 +32,8 @@ import { TransactionRepository } from "./TransactionRepository.js"
 import { TransactionSubmitter } from "./TransactionSubmitter.js"
 import { TxMonitor } from "./TxMonitor.js"
 import { type EIP1559Parameters, opStackDefaultEIP1559Parameters } from "./eip1559.js"
-import { blockchainRpcResponseTimeHistogram, rpcCounter, rpcErrorCounter } from "./telemetry/metrics"
+import { initializeTelemetry } from "./telemetry/instrumentation"
+import { TxmMetrics } from "./telemetry/metrics"
 
 export type TransactionManagerConfig = {
     /**
@@ -139,6 +141,30 @@ export type TransactionManagerConfig = {
      * Default: {@link DefaultRetryPolicyManager}
      */
     retryPolicyManager?: RetryPolicyManager
+
+    /**
+     * Transaction Manager metrics configuration.
+     */
+    metrics?: {
+        /**
+         * Whether to enable metrics collection.
+         * Defaults to true.
+         */
+        active?: boolean
+        /**
+         * Port number for the default Prometheus metrics endpoint.
+         * The default metric reader is a Prometheus reader that exposes metrics via this endpoint.
+         * This setting is only used when custom metricReaders are not provided.
+         * Defaults to 9090.
+         */
+        port?: number
+        /**
+         * Custom metric readers to use instead of the default Prometheus reader.
+         * If provided, these readers will be used and the port setting will be ignored.
+         * If not provided, a default Prometheus reader will be configured using the specified port.
+         */
+        metricReaders?: MetricReader[]
+    }
 }
 
 export type TransactionOriginator = (block: LatestBlock) => Promise<Transaction[]>
@@ -178,6 +204,12 @@ export class TransactionManager {
     public readonly blockInactivityTimeout: number
 
     constructor(_config: TransactionManagerConfig) {
+        initializeTelemetry({
+            active: _config.metrics?.active ?? true,
+            port: _config.metrics?.port ?? 9090,
+            metricReaders: _config.metrics?.metricReaders,
+        })
+
         this.collectors = []
 
         const protocol = getUrlProtocol(_config.rpc.url)
@@ -237,9 +269,9 @@ export class TransactionManager {
                 chain,
             }),
             {
-                rpcCounter: rpcCounter,
-                rpcErrorCounter: rpcErrorCounter,
-                rpcResponseTimeHistogram: blockchainRpcResponseTimeHistogram,
+                rpcCounter: TxmMetrics.getInstance().rpcCounter,
+                rpcErrorCounter: TxmMetrics.getInstance().rpcErrorCounter,
+                rpcResponseTimeHistogram: TxmMetrics.getInstance().blockchainRpcResponseTimeHistogram,
             },
         )
 
@@ -249,9 +281,9 @@ export class TransactionManager {
                 chain,
             }),
             {
-                rpcCounter: rpcCounter,
-                rpcErrorCounter: rpcErrorCounter,
-                rpcResponseTimeHistogram: blockchainRpcResponseTimeHistogram,
+                rpcCounter: TxmMetrics.getInstance().rpcCounter,
+                rpcErrorCounter: TxmMetrics.getInstance().rpcErrorCounter,
+                rpcResponseTimeHistogram: TxmMetrics.getInstance().blockchainRpcResponseTimeHistogram,
             },
         )
 
diff --git a/packages/txm/lib/TransactionRepository.ts b/packages/txm/lib/TransactionRepository.ts
@@ -5,12 +5,7 @@ import { Topics, eventBus } from "./EventBus.js"
 import { NotFinalizedStatuses, Transaction } from "./Transaction.js"
 import type { TransactionManager } from "./TransactionManager.js"
 import { db } from "./db/driver.js"
-import {
-    databaseErrorsCounter,
-    databaseOperationDurationHistogram,
-    databaseOperationsCounter,
-    notFinalizedTransactionsGauge,
-} from "./telemetry/metrics"
+import { TxmMetrics } from "./telemetry/metrics"
 
 /**
  * This module acts as intermediate layer between the library and the database.
@@ -54,7 +49,7 @@ export class TransactionRepository {
             return ok(cachedTransaction)
         }
 
-        databaseOperationsCounter.add(1, {
+        TxmMetrics.getInstance().databaseOperationsCounter.add(1, {
             operation: "getTransaction",
         })
         const start = Date.now()
@@ -69,12 +64,12 @@ export class TransactionRepository {
             unknownToError,
         )
 
-        databaseOperationDurationHistogram.record(Date.now() - start, {
+        TxmMetrics.getInstance().databaseOperationDurationHistogram.record(Date.now() - start, {
             operation: "getTransaction",
         })
 
         if (persistedTransactionResult.isErr()) {
-            databaseErrorsCounter.add(1, {
+            TxmMetrics.getInstance().databaseErrorsCounter.add(1, {
                 operation: "getTransaction",
             })
             return err(persistedTransactionResult.error)
@@ -90,7 +85,7 @@ export class TransactionRepository {
 
         const notPersistedTransactions = transactions.filter((t) => t.notPersisted)
 
-        databaseOperationsCounter.add(1, {
+        TxmMetrics.getInstance().databaseOperationsCounter.add(1, {
             operation: "saveTransactions",
         })
         const start = Date.now()
@@ -113,7 +108,7 @@ export class TransactionRepository {
             unknownToError,
         )
 
-        databaseOperationDurationHistogram.record(Date.now() - start, {
+        TxmMetrics.getInstance().databaseOperationDurationHistogram.record(Date.now() - start, {
             operation: "saveTransactions",
         })
 
@@ -124,9 +119,9 @@ export class TransactionRepository {
             this.notFinalizedTransactions.push(...notPersistedTransactions)
             transactions.forEach((t) => t.markFlushed())
 
-            notFinalizedTransactionsGauge.record(this.notFinalizedTransactions.length)
+            TxmMetrics.getInstance().notFinalizedTransactionsGauge.record(this.notFinalizedTransactions.length)
         } else {
-            databaseErrorsCounter.add(1, {
+            TxmMetrics.getInstance().databaseErrorsCounter.add(1, {
                 operation: "saveTransactions",
             })
         }
@@ -147,7 +142,7 @@ export class TransactionRepository {
     }
 
     async purgeFinalizedTransactions() {
-        databaseOperationsCounter.add(1, {
+        TxmMetrics.getInstance().databaseOperationsCounter.add(1, {
             operation: "purgeFinalizedTransactions",
         })
         const start = Date.now()
@@ -162,12 +157,12 @@ export class TransactionRepository {
             unknownToError,
         )
 
-        databaseOperationDurationHistogram.record(Date.now() - start, {
+        TxmMetrics.getInstance().databaseOperationDurationHistogram.record(Date.now() - start, {
             operation: "purgeFinalizedTransactions",
         })
 
         if (result.isErr()) {
-            databaseErrorsCounter.add(1, {
+            TxmMetrics.getInstance().databaseErrorsCounter.add(1, {
                 operation: "purgeFinalizedTransactions",
             })
         }
diff --git a/packages/txm/lib/TxMonitor.ts b/packages/txm/lib/TxMonitor.ts
@@ -6,7 +6,7 @@ import { Topics, eventBus } from "./EventBus.js"
 import type { RevertedTransactionReceipt } from "./RetryPolicyManager"
 import { type Attempt, AttemptType, type Transaction, TransactionStatus } from "./Transaction.js"
 import type { TransactionManager } from "./TransactionManager.js"
-import { transactionInclusionBlockHistogram, transactionsRetriedCounter } from "./telemetry/metrics"
+import { TxmMetrics } from "./telemetry/metrics"
 
 type AttemptWithReceipt = { attempt: Attempt; receipt: TransactionReceipt }
 
@@ -140,7 +140,9 @@ export class TxMonitor {
 
             const { attempt, receipt } = attemptOrResults
 
-            transactionInclusionBlockHistogram.record(Number(block.number - transaction.collectionBlock!))
+            TxmMetrics.getInstance().transactionInclusionBlockHistogram.record(
+                Number(block.number - transaction.collectionBlock!),
+            )
 
             if (receipt.status === "success") {
                 if (attempt.type === AttemptType.Cancellation) {
@@ -162,7 +164,7 @@ export class TxMonitor {
                 return transaction.changeStatus(TransactionStatus.Failed)
             }
 
-            transactionsRetriedCounter.add(1)
+            TxmMetrics.getInstance().transactionsRetriedCounter.add(1)
 
             return this.handleRetryTransaction(transaction)
         })
diff --git a/packages/txm/lib/telemetry/instrumentation.ts b/packages/txm/lib/telemetry/instrumentation.ts
@@ -1,7 +1,7 @@
 import opentelemetry from "@opentelemetry/api"
 import { PrometheusExporter } from "@opentelemetry/exporter-prometheus"
 import { Resource } from "@opentelemetry/resources"
-import { MeterProvider } from "@opentelemetry/sdk-metrics"
+import { MeterProvider, type MetricReader } from "@opentelemetry/sdk-metrics"
 import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from "@opentelemetry/semantic-conventions"
 
 const resource = Resource.default().merge(
@@ -11,11 +11,19 @@ const resource = Resource.default().merge(
     }),
 )
 
-const prometheusExporter = new PrometheusExporter({ port: 9090 })
+export function initializeTelemetry({
+    active,
+    port,
+    metricReaders,
+}: { active: boolean; port: number; metricReaders?: MetricReader[] }): void {
+    if (!active) {
+        return
+    }
 
-const myServiceMeterProvider = new MeterProvider({
-    resource: resource,
-    readers: [prometheusExporter],
-})
+    const meterProvider = new MeterProvider({
+        resource: resource,
+        readers: metricReaders || [new PrometheusExporter({ port })],
+    })
 
-opentelemetry.metrics.setGlobalMeterProvider(myServiceMeterProvider)
+    opentelemetry.metrics.setGlobalMeterProvider(meterProvider)
+}
diff --git a/packages/txm/lib/telemetry/metrics.ts b/packages/txm/lib/telemetry/metrics.ts
