Metrics

Node.js client 6.3.0 provides two levels of metrics: Stats and Extended Metrics.

Stats

Stats is an on-demand snapshot of a cluster’s thread and connection usage. To obtain Stats on an active Aerospike instance:

let stats = client.stats()

Stats contain the following properties:

• nodes: Metrics for each node.

  • name: Name of the node

  • syncConnections: Sync connections.

    • inUse: Active connections from connection pool(s) currently executing commands.
    • inPool: Initialized connections in connection pool(s) that are not currently active.
    • opened: Total number of node connections opened since node was started.
    • closed: Total number of node connections closed since node was started.

  • asyncConnections: Async connections.

    • inUse: Active connections from connection pool(s) currently executing commands.
    • inPool: Initialized connections in connection pool(s) that are not currently active.
    • opened: Total number of node connections opened since node was started.
    • closed: Total number of node connections closed since node was started.

  • pipelineConnections: Pipeline connections.

    • inUse: Active connections from connection pool(s) currently executing commands.
    • inPool: Initialized connections in connection pool(s) that are not currently active.
    • opened: Total number of node connections opened since node was started.
    • closed: Total number of node connections closed since node was started.

  • errorCount: Command error count since node was started. If the error is retryable, multiple errors per command may occur.

  • timeoutCount: Command timeout count since node was started. If the timeout is retryable (ie socketTimeout), multiple timeouts per command may occur.

  • keyBusyCount: Command timeout count since node was started. If the timeout is retryable (ie socketTimeout), multiple timeouts per command may occur.

• commands: Metrics for each async event loop.

  • inFlight: Approximate number of commands actively being processed on the event loop.
  • queued: Approximate number of commands stored on this event loop’s delay queue that have not been started yet.

Extended metrics

To use extended metrics, you must explicitly notify the client to track latency and command counts for every node. There is a performance penalty when extended metrics is enabled. To enable:

let policy: MetricsPolicy = new Aerospike.MetricsPolicy({
    reportDir: './metrics_sub_dir/example_dir',
    interval: 600 // Write metrics snapshot approximately every 600 seconds.
  }
)

await client.enableMetrics(policy)

To disable:

await client.disableMetrics()

The MetricsPolicy fields are:

• metricsListeners: Listener that handles metrics notification events. The default listener implementation writes the metrics snapshot to a file. The listener can also be overridden to send the metrics snapshot directly to OpenTelemetry.

  The following is a list of metricsListeners fields:

  • enableListener: Called when metrics have been enabled for the cluster.
  • snapshotListener: Called when a metrics snapshot has been requested for the given cluster.
  • nodeCloseListener: Called when a node is dropped from the cluster.
  • disable_listener: Called when metrics have been disabled for the cluster.

• reportDir: Directory path to write metrics log files for listeners that write logs.

• reportSizeLimit: Metrics file size soft limit, in bytes, for listeners that write logs. When reportSizeLimit is reached or exceeded, the current metrics file is closed and a new metrics file is created with a new timestamp. If reportSizeLimit is set to 0, the metrics file size is unbounded and the file is only closed when client.disableMetrics() or client.close() is called. Defaults to 0.

• interval: Number of cluster tend iterations between metrics notification events. One tend iteration is defined as config.tenderInterval (default: 1 second) plus the time to tend all nodes. Defaults to 30.

• latencyColumns: Number of elapsed time range buckets in latency histograms. Defaults to 7.

• latencyShift: Power of 2 multiple between each range bucket in latency histograms starting at column 3. The bucket units are in milliseconds. The first 2 buckets are <=1ms and >1ms. Examples:

// latency_columns=5 latency_shift=3
<=1ms >1ms >8ms >64ms >512ms
// latency_columns=7 latency_shift=2
<=1ms >1ms >4ms >16ms >64ms >256ms >1024ms

If you are using custom callbacks, then you will have access to a representation of the cluster including individual NamespaceMetrics for each node. The following data will provided as an argument to your custom callback.

• appId: Application identifier.

• clusterName: Cluster name.

• commandCount: Count of commands since client was started.

• delayQueueTimeoutCount: Count of async commands that timed out in the delay queue before the command was processed since client was started,

• invalidNodeCount: Count of node failures in the most recent cluster tend iteration.

• transactionCount: Count of transactions since client was started.

• retryCount: Count of retry since client was started.

• labels: Object containing name/value labels that is applied when exporting metrics.

• nodes: Nodes associated with the cluster.

  • node_name: Node name.

  • address: Node IP address.

  • port: Node port.

  • metrics: Namespace metrics for each node.

    • ns: Namespace name.

    • bytesIn: Bytes received from the server.

    • bytesOut: Bytes sent to the server.

    • errorCount: Count of errors since node was initialized.

    • timeoutCount: Count of timeout errors since node was initialized.

    • keyBusyCount: Count of key busy errors since node was initialized.

    • connLatency: Connection creation latency histogram.

    • writeLatency: Single record write commands latency histogram.

    • readLatency: Single record read commands latency histogram.

    • batchLatency: Batch read/write commands latency histogram.

    • queryLatency: Scan/Query commands latency histogram.

The default extended metrics file includes all as_cluster_stats fields. The fields are listed below:

• name: Cluster name.

• clientType: Type of Client (e.g. C, Java)

• clientVersion: Current Client Version

• appId: Application identifier.

• label[]: List of all name/value labels that is applied when exporting metrics.

• cpu: Current CPU usage percentage of the client process.

• mem: Current memory usage of the client process.

• invalidNodeCount: Count of commands since client was started.

• commandCount: Count of commands since client was started.

• retryCount: Count of retry since client was started.

• delayQueueTimeoutCount: Count of async commands that timed out in the delay queue before the command was processed since client was started,

• eventloop[]: Metrics for each async event loop.
  • processSize: Approximate number of commands actively being processed on the event loop.
  • queueSize: Approximate number of commands stored on this event loop’s delay queue that have not been started yet.

• node[]: Metrics for each node.

  • node_name: Node name.

  • address: Node IP address.

  • port: Node port.

  • sync: Sync connections.

    • inUse: Active connections from connection pool(s) currently executing commands.
    • inPool: Initialized connections in connection pool(s) that are not currently active.
    • opened: Total number of node connections opened since node was started.
    • closed: Total number of node connections closed since node was started.

  • async: Async connections.

    • inUse: Active connections from connection pool(s) currently executing commands.
    • inPool: Initialized connections in connection pool(s) that are not currently active.
    • opened: Total number of node connections opened since node was started.
    • closed: Total number of node connections closed since node was started.

  • metrics: Namespace metrics for each node.

    • name: Namespace name.

    • errorCount: Count of errors since node was initialized.

    • timeoutCount: Count of timeout errors since node was initialized.

    • keyBusyCount: Count of key busy errors since node was initialized.

    • bytesIn: Bytes received from the server.

    • bytesOut: Bytes sent to the server.

    • latency: Latency buckets for the following types:

      • conn: Connection creation latency.

      • write: Single record write commands.

      • read: Single record read commands.

      • batch: Batch read/write commands.

      • query: Scan/Query commands.

Extended metrics file format: <reportDir>/metrics-yyyyMMddHHmmss.log

Extended metrics file example:

2025-08-04 15:22:03 header(2) cluster[name,clientType,clientVersion,appId,label[],cpu,mem,invalidNodeCount,commandCount,retryCount,delayQueueTimeoutCount,eventloop[],node[]] label[name,value] eventloop[processSize,processSize] node[name,address,port,syncConn,asyncConn,namespace[]] conn[inUse,inPool,opened,closed] namespace[name,errors,timeouts,keyBusy,bytesIn,bytesOut,latency[]] latency(7,1)[type[l1,l2,l3...]]
2025-08-04 15:22:03 cluster[,C,7.0.4,,[],0,11707340,0,115,0,0,[[0,0]],[[A1,127.0.0.1,3000,0,0,2,1,0,100,104,4,[test,1,3,0,29307,34822,[conn[0,0,0,0,0,0,0],write[0,0,0,0,0,0,0],read[0,0,0,0,0,0,0],batch[0,0,0,0,0,0,0],query[0,0,0,0,0,0,0]],,0,0,0,2900,2567,[conn[0,0,0,0,0,0,0],write[0,0,0,0,0,0,0],read[0,0,0,0,0,0,0],batch[0,0,0,0,0,0,0],query[0,0,0,0,0,0,0]]]]]]

...