@aztec/telemetry-client 0.0.0-test.1 → 0.0.1-commit.017a351

package/package.json

@@ -1,5 +1,6 @@
 {
   "name": "@aztec/telemetry-client",
+  "version": "0.0.1-commit.017a351",
   "inherits": [
     "../package.common.json"
   ],
@@ -7,18 +8,18 @@
   "exports": {
     ".": "./dest/index.js",
     "./bench": "./dest/bench.js",
+    "./config": "./dest/config.js",
+    "./start": "./dest/start.js",
     "./otel-pino-stream": "./dest/vendor/otel-pino-stream.js"
   },
   "scripts": {
-    "build": "yarn clean && tsc -b",
-    "build:dev": "tsc -b --watch",
+    "build": "yarn clean && ../scripts/tsc.sh",
+    "build:dev": "../scripts/tsc.sh --watch",
     "clean": "rm -rf ./dest .tsbuildinfo",
-    "formatting": "run -T prettier --check ./src && run -T eslint ./src",
-    "formatting:fix": "run -T eslint --fix ./src && run -T prettier -w ./src",
     "test": "NODE_NO_WARNINGS=1 node --experimental-vm-modules ../node_modules/.bin/jest --passWithNoTests --maxWorkers=${JEST_MAX_WORKERS:-8}"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20.10"
   },
   "files": [
     "dest",
@@ -26,15 +27,15 @@
     "!*.test.*"
   ],
   "dependencies": {
-    "@aztec/foundation": "0.0.0-test.1",
-    "@aztec/stdlib": "0.0.0-test.1",
+    "@aztec/foundation": "0.0.1-commit.017a351",
+    "@aztec/stdlib": "0.0.1-commit.017a351",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/api-logs": "^0.55.0",
     "@opentelemetry/core": "^1.28.0",
     "@opentelemetry/exporter-logs-otlp-http": "^0.55.0",
     "@opentelemetry/exporter-metrics-otlp-http": "^0.55.0",
     "@opentelemetry/exporter-trace-otlp-http": "^0.55.0",
-    "@opentelemetry/host-metrics": "^0.35.4",
+    "@opentelemetry/host-metrics": "^0.36.2",
     "@opentelemetry/otlp-exporter-base": "^0.55.0",
     "@opentelemetry/resource-detector-gcp": "^0.32.0",
     "@opentelemetry/resources": "^1.28.0",
@@ -42,15 +43,17 @@
     "@opentelemetry/sdk-metrics": "^1.28.0",
     "@opentelemetry/sdk-trace-node": "^1.28.0",
     "@opentelemetry/semantic-conventions": "^1.28.0",
-    "prom-client": "^15.1.3"
+    "prom-client": "^15.1.3",
+    "viem": "npm:@aztec/viem@2.38.2"
   },
   "devDependencies": {
-    "@jest/globals": "^29.5.0",
-    "@types/jest": "^29.5.0",
+    "@jest/globals": "^30.0.0",
+    "@types/jest": "^30.0.0",
     "@types/koa": "^2.15.0",
-    "jest": "^29.5.0",
+    "@typescript/native-preview": "7.0.0-dev.20260113.1",
+    "jest": "^30.0.0",
     "ts-node": "^10.9.1",
-    "typescript": "^5.0.4"
+    "typescript": "^5.3.3"
   },
   "jest": {
     "extensionsToTreatAsEsm": [
@@ -83,7 +86,10 @@
     "testTimeout": 120000,
     "setupFiles": [
       "../../foundation/src/jest/setup.mjs"
+    ],
+    "testEnvironment": "../../foundation/src/jest/env.mjs",
+    "setupFilesAfterEnv": [
+      "../../foundation/src/jest/setupAfterEnv.mjs"
     ]
-  },
-  "version": "0.0.0-test.1"
+  }
 }

package/src/attributes.ts

@@ -14,36 +14,41 @@
  * @see {@link https://opentelemetry.io/docs/specs/semconv/general/attribute-naming/}
  */
 
+/** The host of an HTTP request */
+export const HTTP_REQUEST_HOST = 'http.header.request.host';
+export const HTTP_RESPONSE_STATUS_CODE = 'http.response.status_code';
+
 /** The Aztec network identifier */
 export const NETWORK_NAME = 'aztec.network_name';
 
+export const AZTEC_NODE_ROLE = 'aztec.node_role';
+export const AZTEC_ROLLUP_VERSION = 'aztec.rollup_version';
+export const AZTEC_ROLLUP_ADDRESS = 'aztec.rollup_address';
+export const AZTEC_REGISTRY_ADDRESS = 'aztec.registry_address';
+
 /**
  * The name of the protocol circuit being run (e.g. public-kernel-setup or base-rollup)
  * @see {@link @aztec/stdlib/stats:CircuitName}
  */
 export const PROTOCOL_CIRCUIT_NAME = 'aztec.circuit.protocol_circuit_name';
 
-/**
- * The type of protocol circuit being run: server or client
- */
-export const PROTOCOL_CIRCUIT_TYPE = 'aztec.circuit.protocol_circuit_type';
-
 /**
  * For an app circuit, the contract:function being run (e.g. Token:transfer)
  */
 export const APP_CIRCUIT_NAME = 'aztec.circuit.app_circuit_name';
 
-/**
- * The type of app circuit being run: server or client
- */
-export const APP_CIRCUIT_TYPE = 'aztec.circuit.app_circuit_type';
-
 /** The block archive */
 export const BLOCK_ARCHIVE = 'aztec.block.archive';
 /** The block number */
 export const BLOCK_NUMBER = 'aztec.block.number';
+/** The L2 block hash */
+export const BLOCK_HASH = 'aztec.block.hash';
 /** The slot number */
 export const SLOT_NUMBER = 'aztec.slot.number';
+/** Whether an event happened before or after a slot boundary. */
+export const SLOT_BOUNDARY_SIDE = 'aztec.slot_boundary_side';
+/** The checkpoint number */
+export const CHECKPOINT_NUMBER = 'aztec.checkpoint.number';
 /** The parent's block number */
 export const BLOCK_PARENT = 'aztec.block.parent';
 /** How many txs are being processed to build this block */
@@ -70,6 +75,8 @@ export const ERROR_TYPE = 'aztec.error_type';
 export const L1_TX_TYPE = 'aztec.l1.tx_type';
 /** The L1 address of the entity that sent a transaction to L1 */
 export const L1_SENDER = 'aztec.l1.sender';
+/** The L1 address receiving rewards */
+export const COINBASE = 'aztec.coinbase';
 /** The phase of the transaction */
 export const TX_PHASE_NAME = 'aztec.tx.phase_name';
 /** The reason for disconnecting a peer */
@@ -78,24 +85,30 @@ export const P2P_GOODBYE_REASON = 'aztec.p2p.goodbye.reason';
 export const PROVING_JOB_TYPE = 'aztec.proving.job_type';
 /** The proving job id */
 export const PROVING_JOB_ID = 'aztec.proving.job_id';
-
+/** Merkle tree name */
 export const MERKLE_TREE_NAME = 'aztec.merkle_tree.name';
 /** The prover-id in a root rollup proof. */
 export const ROLLUP_PROVER_ID = 'aztec.rollup.prover_id';
 /** Whether the proof submission was timed out (delayed more than 20 min) */
 export const PROOF_TIMED_OUT = 'aztec.proof.timed_out';
+/** Status of the validator (eg proposer, in-committee, none) */
+export const VALIDATOR_STATUS = 'aztec.validator_status';
 
 export const P2P_ID = 'aztec.p2p.id';
 export const P2P_REQ_RESP_PROTOCOL = 'aztec.p2p.req_resp.protocol';
-export const P2P_REQ_RESP_BATCH_REQUESTS_COUNT = 'aztec.p2p.req_resp.batch_requests_count';
+/** The state of a peer (Healthy, Disconnect, Banned) */
+export const P2P_PEER_SCORE_STATE = 'aztec.p2p.peer_score_state';
 export const POOL_NAME = 'aztec.pool.name';
 
+export const PEER_ID = 'aztec.p2p.peer_id';
+
 export const SEQUENCER_STATE = 'aztec.sequencer.state';
 
 export const SIMULATOR_PHASE = 'aztec.simulator.phase';
 export const TARGET_ADDRESS = 'aztec.address.target';
 export const SENDER_ADDRESS = 'aztec.address.sender';
 export const MANA_USED = 'aztec.mana.used';
+export const TOTAL_INSTRUCTIONS = 'aztec.total_instructions';
 
 /** Whether a sync process is the initial run, which is usually slower than iterative ones. */
 export const INITIAL_SYNC = 'aztec.initial_sync';
@@ -113,3 +126,37 @@ export const GAS_DIMENSION = 'aztec.gas_dimension';
 export const WORLD_STATE_REQUEST_TYPE = 'aztec.world_state_request';
 
 export const NODEJS_EVENT_LOOP_STATE = 'nodejs.eventloop.state';
+
+export const TOPIC_NAME = 'aztec.gossip.topic_name';
+
+/** The reason a transaction was evicted from the tx pool */
+export const TX_POOL_EVICTION_REASON = 'aztec.mempool.eviction_reason';
+
+export const TX_COLLECTION_METHOD = 'aztec.tx_collection.method';
+
+/** Scope of L1 transaction (sequencer, prover, or other) */
+export const L1_TX_SCOPE = 'aztec.l1_tx.scope';
+
+/** Generic error type attribute */
+export const IS_COMMITTEE_MEMBER = 'aztec.is_committee_member';
+
+/** Fisherman fee analysis strategy identifier */
+export const FISHERMAN_FEE_STRATEGY_ID = 'aztec.fisherman.strategy_id';
+
+/** Whether the analyzed block reached 100% blob capacity */
+export const BLOCK_FULL = 'aztec.block_full';
+
+/** The L1 transaction target for block proposal */
+export const L1_BLOCK_PROPOSAL_TX_TARGET = 'aztec.l1.block_proposal_tx_target';
+
+/** Whether tracing methods were used to extract block proposal data */
+export const L1_BLOCK_PROPOSAL_USED_TRACE = 'aztec.l1.block_proposal_used_trace';
+
+/** HA signer duty type (e.g., BLOCK_PROPOSAL, CHECKPOINT_ATTESTATION) */
+export const HA_DUTY_TYPE = 'aztec.ha_signer.duty_type';
+
+/** HA signer node identifier */
+export const HA_NODE_ID = 'aztec.ha_signer.node_id';
+
+/** The address of an attester (validator) participating in consensus */
+export const ATTESTER_ADDRESS = 'aztec.attester.address';

package/src/bench.ts

@@ -1,12 +1,14 @@
+import { createLogger } from '@aztec/foundation/log';
+
 import type { BatchObservableCallback, Context, MetricOptions, Observable, ValueType } from '@opentelemetry/api';
 
+import type { MetricDefinition } from './metrics.js';
 import { NoopTracer } from './noop.js';
 import type {
   AttributesType,
   Gauge,
   Histogram,
   Meter,
-  MetricsType,
   ObservableGauge,
   ObservableUpDownCounter,
   TelemetryClient,
@@ -29,6 +31,14 @@ export type BenchmarkMetricsType = {
 export class BenchmarkTelemetryClient implements TelemetryClient {
   private meters: InMemoryPlainMeter[] = [];
 
+  constructor() {
+    const log = createLogger('telemetry:client');
+    log.info(`Using benchmark telemetry client`);
+  }
+
+  setExportedPublicTelemetry(_prefixes: string[]): void {}
+  setPublicTelemetryCollectFrom(_roles: string[]): void {}
+
   getMeter(name: string): Meter {
     const meter = new InMemoryPlainMeter(name);
     this.meters.push(meter);
@@ -51,6 +61,14 @@ export class BenchmarkTelemetryClient implements TelemetryClient {
     return true;
   }
 
+  getTraceContext(): string | undefined {
+    return undefined;
+  }
+
+  extractPropagatedContext() {
+    return undefined;
+  }
+
   getMeters(): BenchmarkMetricsType {
     return this.meters;
   }
@@ -69,30 +87,34 @@ class InMemoryPlainMeter implements Meter {
     this.metrics.forEach(metric => metric.clear());
   }
 
-  createGauge(name: MetricsType, options?: MetricOptions | undefined): Gauge {
-    return this.createMetric('gauge', name, options);
+  createGauge(metric: MetricDefinition): Gauge {
+    return this.createMetric('gauge', metric);
   }
 
-  createObservableGauge(name: MetricsType, options?: MetricOptions | undefined): ObservableGauge {
-    return this.createMetric('gauge', name, options);
+  createObservableGauge(metric: MetricDefinition): ObservableGauge {
+    return this.createMetric('gauge', metric);
   }
 
-  createHistogram(name: MetricsType, options?: MetricOptions | undefined): Histogram {
-    return this.createMetric('histogram', name, options);
+  createHistogram(metric: MetricDefinition, _extraOptions?: Partial<MetricOptions>): Histogram {
+    return this.createMetric('histogram', metric);
   }
 
-  createUpDownCounter(name: MetricsType, options?: MetricOptions | undefined): UpDownCounter {
-    return this.createMetric('counter', name, options);
+  createUpDownCounter(metric: MetricDefinition): UpDownCounter {
+    return this.createMetric('counter', metric);
   }
 
-  createObservableUpDownCounter(name: MetricsType, options?: MetricOptions | undefined): ObservableUpDownCounter {
-    return this.createMetric('counter', name, options);
+  createObservableUpDownCounter(metric: MetricDefinition): ObservableUpDownCounter {
+    return this.createMetric('counter', metric);
   }
 
-  private createMetric(type: 'gauge' | 'counter' | 'histogram', name: string, options?: MetricOptions) {
-    const metric = new InMemoryPlainMetric(type, name, options);
-    this.metrics.push(metric);
-    return metric;
+  private createMetric(type: 'gauge' | 'counter' | 'histogram', metric: MetricDefinition) {
+    const m = new InMemoryPlainMetric(type, metric.name, {
+      description: metric.description,
+      unit: metric.unit,
+      valueType: metric.valueType,
+    });
+    this.metrics.push(m);
+    return m;
   }
 
   addBatchObservableCallback(

package/src/config.ts

@@ -1,41 +1,51 @@
-import { type ConfigMappingsType, getConfigFromMappings } from '@aztec/foundation/config';
+import {
+  type ConfigMappingsType,
+  booleanConfigHelper,
+  getConfigFromMappings,
+  numberConfigHelper,
+} from '@aztec/foundation/config';
 
 export interface TelemetryClientConfig {
   metricsCollectorUrl?: URL;
+  publicMetricsCollectorUrl?: URL;
+  publicIncludeMetrics: string[];
+  publicMetricsOptOut: boolean;
+  publicMetricsCollectFrom: string[];
   tracesCollectorUrl?: URL;
   logsCollectorUrl?: URL;
   otelCollectIntervalMs: number;
   otelExportTimeoutMs: number;
-  otelExcludeMetrics?: string[];
+  otelExcludeMetrics: string[];
+  otelIncludeMetrics: string[];
+  otelMinTraceDurationMs: number;
+  otelBspMaxQueueSize: number;
 }
 
 export const telemetryClientConfigMappings: ConfigMappingsType<TelemetryClientConfig> = {
   metricsCollectorUrl: {
     env: 'OTEL_EXPORTER_OTLP_METRICS_ENDPOINT',
     description: 'The URL of the telemetry collector for metrics',
-    parseEnv: (val: string) => val && new URL(val),
+    parseEnv: (val: string) => new URL(val),
   },
   tracesCollectorUrl: {
     env: 'OTEL_EXPORTER_OTLP_TRACES_ENDPOINT',
     description: 'The URL of the telemetry collector for traces',
-    parseEnv: (val: string) => val && new URL(val),
+    parseEnv: (val: string) => new URL(val),
   },
   logsCollectorUrl: {
     env: 'OTEL_EXPORTER_OTLP_LOGS_ENDPOINT',
     description: 'The URL of the telemetry collector for logs',
-    parseEnv: (val: string) => val && new URL(val),
+    parseEnv: (val: string) => new URL(val),
   },
   otelCollectIntervalMs: {
     env: 'OTEL_COLLECT_INTERVAL_MS',
     description: 'The interval at which to collect metrics',
-    defaultValue: 60000, // Default extracted from otel client
-    parseEnv: (val: string) => parseInt(val),
+    ...numberConfigHelper(60000),
   },
   otelExportTimeoutMs: {
     env: 'OTEL_EXPORT_TIMEOUT_MS',
     description: 'The timeout for exporting metrics',
-    defaultValue: 30000, // Default extracted from otel client
-    parseEnv: (val: string) => parseInt(val),
+    ...numberConfigHelper(30000),
   },
   otelExcludeMetrics: {
     env: 'OTEL_EXCLUDE_METRICS',
@@ -49,6 +59,63 @@ export const telemetryClientConfigMappings: ConfigMappingsType<TelemetryClientCo
         : [],
     defaultValue: [],
   },
+  otelMinTraceDurationMs: {
+    env: 'OTEL_MIN_TRACE_DURATION_MS',
+    description: 'The minimum successful trace duration to export in milliseconds. Set to 0 to export all traces.',
+    ...numberConfigHelper(10),
+  },
+  otelBspMaxQueueSize: {
+    env: 'OTEL_BSP_MAX_QUEUE_SIZE',
+    description: 'The maximum number of completed spans to queue before export.',
+    ...numberConfigHelper(2048),
+  },
+  otelIncludeMetrics: {
+    env: 'OTEL_INCLUDE_METRICS',
+    description: 'A list of metric prefixes to include in export (ignored if OTEL_EXCLUDE_METRICS is set)',
+    parseEnv: (val: string) =>
+      val
+        ? val
+            .split(',')
+            .map(s => s.trim())
+            .filter(s => s.length > 0)
+        : [],
+    defaultValue: [],
+  },
+
+  publicMetricsCollectorUrl: {
+    env: 'PUBLIC_OTEL_EXPORTER_OTLP_METRICS_ENDPOINT',
+    description: 'A URL to publish a subset of metrics for public consumption',
+    parseEnv: (val: string) => new URL(val),
+  },
+  publicMetricsCollectFrom: {
+    env: 'PUBLIC_OTEL_COLLECT_FROM',
+    description: 'The role types to collect metrics from',
+    parseEnv: (val: string) =>
+      val
+        ? val
+            .split(',')
+            .map(s => s.trim())
+            .filter(s => s.length > 0)
+        : [],
+    defaultValue: [],
+  },
+  publicIncludeMetrics: {
+    env: 'PUBLIC_OTEL_INCLUDE_METRICS',
+    description: 'A list of metric prefixes to publicly export',
+    parseEnv: (val: string) =>
+      val
+        ? val
+            .split(',')
+            .map(s => s.trim())
+            .filter(s => s.length > 0)
+        : [],
+    defaultValue: [],
+  },
+  publicMetricsOptOut: {
+    env: 'PUBLIC_OTEL_OPT_OUT',
+    description: 'Whether to opt out of sharing optional telemetry',
+    ...booleanConfigHelper(true),
+  },
 };
 
 export function getConfigEnvVars(): TelemetryClientConfig {

package/src/index.ts

@@ -4,6 +4,7 @@ export * as Attributes from './attributes.js';
 export * from './with_tracer.js';
 export * from './prom_otel_adapter.js';
 export * from './lmdb_metrics.js';
+export * from './l1_metrics.js';
 export * from './wrappers/index.js';
 export * from './start.js';
 export * from './otel_propagation.js';

package/src/l1_metrics.ts

@@ -0,0 +1,65 @@
+import type { EthAddress } from '@aztec/foundation/eth-address';
+
+import { type Chain, type FallbackTransport, type Hex, type HttpTransport, type PublicClient, formatEther } from 'viem';
+
+import { L1_SENDER } from './attributes.js';
+import { L1_BALANCE_ETH, L1_BLOB_BASE_FEE_WEI, L1_BLOCK_HEIGHT, L1_GAS_PRICE_WEI } from './metrics.js';
+import type { BatchObservableResult, Meter, ObservableGauge } from './telemetry.js';
+
+export class L1Metrics {
+  private l1BlockHeight: ObservableGauge;
+  private l1BalanceEth: ObservableGauge;
+  private gasPriceWei: ObservableGauge;
+  private blobBaseFeeWei: ObservableGauge;
+  private addresses: Hex[];
+
+  constructor(
+    private meter: Meter,
+    private client: PublicClient<FallbackTransport<HttpTransport[]>, Chain>,
+    addresses: EthAddress[],
+  ) {
+    this.l1BlockHeight = meter.createObservableGauge(L1_BLOCK_HEIGHT);
+    this.l1BalanceEth = meter.createObservableGauge(L1_BALANCE_ETH);
+    this.gasPriceWei = meter.createObservableGauge(L1_GAS_PRICE_WEI);
+    this.blobBaseFeeWei = meter.createObservableGauge(L1_BLOB_BASE_FEE_WEI);
+
+    this.addresses = addresses.map(addr => addr.toString());
+  }
+
+  start() {
+    this.meter.addBatchObservableCallback(this.observe, [this.l1BalanceEth, this.l1BlockHeight]);
+  }
+
+  stop() {
+    this.meter.removeBatchObservableCallback(this.observe, [this.l1BalanceEth, this.l1BlockHeight]);
+  }
+
+  private observe = async (observer: BatchObservableResult) => {
+    const blockNumber = await this.client.getBlockNumber();
+    const ethBalances = await Promise.all(
+      this.addresses.map(address =>
+        this.client.getBalance({
+          address,
+          blockNumber,
+        }),
+      ),
+    );
+
+    const gasPrice = await this.client.getGasPrice();
+    const blobFee = await this.client.getBlobBaseFee();
+
+    observer.observe(this.l1BlockHeight, Number(blockNumber));
+    observer.observe(this.gasPriceWei, Number(gasPrice));
+    observer.observe(this.blobBaseFeeWei, Number(blobFee));
+
+    for (let i = 0; i < ethBalances.length; i++) {
+      const wei = ethBalances[i];
+      const address = this.addresses[i];
+      const eth = parseFloat(formatEther(wei, 'wei'));
+
+      observer.observe(this.l1BalanceEth, eth, {
+        [L1_SENDER]: address,
+      });
+    }
+  };
+}

package/src/lmdb_metrics.ts

@@ -1,36 +1,35 @@
 import * as Metrics from './metrics.js';
-import {
-  type AttributesType,
-  type BatchObservableResult,
-  type Meter,
-  type ObservableGauge,
-  ValueType,
-} from './telemetry.js';
+import type { AttributesType, BatchObservableResult, Meter, ObservableGauge } from './telemetry.js';
 
-export type LmdbStatsCallback = () => Promise<{ mappingSize: number; numItems: number; actualSize: number }>;
+export type LmdbStatsCallback = () => Promise<{
+  mappingSize: number;
+  physicalFileSize: number;
+  numItems: number;
+  actualSize: number;
+}>;
 
 export class LmdbMetrics {
   private dbMapSize: ObservableGauge;
+  private dbPhysicalFileSize: ObservableGauge;
   private dbUsedSize: ObservableGauge;
   private dbNumItems: ObservableGauge;
 
-  constructor(meter: Meter, private attributes?: AttributesType, private getStats?: LmdbStatsCallback) {
-    this.dbMapSize = meter.createObservableGauge(Metrics.DB_MAP_SIZE, {
-      description: 'LMDB Map Size',
-      valueType: ValueType.INT,
-      unit: 'By',
-    });
-    this.dbUsedSize = meter.createObservableGauge(Metrics.DB_USED_SIZE, {
-      description: 'LMDB Used Size',
-      valueType: ValueType.INT,
-      unit: 'By',
-    });
-    this.dbNumItems = meter.createObservableGauge(Metrics.DB_NUM_ITEMS, {
-      description: 'LMDB Num Items',
-      valueType: ValueType.INT,
-    });
+  constructor(
+    meter: Meter,
+    private attributes?: AttributesType,
+    private getStats?: LmdbStatsCallback,
+  ) {
+    this.dbMapSize = meter.createObservableGauge(Metrics.DB_MAP_SIZE);
+    this.dbPhysicalFileSize = meter.createObservableGauge(Metrics.DB_PHYSICAL_FILE_SIZE);
+    this.dbUsedSize = meter.createObservableGauge(Metrics.DB_USED_SIZE);
+    this.dbNumItems = meter.createObservableGauge(Metrics.DB_NUM_ITEMS);
 
-    meter.addBatchObservableCallback(this.recordDBMetrics, [this.dbMapSize, this.dbUsedSize, this.dbNumItems]);
+    meter.addBatchObservableCallback(this.recordDBMetrics, [
+      this.dbMapSize,
+      this.dbPhysicalFileSize,
+      this.dbUsedSize,
+      this.dbNumItems,
+    ]);
   }
 
   private recordDBMetrics = async (observable: BatchObservableResult) => {
@@ -39,6 +38,7 @@ export class LmdbMetrics {
     }
     const metrics = await this.getStats();
     observable.observe(this.dbMapSize, metrics.mappingSize, this.attributes);
+    observable.observe(this.dbPhysicalFileSize, metrics.physicalFileSize, this.attributes);
     observable.observe(this.dbNumItems, metrics.numItems, this.attributes);
     observable.observe(this.dbUsedSize, metrics.actualSize, this.attributes);
   };

package/src/metric-utils.ts

@@ -0,0 +1,75 @@
+import type { AttributeValue, MetricOptions } from '@opentelemetry/api';
+
+import type { MetricDefinition } from './metrics.js';
+import type { AllowedAttributeNames, Meter, MetricAttributesType, UpDownCounter } from './telemetry.js';
+
+/** Extracts OpenTelemetry MetricOptions from a MetricDefinition */
+export function toMetricOptions(def: MetricDefinition): MetricOptions {
+  return {
+    description: def.description,
+    unit: def.unit,
+    valueType: def.valueType,
+  };
+}
+
+/** A mapping of attribute keys to their possible values */
+export type AttributeValuesMap = Partial<Record<AllowedAttributeNames, AttributeValue[]>>;
+
+/**
+ * Expands an attribute values map into all combinations of attribute objects.
+ * Example: { status: ['ok', 'fail'], type: ['a', 'b'] } =>
+ *   [{ status: 'ok', type: 'a' }, { status: 'ok', type: 'b' }, { status: 'fail', type: 'a' }, { status: 'fail', type: 'b' }]
+ */
+export function expandAttributeCombinations(attrMap: AttributeValuesMap): MetricAttributesType[] {
+  const keys = Object.keys(attrMap) as AllowedAttributeNames[];
+  if (keys.length === 0) {
+    return [{}];
+  }
+
+  const result: MetricAttributesType[] = [];
+
+  function generate(index: number, current: MetricAttributesType) {
+    if (index === keys.length) {
+      result.push({ ...current });
+      return;
+    }
+    const key = keys[index];
+    for (const value of attrMap[key]!) {
+      current[key] = value;
+      generate(index + 1, current);
+    }
+  }
+
+  generate(0, {});
+  return result;
+}
+
+/**
+ * Creates an UpDownCounter and initializes it to 0.
+ * @param meter - The meter to create the counter on
+ * @param metric - The metric definition
+ * @param attributes - Optional attributes for initialization. Can be:
+ *   - AttributeValuesMap: mapping of attribute keys to arrays of possible values (generates cartesian product)
+ *   - MetricAttributesType[]: explicit array of attribute objects
+ *   - undefined: initializes without attributes
+ */
+export function createUpDownCounterWithDefault(
+  meter: Meter,
+  metric: MetricDefinition,
+  attributes: AttributeValuesMap | MetricAttributesType[] | undefined = undefined,
+): UpDownCounter {
+  const counter = meter.createUpDownCounter(metric);
+  if (attributes === undefined) {
+    counter.add(0);
+  } else if (Array.isArray(attributes)) {
+    for (const attrs of attributes) {
+      counter.add(0, attrs);
+    }
+  } else {
+    const combinations = expandAttributeCombinations(attributes);
+    for (const attrs of combinations) {
+      counter.add(0, attrs);
+    }
+  }
+  return counter;
+}