Skip to main content

GetMetrics

Retrieve the current metric values.

Any authenticated user can call this command; no additional CRUD permission or input/output blobs are required.

Parameters​

Parameter

Type / required

Default and behavior

format

string / optional

Defaults to json. Allowed: json or prometheus.

metrics

array of objects / optional

Omitted or empty: all metric families. Otherwise select the named families and optional complete label sets.

Each metrics element is an object with these fields:

Parameter

Type / required

Default and behavior

family

string / required

Exact metric family name; no default. Unknown names select no family.

labels

array of string maps / optional

Omitted or empty: all series in the family. Each object must exactly match the complete label set, including values, of a series. Multiple objects select alternative complete sets.

A label filter is exact, not a subset match. For a series with both method and status labels, filtering only method does not select that series. An empty object in labels selects a series without labels.

Response and recovery​

Success returns status: 0, version (the server version), and values. For json, values contains the metric families and series. Floating-point values are strings and may be "inf", "-inf", or "nan"; integer counts remain JSON integers. For prometheus, values is a string in Prometheus text exposition format. Unknown family names or unmatched label sets give a successful result without those metrics.

Invalid formats, missing family names, or non-string label values fail validation; correct the selector. See Responses for authentication and validation error envelopes.

Details​

A metric represents a single specific measurable phenomenon such as the size of a database or the number of queries that have run. Metrics come in a variety of types:

  • A counter is a single cumulative value that can only increase over time. As their name implies, counters can be used to ‘count’ discrete events as they occur, for example the number of queries received. The value of a counter reflects the amount accumulated since the ApertureDB process launched.

  • A gauge is a numerical value that can go up or down. The value of a gauge generally reflects some current state, for example the length of a queue.

  • A histogram provides a breakdown of discrete samples into buckets. It also includes a ‘count’ (counter) and ‘sum’ (gauge) representing the total number of samples taken and sum of all sample values respectively. Histograms are used to describe the distribution of events according to their size, such as query processing times or response sizes.

  • A summary is similar to a histogram but instead of fixed buckets it computes running quantiles over a sliding time window. Summaries are more expensive to compute than other metric types and are used less frequently.

ApertureDB metrics are organized into families. A family describes a class of related metrics that can be compared directly with each other. Metrics within a family are differentiated using labels and must share the same type.

Query timing​

graph_read_query_seconds and graph_write_query_seconds break graph work into phases identified by the operation label. Their exec phase includes authorization. Sum the phases within these families when calculating graph work.

graph_authorization_seconds measures authorization separately, with operation="read" for read queries, operation="write" for write queries, and operation="snapshot" for identity lookups used by batching or error reporting. The read and write measurements are already included in graph execution time; do not add them to the phase totals. This family replaces the previous authorization series in the graph phase families and the earlier query_seconds{operation="process_query",suboperation="auth"} series.

Examples​

The following query returns the connection_queue_seconds histogram in JSON. The example responses use zero sample counts and sums. A running server reports its current measurements; family metadata and bucket boundaries have the structure shown here:

[{
    "GetMetrics": {
        "format": "json",
        "metrics": [{
            "family": "connection_queue_seconds"
        }]
    }
}]

Successful response:

[{
    "GetMetrics": {
        "status": 0,
        "values": {
            "families": [{
                "help": "Time spent in the connection queue, in seconds",
                "metrics": [{
                    "buckets": [{
                        "count": 0,
                        "max": "0.0001"
                    }, {
                        "count": 0,
                        "max": "0.001"
                    }, {
                        "count": 0,
                        "max": "0.01"
                    }, {
                        "count": 0,
                        "max": "0.1"
                    }, {
                        "count": 0,
                        "max": "1"
                    }, {
                        "count": 0,
                        "max": "10"
                    }, {
                        "count": 0,
                        "max": "inf"
                    }],
                    "count": 0,
                    "sum": "0"
                }],
                "name": "connection_queue_seconds",
                "type": "Histogram"
            }]
        },
        "version": "0.19.15"
    }
}]

The same metrics are available in Prometheus text format:

[{
    "GetMetrics": {
        "format": "prometheus",
        "metrics": [{
            "family": "connection_queue_seconds"
        }]
    }
}]
[{
    "GetMetrics": {
        "status": 0,
        "values": "# HELP connection_queue_seconds Time spent in the connection queue, in seconds\n# TYPE connection_queue_seconds histogram\nconnection_queue_seconds_count 0\nconnection_queue_seconds_sum 0\nconnection_queue_seconds_bucket{le=\"0.0001\"} 0\nconnection_queue_seconds_bucket{le=\"0.001\"} 0\nconnection_queue_seconds_bucket{le=\"0.01\"} 0\nconnection_queue_seconds_bucket{le=\"0.1\"} 0\nconnection_queue_seconds_bucket{le=\"1\"} 0\nconnection_queue_seconds_bucket{le=\"10\"} 0\nconnection_queue_seconds_bucket{le=\"+Inf\"} 0\n",
        "version": "0.19.15"
    }
}]

The following are the metric families exposed by ApertureDB.

  • commands_per_query : Number of commands per ApertureDB query

  • user_command_total : Number of commands executed by a user

  • client_connection_seconds : The time taken to establish and/or destroy a client connection, in seconds

  • connection_failed_attempts : The number of connection attempts that failed to negotiate protocol

  • connection_queue_seconds : Time spent in the connection queue, in seconds

  • cpu_cycles_total : Elapsed CPU cycles

  • page_faults_total : The number of page faults encountered by ApertureDB

  • memory_bytes : Bytes of memory in use

  • storage_graph_bytes : Bytes of storage used for graph

  • storage_images_bytes : Bytes of storage used for images

  • storage_videos_bytes : Bytes of storage used for videos

  • storage_blobs_bytes : Bytes of storage used for blobs

  • storage_total_bytes : Bytes of storage used

  • num_cores : The number of concurrent threads supported on this machine

  • query_seconds : Time taken per query, in seconds

  • api_bytes_transferred : The amount of data sent and received by the ApertureDB API, in bytes

  • log_messages_total : The number of log messages generated

  • audit_events_total : The number of audit events generated

  • region_intersections_by_resulting_pieces : The number of region intersection operations performed broken down by number of convex pieces in the intersection

  • region_intersection_seconds_by_resulting_pieces : The time spent computing region intersections broken down by number of convex pieces in the intersection

  • region_intersection_pieces_total : The total number of convex pieces generated by region intersection operations that fell within the specified range

  • iou_values : The distribution of intersection over union (IoU) values computed between pairs of regions

  • region_intersection_seconds : A histogram of the time spent per region intersection operation

  • client_session_total : The number of user sessions served

  • desc_set_footprint_bytes : The total size of a descriptor set on disk

  • desc_set_index_seconds : The time taken to construct descriptor set indexes

  • desc_set_num_vectors : The number of descriptors in a descriptor set

  • desc_set_knn_seconds : The time spent performing similarity search in a descriptor set

  • desc_set_knn_throughput_total : The number of descriptor vectors input into and output by nearest neighbor similarity searches

  • graph_process_command_seconds : Time to process graph commands in seconds

  • graph_query_commands_total : Count of graph commands processed within a query

  • lmdb_page_size_bytes : The size in bytes of a single LMDB page

  • lmdb_depth : The current maximum depth (height) of the LMDB b-tree

  • lmdb_pages : The current number of pages in the LMDB B-tree

  • lmdb_entries : The current number of data items in the LMDB B-tree

  • memory_heap_allocated_bytes_total : The total number of bytes of heap memory allocated

  • memory_heap_freed_bytes_total : The total number of bytes of heap memory deallocated

  • auth_lock_seconds : The amount of time spent within and/or waiting for an authentication lock.

  • query_handlers : The number of individual query handlers.

  • page_size : The size of a memory page, in bytes.

  • graph_filter_seconds : The time taken processing graph filters, in seconds.

  • graph_filter_entities_total : The number of entities processed by graph filters.

  • graph_read_query_seconds : Read graph operations in seconds

  • graph_write_query_seconds : Write graph operations in seconds

  • graph_authorization_seconds : Authorization time within graph execution or snapshot identity lookup

  • graph_txns_behind : Transactions this node is behind the cluster, as of its last sync