Process Management

This document covers how to manage the Vector process using various interfaces. How you manage the Vector process is largely dependent on how you installed Vector.

Administrate

Linux
YUM

Start

sudo systemctl start vector

Healthchecks

By default, Vector will perform healthchecks on all components. Health checks ensure that the downstream service is accessible and ready to accept data. This check is performed upon component initialization. If the health check fails, an error will be logged and Vector will proceed to start.

Require healthchecks

If you'd like to exit immediately upon a health check failure, you can pass the --require-healthy flag when starting Vector:

vector --config /etc/vector/vector.toml --require-healthy
Disable healthchecks

If you'd like to disable health checks you can set the healthcheck option to false for each component:

[sinks.my-sink]
type = "..."
healthcheck = false

Options

Please refer to the start command CLI reference for a comprehensive list of command line flags and options.

Stop

sudo systemctl stop vector

Graceful Shutdown

Vector is designed to gracefully shutdown within 60 seconds when a SIGTERM process signal is received. Vector will print the shutdown status every 10 seconds so that you are informed of the process. The graceful shutdown process is as follows:

  1. Stop accepting new data for all sources.
  2. Close open connections.
  3. Flush sink buffers.
  4. Exit the process with a 0 exit code.

Force Killing

If Vector is forcefully killed there is the potential to lose in-flight data. If Vector fails to shut down gracefully please report it as a bug.

Reload

systemctl kill -s HUP --kill-who=main vector.service

Automatic reload on changes

You can automatically reload Vector's configuration file when it changes by using the -w or --watch-config flag when starting Vector. This should be used with caution since it can sometimes cause surprise behavior. When possible, we recommend issuing a manual reload after you've changed configuration.

Configuration errors

When Vector is reloaded it proceeds to read the new configuration file from disk. If the file has errors it will be logged to STDOUT and ignored, preserving any previous configuration that was set. If the process exits you will not be able to restart the process since it will try to use the new, invalid, configuration file.

Graceful pipeline transitioning

Vector will perform a diff between the new and old topology to determine which changes need to be made. Deleted components be shut down first, ensuring there are no resource conflicts with new components, and then new components will be started.

Restart

sudo systemctl restart vector

Restarting is the equivalent to fully stopping and starting the Vector process. When possible, we recommend reloading Vector instead, since it will minimize downtime and disruptions.

Observe

sudo journalctl -fu vector
explain this command

Upgrade

sudo yum upgrade vector

Working upstream

Depending on your topology, you'll want update your Vector instances in a specific order. You should always start downstream and work your way upstream. This allows for incremental updating across your topology, ensuring downstream Vector instances do not receive data in formats that are unrecognized. Vector always makes a best effort to successfully process data, but there is no guarantee of this if a Vector instance is handling a data format defined by a future unknown Vector version.

Capacity planning

When updating, you'll be taking Vector instances off-line for a short period of time, and upstream data will accumulate and buffer. To avoid overloading your instances, you'll want to make sure you have enough capacity to handle the surplus of data. We recommend provisioning at least 20% of head room, on all resources, to account for spikes and updating.

How it works

Signals

SignalDescription
SIGTERMInitiates graceful shutdown process.
SIGHUPReloads configuration on the fly.

Exit Codes

A full list of exit codes can be found in the exitcodes Rust crate. The relevant codes that Vector uses are:

CodeDescription
0No error.
1Exited with error.
78Bad configuration.