• [+] expand all

/state/v1 API reference

Every service exposes the /state/v1 API - use vespa-model-inspect to find ports, see the multinode-HA sample application for practical examples.

HTTP requests

HTTP request state/v1 operation Description
GET

Service config generation

/state/v1/config

In the response, config has a mandatory generation and one or more <service> elements:

  • sentinel
  • container
  • distributor
  • logd
  • slobroks
  • servicelayer
  • proton

Note: Other configuration elements can also be added as a service. A <service> has a mandatory generation. An optional message can be returned. Example:

{
    "config": {
        "generation": 11,
        "slobroks": {
            "generation": 11,
            "message": "ok"
        }
    }
}
Service version

/state/v1/version

Returns a mandatory service version. Example:

{
    "version" : "8.43.64"
}
Service health

/state/v1/health

Returns the service status, with time, status and metrics. Metrics contains requestsPerSecond and latencySeconds, see StateHandler.

Example:

{
    "time": 1661863544346,
    "status": {
        "code": "up"
    },
    "metrics": {
        "snapshot": {
            "from": 1661863483.422,
            "to": 1661863543.38
        },
        "values": [
            {
                "name": "requestsPerSecond",
                "values": {
                    "count": 30,
                    "rate": 0.5
                }
            },
            {
                "name": "latencySeconds",
                "values": {
                    "average": 0.001,
                    "sum": 0,
                    "count": 0,
                    "last": 0.001,
                    "max": 0.001,
                    "min": 0.001,
                    "rate": 0
                }
            }
        ]
    }
}
Service metrics

/state/v1/metrics

Same as /state/v1/health, but with a full metrics set.

A metric has a name and values, and can have a description and a set of dimensions:

{
    "name": "content.proton.documentdb.matching.rank_profile.query_setup_time",
    "description": "Average time (sec) spent setting up and tearing down queries",
    "values": {
        "average": 0,
        "sum": 0,
        "count": 0,
        "rate": 0,
        "min": 0,
        "max": 0,
        "last": 0
    },
    "dimensions": {
        "documenttype": "music",
        "rankProfile": "default"
    }
}
Service metric histograms

/state/v1/metrics/histograms

See histograms for usage. The histograms are implemented using HdrHistogram, and the CSV result is what that library generates.

HTTP status codes

Non-exhaustive list of status codes:

Code Description
200 OK.

Response format

Responses are in JSON format, with the following fields:

Element Parent Type Description

config

Object Root element for /state/v1/config.

generation

config Number The generation number is the number for the config that is active in the application.

message

config String An info or error message.

version

String Vespa version.

time

Number Epoch in microseconds.

status

Object

code

status String Service status code - one of:
  • up
  • down
  • initializing

Containers with the query API enabled return initializing while waiting for content nodes to start, see example. up means that the service is fully up. Assume status down if no response. Refer to StateMonitor for implementation.

message

status String Message is optional - it is normally empty if the service is up, while it is set to a textual reason for why it is unavailable, if so.

metrics

Object Snapshot of metric values.

snapshot

metrics Object Time period for metrics snapshot.

from

snapshot Number Epoch in seconds, with microseconds fraction.

to

snapshot Number Epoch in seconds, with microseconds fraction.

values

metrics Array Array of metric objects.

name

values String Metric name.

description

values String Textual description of the metric.

dimensions

values Object Set of dimension name/value pairs.

values

values Object Set of metric values.

average

values Number Average metric value, typically sum divided by count.

sum

values Number Sum of metric values in snapshot.

count

values Number Number of times metric has been set. For instance in a metric counting number of operations done, it will give the number of operations added for that snapshot period. For a value metric, for instance latency of operations, the count will give how many times latencies have been added to the metric.

last

values Number Last metric value.

max

values Number Max metric value in snapshot.

min

values Number Min metric value in snapshot.

rate

values Number Metric rate: count divided by snapshot interval.