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
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:
- Stop accepting new data for all sources.
- Close open connections.
- Flush sink buffers.
- 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
- Logs
- Metrics
sudo journalctl -fu vector
Upgrade
sudo yum upgrade vector
Working upstream
Depending on your pipeline, 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
Signal | Description |
---|---|
SIGTERM | Initiates graceful shutdown process. |
SIGHUP | Reloads 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:
Code | Description |
---|---|
0 | No error. |
1 | Exited with error. |
78 | Bad configuration. |