Skip to main content

GetMetrics

Retrieve the current metric values.

Parameters​

  • [optional] format: Set the format in which to return the metric values. Supported formats:

    • “json” (default) : Return metric values as a json object.
      Numeric values are represented as strings and may be “inf”, “-inf”, or “nan”.

    • “prometheus” : Return metric values as a string formatted for Prometheus.

  • [optional] metrics: An array of specific metrics to include in the result. By default, all metrics are returned.

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. See below for examples.

See Deprecations and migrations for metrics that help identify API migration work.

Examples​

The following shows how to obtain metrics in JSON:

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

Successful response:

[{
    "GetMetrics": {
        "status": 0,
        "values": {
            "families": [{
                "help": "Number of connections pushed onto the connection queue",
                "metrics": [{
                    "value": "2432"
                }],
                "name": "connection_queue_seconds_pushes",
                "type": "Counter"
            }, {
                "help": "Time spent in the connection queue, in seconds",
                "metrics": [{
                    "buckets": [{
                        "count": 2431,
                        "max": "0.0001"
                    }, {
                        "count": 2432,
                        "max": "0.001"
                    }, {
                        "count": 2432,
                        "max": "0.01"
                    }, {
                        "count": 2432,
                        "max": "0.1"
                    }, {
                        "count": 2432,
                        "max": "1"
                    }, {
                        "count": 2432,
                        "max": "10"
                    }, {
                        "count": 2432,
                        "max": "inf"
                    }],
                    "count": 2432,
                    "sum": "0.02971765499999999"
                }],
                "name": "connection_queue_seconds",
                "type": "Histogram"
            }]
        },
        "version": "0.15.1"
    }
}]

This is an example of retrieving the same metrics in Prometheus format:

[{
    "GetMetrics": {
        "format": "prometheus",
        "metrics": [{
            "family": "connection_queue_seconds"
        }, {
            "family": "connection_queue_seconds_pushes"
        }]
    }
}]
[{
    "GetMetrics": {
        "status": 0,
        "values": """
# HELP connection_queue_seconds_pushes Number of connections pushed onto the connection queue
# TYPE connection_queue_seconds_pushes counter
connection_queue_seconds_pushes 2935
# HELP connection_queue_seconds Time spent in the connection queue, in seconds
# TYPE connection_queue_seconds histogram
connection_queue_seconds_count 2935
connection_queue_seconds_sum 0.03495181900000004
connection_queue_seconds_bucket{le="0.0001"} 2935
connection_queue_seconds_bucket{le="0.001"} 2935
connection_queue_seconds_bucket{le="0.01"} 2935
connection_queue_seconds_bucket{le="0.1"} 2935
connection_queue_seconds_bucket{le="1"} 2935
connection_queue_seconds_bucket{le="10"} 2935
connection_queue_seconds_bucket{le="+Inf"} 2935
""",
        "version": "0.15.1"
    }
}]

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_txns_behind : Transactions this node is behind the cluster, as of its last sync