[+] 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.