Welcome to the Meilisearch specifications!

# Metrics API

This endpoint is currently experimental.

This means that it can break at any time between two minor versions as long as it is not stabilized.

# 1. Summary

This specification describes the metrics API endpoint with the exhaustive list of returned metrics.

The endpoint returns observability data to monitor a Meilisearch instance using Prometheus (opens new window).

# 2. Motivation

Improve the capabilities of a Meilisearch instance regarding observability and ease its integration into monitoring stacks.

# 3. Functional Specification

# 3.1. Activating the feature

By default, the /metrics endpoint is not accessible. To activate it, the --experimental-enable-metrics CLI option or MEILI_EXPERIMENTAL_ENABLE_METRICS env var must be specified at launch. See Instance Options

# 3.2. metrics API resource definition

Prometheus metrics format is text-based and line-oriented. Lines are separated by a line feed character (n).

A metric is composed of several fields:

  • # HELP metadata
  • # TYPE metadata
  • Metric name
  • Current metric value

Meilisearch returns the metrics specified in the table below.

Name Type
meilisearch_http_requests_total counter
meilisearch_http_response_time_seconds histogram
meilisearch_db_size_bytes gauge
meilisearch_used_db_size_bytes gauge
meilisearch_index_docs_count gauge
meilisearch_index_count gauge
meilisearch_nb_tasks counter
meilisearch_last_update gauge
meilisearch_is_indexing gauge

# 3.2.1 meilisearch_http_requests_total

Returns the number of times an API resource is accessed.

# HELP http_requests_total HTTP requests total
# TYPE http_requests_total counter
meilisearch_http_requests_total{method=":httpMethod",path=":resourcePath"} :numberOfRequest

# 3.2.2. meilisearch_http_response_time_seconds

Returns a time histogram showing the number of times an API resource call goes into a time bucket (expressed in second).

# HELP http_response_time_seconds HTTP response times
# TYPE http_response_time_seconds histogram
http_response_time_seconds_bucket{method=":httpMethod",path=":resourcePath",le="0.0005"} :numberOfRequest
http_response_time_seconds_bucket{method=":httpMethod",path=":resourcePath",le="0.0008"} :numberOfRequest
http_response_time_seconds_bucket{method=":httpMethod",path=":resourcePath",le="0.00085"} :numberOfRequest
http_response_time_seconds_bucket{method=":httpMethod",path=":resourcePath",le="0.0009"} :numberOfRequest
http_response_time_seconds_bucket{method=":httpMethod",path=":resourcePath",le="0.00095"} :numberOfRequest
http_response_time_seconds_bucket{method=":httpMethod",path=":resourcePath",le="0.001"} :numberOfRequest
http_response_time_seconds_bucket{method=":httpMethod",path=":resourcePath",le="0.00105"} :numberOfRequest
http_response_time_seconds_bucket{method=":httpMethod",path=":resourcePath",le="0.0011"} :numberOfRequest
http_response_time_seconds_bucket{method=":httpMethod",path=":resourcePath",le="0.00115"} :numberOfRequest
http_response_time_seconds_bucket{method=":httpMethod",path=":resourcePath",le="0.0012"} :numberOfRequest
http_response_time_seconds_bucket{method=":httpMethod",path=":resourcePath",le="0.0015"} :numberOfRequest
http_response_time_seconds_bucket{method=":httpMethod",path=":resourcePath",le="0.002"} :numberOfRequest
http_response_time_seconds_bucket{method=":httpMethod",path=":resourcePath",le="0.003"} :numberOfRequest
http_response_time_seconds_bucket{method=":httpMethod",path=":resourcePath",le="1"} :numberOfRequest
http_response_time_seconds_bucket{method=":httpMethod",path=":resourcePath",le="+Inf"} :numberOfRequest
http_response_time_seconds_sum{method=":httpMethod",path=":resourcePath"} :numberOfRequest
meilisearch_http_response_time_seconds_count{method=":httpMethod",path=":resourcePath"} :numberOfRequest

# 3.2.3. meilisearch_db_size_bytes

Returns the “real” size of the database on disk in bytes. It includes all the lmdb memory mapped files plus all the files contained in the data.ms directory (mainly the updates files that were not processed yet).

# HELP meilisearch_db_size_bytes Meilisearch Db Size In Bytes
# TYPE meilisearch_db_size_bytes gauge
meilisearch_db_size_bytes :databaseSizeInBytes

# 3.2.4. meilisearch_used_db_size_bytes

Returns the size of the database actually used by meilisearch in bytes. Include all the same files as meilisearch_db_size_bytes except that when it comes to an LMDB database, we only count the pages used by meilisearch. This means if you see a large gap between both metrics, adding documents will probably re-use freed pages instead of growing meilisearch_db_size_bytes.

# HELP meilisearch_used_db_size_bytes Meilisearch Used DB Size In Bytes
# TYPE meilisearch_used_db_size_bytes gauge
meilisearch_used_db_size_bytes :databaseSizeInBytes

# 3.2.5. meilisearch_index_docs_count

Returns the number of documents for an index.

# HELP meilisearch_index_docs_count Meilisearch Index Docs Count
# TYPE meilisearch_index_docs_count gauge
meilisearch_index_docs_count{index=":indexUid"} :numberOfDocuments

# 3.2.6. meilisearch_index_count

Returns the total number of indexes for the Meilisearch instance.

# HELP meilisearch_index_count Meilisearch Index Count
# TYPE meilisearch_index_count gauge
meilisearch_index_count :numberOfIndex

# 3.2.7. meilisearch_nb_tasks

Returns the total number of tasks for the Meilisearch instance parametrized by the kind of task and its value (see the table below).

# HELP meilisearch_nb_tasks Meilisearch Number of tasks
# TYPE meilisearch_nb_tasks gauge
meilisearch_nb_tasks{kind=":kind",value=":value"} :number

Here is a list of available kind and associated values:

Kind values
indexes Any created indexes
statuses Any task statuses (i.e.: succeeded, failed, enqueued, etc...)
types Any task types (i.e.: documentAdditionOrUpdate, settingsUpdate, etc...)

# 3.2.8. meilisearch_last_update

Returns the timestamp of the last update.

# HELP meilisearch_last_update Meilisearch Last Update
# TYPE meilisearch_last_update gauge
meilisearch_last_update :unixTimestamp

# 3.2.8. meilisearch_is_indexing

Returns 1 if Meilisearch is indexing or 0 if not.

# HELP meilisearch_is_indexing Meilisearch Is Indexing
# TYPE meilisearch_is_indexing gauge
meilisearch_is_indexing :isIndexing

# 3.3. API Endpoints Definition

# 3.3.1. GET - /metrics

Fetch the metrics of the Meilisearch instance.

200 - Response body example

# HELP meilisearch_database_size MeiliSearch Stats DbSize
# TYPE meilisearch_database_size gauge
meilisearch_database_size 1097728
# HELP meilisearch_docs_count MeiliSearch Stats Docs Count
# TYPE meilisearch_docs_count gauge
meilisearch_docs_count{index="movies"} 807
meilisearch_docs_count{index="movies_2"} 0
# HELP meilisearch_total_index MeiliSearch Stats Index Count
# TYPE meilisearch_total_index gauge
meilisearch_total_index 2

# 3.3.2. Errors

  • 🔴 If --experimental-enable-metrics CLI option / MEILI_EXPERIMENTAL_ENABLE_METRICS env var is not specified at launch, the API returns a feature_not_enabled error.
# 3.3.2.1 Auth Errors

If a master key is used to secure a Meilisearch instance, the auth layer returns the following errors:

  • 🔴 Accessing this route without the Authorization header returns a missing_authorization_header error.
  • 🔴 Accessing this route with a key that does not have the permission metrics.get (i.e. other than the master key) returns an invalid_api_key error.
  • 🔴 Accessing this route with a key that has a restriction on the indexes returns an invalid_api_key error.

# 4. Technical Details

N/A

# 5. Future Possibilities

  • Merge /stats with /metrics. A header could specify the preferred format. e.g application/json (similar to actual stats resource) or text/plain (Prometheus)

← Compression headers →