Vespa Command-line Tools

This is the reference for the Vespa command-line tools.


vespa-configproxy-cmd is a status and control tool for the config proxy. The config proxy runs on all nodes as a proxy for one or more config servers. It connects to the config proxy on localhost by default.

Synopsis: vespa-configproxy-cmd -m method [args]


$ vespa-configproxy-cmd -m sources
-m method, available methods are:
cache Output the config proxy cache content (overview)
getConfig Get config (see vespa-get-config)
getmode Outputs the current mode of the config proxy
setmode Use default or memorycache - example
invalidatecache Clears the current cache in config proxy
cachefull Output the config proxy cache content (including config payload)
sources Output the config proxy's upstream config sources
updatesources Updates the config proxy's upstream config sources to the supplied ones
-p port number, optional
-s hostname, optional
-h help text and usage


vespa-feeder is a feeding client that parses JSON input as Vespa document operations and sends to a Vespa application.


vespa-get retrieves documents from a Vespa content cluster, and prints to stdout. vespa-get retrieves documents identified by the document ids passed as command line arguments. If no document ids are passed through the command line interface, ids will be read from stdin - separated by line breaks.

Synopsis: vespa-get <options> [documentid...]


-a,--trace tracelevel Trace level to use (default 0)
-c,--configid configid Use the specified config id for messagebus configuration
-f,--fieldset fieldset Retrieve the specified fields only (see Document field sets) (default '[all]')
-h,--help Show this syntax page
-i,--printids Show only identifiers of retrieved documents
-j,--jsonoutput JSON output
-l,--loadtype loadtype Load type (default "")
-n,--noretry Do not retry operation on transient errors, as is default
-p,--priority priority Priority (default 6)
-r,--route route Send request to the given messagebus route
-s,--showdocsize Show binary size of document
-t,--timeout timeout Set timeout for the request in seconds (default 0)
-u,--cluster cluster Send request to the given content cluster


vespa-get-config is a command line tool to get configuration from a config server or config proxy. By default it connects to the config proxy on localhost, fetches config from its cache and prints the config payload on stdout. Configuration is addressed using name and configId. If configId is omitted, the global and default data for that name is returned. The default port number is 19090, the config proxy's port - use 19070 to access a config server. Also check ports.

Synopsis: vespa-get-config -n defName -i configId <option> [args]


$ vespa-get-config -n container.statistics -i search/


-n config definition name, including namespace (on the form <namespace>.<name>)
-i config id, optional
-a config def schema file, optional (if you want to use another schema than known for the config server)
-m defMd5, optional
-c configMd5, optional
-t server timeout, in seconds, default value 3, optional
-w timeout, default value 10, optional
-s server hostname, default localhost, optional
-p port, default 19090, optional
-d debug mode, optional
-h help text and usage


vespa-logfmt reads Vespa log files, selects messages, and writes a formatted version of these messages to standard output. If no file argument is given, vespa-logfmt will read the last Vespa log file $VESPA_HOME/logs/vespa/vespa.log (this also works with the -f option). Otherwise, reads only the files given as arguments. To read standard input, supply a single dash ’-’ as a file argument. Refer to the logs reference.

Synopsis: vespa-logfmt [-l levellist ] [-s fieldlist ] [-p pid ] [-S service ] [-Hhost ] [-c regex ] [-m regex ] [-f ] [-N ] [-t ] [-ts ] [file …]


Display only messages with log level "event", printing a human-readable time (without any fractional seconds), the service generating the event and the event message:

$ vespa-logfmt -l event -s fmttime,service,message
[2017-09-05 06:16:16] config-sentinel  stopped/1 name="sbin/vespa-config-sentinel -c hosts/vespa-container (pid 1558)" pid=1558 exitcode=1
[2017-09-05 06:16:16] config-sentinel  starting/1 name="sbin/vespa-config-sentinel -c hosts/vespa-container (pid 1564)"
[2017-09-05 06:16:16] config-sentinel  started/1 name="config-sentinel"
[2017-09-05 06:17:00] configserver     count/1 name=configserver.failedRequests value=0
[2017-09-05 06:17:00] configserver     count/1 name=procTime value=0
[2017-09-05 06:17:00] configserver     count/1 name=configserver.requests value=0
Display messages with log levels that are not any of info, debug, or event, printing the time in seconds and microseconds, the log level, the component name, and the message text:
$ vespa-logfmt -l all-info,-debug -s level -s time,usecs,component,message -t -l -event
1504592294.738000 WARNING : No config found for name=sentinel,namespace=cloud.config,configId=hosts/vespa-container within timeout, will retry
1504592296.388000 WARNING : Request callback failed: APPLICATION_NOT_LOADED. Connection spec: tcp/localhost:19070, error message: Failed request (No application exists) from Connection { Socket[addr=/,port=37806,localport=19070] }
1504592307.949461 WARNING : config-sentinel Connection to tcp/localhost:19090 failed or timed out
1504592307.949587 WARNING : config-sentinel FRT Connection tcp/localhost:19090 suspended until 2017-09-05 06:19:07 GMT
-l levellist (--level=levellist) Filter messages by log level. By default only messages of level fatal, error, warning, and info will be included, while messages of level config, event, debug, and spam will be ignored. This option allows you to replace or modify the list of log levels to be included. levellist is a comma separated list of level names.
  • The name all may be used to add all known levels
  • You may use + or - in front of terms to add or remove from the current (or default) list of levels instead of replacing it
  • Adding term
-s fieldlist Select which fields of log messages to show. The output field order is fixed. When using this option, only the named fields will be printed. The default fields are as [-s fmttime,msecs,level,service,component,message]. The fieldlist is a comma separated list of field names. The name all may be used to add all possible fields. Prepending a minus sign will turn off display of the named field. Starting the list with a plus sign will add and remove fields from the current (or default) list of fields instead of replacing it. Using this option several times works as if the given fieldlist arguments had been concatenated into one comma-separated list. Fields:
time Print the time in seconds since the epoch. Ignored if fmttime is shown
fmttime Print the time in human-readable [YYYY-MM-DD HH:mm:ss] format. Note that the time is printed in the local timezone; to get GMT output, use env TZ=GMT vespa-logfmt
msecs Add milliseconds after the seconds in time and fmttime output. Ignored if usecs is in effect
usecs Add microseconds after the seconds in time and fmttime output
host Print the hostname field
level Print the level field (uppercased)
pid Print the pid field
service Print the service field
component Print the component field
message Print the message text field. You probably always want to add this
-p pid Select messages where the pid field matches the pid string
-S service Select messages where the service field matches the service string
-H host Select messages where the hostname field matches the host string
-c regex Select messages where the component field matches the regex, using perlre regular expression matching
-m regex Select messages where the message text field matches the regex, using perlre regular expression matching
-f Invoke tail -F to follow input file
-L (--livestream) Only useful for multi-machine setups: Invoke vespa-replicate-log-stream to follow live stream from log server, instead of reading any input file. Also implies -s +host as default.
-N Dequote quoted newlines in the message text field to an actual newline plus tab
-t Format the component field (if shown) as a fixed-width string, truncating if necessary
-ts Format the service field (if shown) as a fixed-width string, truncating if necessary


vespa-model-inspect is a tool for inspecting the topology and services of a Vespa system. Hosts, services, clusters, ports, URLs and config ids can be inspected. It can run on any machine in a Vespa cluster that is running a Vespa configuration server.

Synopsis: vespa-model-inspect [-c host | host:port] [-t tag] [-h] [-u] [-v] command


hosts Show hostnames of all hosts in the Vespa system
services Show a list of all service types in the Vespa system
clusters Show a list of all named clusters in the Vespa system
configids Show a list of all config ids in the Vespa system
filter:ports List ports matching filter options
host hostname Show host details: What services are running, and what ports have they allocated
service servicetype Show service details: What instances of the service are running, on what hosts, and what ports have they allocated
cluster clustername Show all services in the cluster, with details on hostname and allocated ports
configid configid Show all services using this configid
get-index-of servicetype host Show all indexes for instances of the service type on the given host
-c host | host:port Specify host and port (or just host) to use for getting the config that this tool displays. Default is to use the configserver. You might want to use localhost:19090 if you are on a host with a running Vespa system without a config server
-h Show usage
-t tag to filter on a port tag
-u Show URLs for services
-v Verbose mode
$ vespa-model-inspect hosts

$ vespa-model-inspect services

$ vespa-model-inspect -u service distributor
distributor @ : content
    tcp/ (MESSAGING)
distributor @ : content
    tcp/ (MESSAGING)
distributor @ : content


Use vespa-proton-cmd to send commands to a search node.

The hostspec argument is one of (port|spec|--local|--id=name)

Synopsis: vespa-proton-cmd HOSTSPEC COMMAND [ARGS]

Use vespa-model-inspect to locate the search node ADMIN RPC port:

$ vespa-model-inspect service searchnode
searchnode @ / : search
    tcp/ (FS4)
    tcp/ (TEST HACK SRMP)
$ vespa-proton-cmd 19108 triggerFlush
  OK: flush trigger enabled
Unless the -h or --help option is used, one of these commands must be present:
die Exit the proton application without cleanup
getConfigTime Get the oldest active config timestamp
getProtonStatus Get the current state of proton and its components
getState Get the current state of the search node
listDocTypes Get the current list of document types
listSchema documentType Get the current schema for the given document type
monitor Get search node state changes since last invocation
triggerFlush Tell the search node to trigger flush as soon as possible for all document types
prepareRestart Tell the search node to prepare for a restart by flushing a set of components to disk such that the time it takes to flush these components plus the time it takes to replay the transaction log after restart is as low as possible
wipeHistory Tell the search node to wipe history of previously removed fields


vespa-remove-index is a command line tool to remove index data on a Vespa search node, by wiping out selected files and subdirectories found in $VESPA_HOME/var/db/vespa/. This process is irreversible and the indexes deleted can not be recovered.

Stop services before running vespa-remove-index.

Synopsis:vespa-remove-index [-force] [-cluster name]


$ vespa-remove-index
[info] For cluster music distribution key 0 you have:
[info] 156 kilobytes of data in var/db/vespa/search/
Really to remove this vespa index? Type "yes" if you are sure ==> yes
[info] removing data:  rm -rf var/db/vespa/search/
[info] removed.
-force Do not require verification from the user before really removing index data
-cluster name Only remove data for given cluster name


vespa-route is a tool to inspect Vespa routing configurations. If file is set, it will be parsed as a feed and the output will look similar to when using Document API with trace enabled.

Synopsis: vespa-route [options] [file]


$ vespa-route
There are 5 route(s):
    1. default
    2. music
    3. music-direct
    4. music-index
    5. storage/

There are 2 hop(s):
    1. docproc/
    2. indexing
--documentmanagerconfigid <id> Sets the config id that supplies document configuration
--dump Prints the complete content of the routing table
--help Prints this help
--hop <name> Prints detailed information about hop <name>
--hops Prints a list of all available hops
--identity <id> Sets the identity of message bus
--listenport <num> Sets the port message bus will listen to
--oosserverpattern <id> Sets the out-of-service server pattern for message bus
--protocol <name> Sets the name of the protocol whose routing to inspect
--route <name> Prints detailed information about route <name>
--routes Prints a list of all available routes
--routingconfigid <id> Sets the config id that supplies the routing tables
--services Prints a list of all available services
--slobrokconfigid <id> Sets the config id that supplies the slobrok server list
--trace <num> Sets the trace level to use when visualizing route
--verify All hops and routes are verified when routing


vespa-stat is a tool to fetch statistics about a specific user, group, bucket, gid or document. vespa-stat works in two stages. The first stage is to figure out the actual buckets we want to look at. In the second stage, it can dump the located buckets. For each command line option, only the relevant documents will be dumped (the document for --document/--gid, or the user/group's documents for --user/--group). This stage can be turned on by adding --dump, but is default on for the case of --document/--gid.

Synopsis: vespa-stat [options]


$ vespa-stat --document id:my_namespace:my_search::12345678-4fb7-3797-ae9a-d4d7a4e6e085
Bucket maps to the following actual files:
	BucketInfo(BucketId(0x4000000000004800): [distributor:17] [node(idx=17,crc=0xe5ce35c7,docs=57/57,bytes=478040/478040,trusted=true,active=true,ready=true),  node(idx=15,crc=0xe5ce35c7,docs=57/57,bytes=478040/478040,trusted=true,active=true,ready=true)])

Details for BucketId(0x4000000000004800):
	Bucket information from node 15:
Persistence bucket BucketId(0x4000000000004800), partition 0
  Timestamp: 1452598747000000, Doc(id:my_namespace:my_search::12345678-4fb7-3797-ae9a-d4d7a4e6e085), gid(0x0048e840a48002b12abbb0a0), size: 101

	Bucket information from node 17:
Persistence bucket BucketId(0x4000000000004800), partition 0
  Timestamp: 1452598747000000, Doc(id:my_namespace:my_search::12345678-4fb7-3797-ae9a-d4d7a4e6e085), gid(0x0048e840a48002b12abbb0a0), size: 101
-b, --bucket <bucketid> Dump list of buckets that are contained in the given bucket, or that contain it
-d, --dump Dump list of documents for all buckets matching the selection command.
-g, --group <groupid> Dump list of buckets that can contain the given group
-h, --help Help text
-l, --gid <globalid> Dump information about one specific document, as given by the GID (implies --dump)
-o, --document <docid> Dump information about one specific document (implies --dump)
-r, --route <route> Route to send the messages to, usually the name of the storage cluster
-s, --bucketspace <space> Stat buckets within the given bucket space - if not provided, 'default' is used
-u, --user <userid> Dump list of buckets that can contain the given user


Refer to vespa-rpc-invoke.


Refer to visiting.