The Vector command line interface
Vector is a single binary that be managed through a command line interface. This page documents all of the available flags, options, subcommands, and environment variables.
Commands
vector
The root command (no subcommand) starts Vector.
vector [FLAGS] [OPTIONS] [SUBCOMMAND] [ARGS]| Flags | Description | Environment variable | Default |
|---|---|---|---|
| --allow-empty-config | Allow the configuration to run without any components. This is useful for loading in an empty stub config that will later be replaced with actual components. Note that this is likely not useful without also watching for config file changes as described in --watch-config. | VECTOR_ALLOW_EMPTY_CONFIG | |
| --help
, -h | Prints help information | | |
| --no-graceful-shutdown-limit | Never time out while waiting for graceful shutdown after SIGINT or SIGTERM received. This is useful when you would like for Vector to attempt to send data until terminated by a SIGKILL. Overrides/cannot be set with --graceful-shutdown-limit-secs. | VECTOR_NO_GRACEFUL_SHUTDOWN_LIMIT | |
| --openssl-no-probe | Disable probing and configuration of root certificate locations on the system for OpenSSL. The probe functionality manipulates the | VECTOR_OPENSSL_NO_PROBE | |
| --quiet
, -q | Reduce detail of internal logging. Repeat to reduce further. Overrides --verbose. | | |
| --require-healthy
, -r | Exit on startup if any sinks fail healthchecks. | VECTOR_REQUIRE_HEALTHY | |
| --verbose
, -v | Enable more detailed logging. Repeat to reduce further. Overrides --quiet. | | |
| --version
, -V | Prints version information | | |
| --watch-config
, -w | Watch for changes in the configuration file and reload accordingly | VECTOR_WATCH_CONFIG | |
| Options | Description | Environment variable | Default | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| --color | Control when ANSI terminal formatting is used. Enum options
| VECTOR_COLOR | auto | ||||||||
| --config
, -c | Read configuration from one or more files. Wildcard paths are supported. If no files are
specified the default config path /etc/vector/vector.yaml is targeted. TOML, YAML and
JSON file formats are supported. The format to interpret the file with is determined from
the file extension (.yaml, .toml, .json). Vector falls back to YAML if it can’t
detect a supported format. | VECTOR_CONFIG | /etc/vector/vector.yaml | ||||||||
| --config-dir | Read configuration from files in one or more directories. The file format is detected
from the file name. Files not ending in .toml, .json, .yaml, or .yml are
ignored. | VECTOR_CONFIG_DIR | | ||||||||
| --config-json | Read configuration from one or more files. Wildcard paths are supported. JSON file
format is assumed. | VECTOR_CONFIG_JSON | | ||||||||
| --config-toml | Test configuration from one or more files. Wildcard paths are
supported. TOML file format is assumed. | VECTOR_CONFIG_TOML | | ||||||||
| --config-yaml | Read configuration from one or more files. Wildcard paths are supported. YAML file
format is assumed. | VECTOR_CONFIG_YAML | | ||||||||
| --graceful-shutdown-limit-secs | Set the duration in seconds to wait for graceful shutdown after SIGINT or SIGTERM are received. After the duration has passed, Vector will force shutdown. To never force shutdown, use --no-graceful-shutdown-limit. | VECTOR_GRACEFUL_SHUTDOWN_LIMIT_SECS | 60 | ||||||||
| --internal-log-rate-limit
, -i | Set the internal log rate limit. This limits Vector from emitting identical logs more than once over the given number of seconds. | VECTOR_INTERNAL_LOG_RATE_LIMIT | 10 | ||||||||
| --log-format | Set the logging format Enum options
| VECTOR_LOG_FORMAT | text | ||||||||
| --threads
, -t | The number of threads to use for processing. The default is the number of available cores. | VECTOR_THREADS | | ||||||||
| --watch-config-method | Method for watching config files.
| VECTOR_WATCH_CONFIG_METHOD | recommended | ||||||||
| --watch-config-poll-interval-seconds | Poll for config changes at given interval
only applicable if poll is set in --watch-config-method | VECTOR_WATCH_CONFIG_POLL_INTERVAL_SECONDS | 60 |
vector generate
Generate a Vector configuration containing a list of components
vector generate [FLAGS] [OPTIONS] [ARGUMENTS]| Flags | Description | Environment variable | Default |
|---|---|---|---|
| --fragment
, -f | Whether to skip the generation of global fields | | |
| --help
, -h | Prints help information | |
| Options | Description | Environment variable | Default |
|---|---|---|---|
| --file | Generate config as a file | |
| Arguments | Required | Description | Type | Default |
|---|---|---|---|---|
pipeline | false | Pipeline expression, e.g. stdin/remap,filter/console | string | none |
vector graph
Generate a visual representation of topologies. The output is in the DOT format, which can be rendered using GraphViz.
You can also visualize the output online at webgraphviz.com.
vector graph [OPTIONS]| Options | Description | Environment variable | Default | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| --color | Control when ANSI terminal formatting is used. Enum options
| VECTOR_COLOR | auto | ||||||||
| --config
, -c | Read configuration from one or more files. Wildcard paths are supported. If no files are
specified the default config path /etc/vector/vector.yaml is targeted. TOML, YAML and
JSON file formats are supported. The format to interpret the file with is determined from
the file extension (.yaml, .toml, .json). Vector falls back to YAML if it can’t
detect a supported format. | VECTOR_CONFIG | /etc/vector/vector.yaml | ||||||||
| --config-dir | Read configuration from files in one or more directories. The file format is detected
from the file name. Files not ending in .toml, .json, .yaml, or .yml are
ignored. | VECTOR_CONFIG_DIR | | ||||||||
| --config-json | Read configuration from one or more files. Wildcard paths are supported. JSON file
format is assumed. | VECTOR_CONFIG_JSON | | ||||||||
| --config-toml | Test configuration from one or more files. Wildcard paths are
supported. TOML file format is assumed. | VECTOR_CONFIG_TOML | | ||||||||
| --config-yaml | Read configuration from one or more files. Wildcard paths are supported. YAML file
format is assumed. | VECTOR_CONFIG_YAML | | ||||||||
| --graceful-shutdown-limit-secs | Set the duration in seconds to wait for graceful shutdown after SIGINT or SIGTERM are received. After the duration has passed, Vector will force shutdown. To never force shutdown, use --no-graceful-shutdown-limit. | VECTOR_GRACEFUL_SHUTDOWN_LIMIT_SECS | 60 | ||||||||
| --internal-log-rate-limit
, -i | Set the internal log rate limit. This limits Vector from emitting identical logs more than once over the given number of seconds. | VECTOR_INTERNAL_LOG_RATE_LIMIT | 10 | ||||||||
| --log-format | Set the logging format Enum options
| VECTOR_LOG_FORMAT | text | ||||||||
| --threads
, -t | The number of threads to use for processing. The default is the number of available cores. | VECTOR_THREADS | | ||||||||
| --watch-config-method | Method for watching config files.
| VECTOR_WATCH_CONFIG_METHOD | recommended | ||||||||
| --watch-config-poll-interval-seconds | Poll for config changes at given interval
only applicable if poll is set in --watch-config-method | VECTOR_WATCH_CONFIG_POLL_INTERVAL_SECONDS | 60 |
vector list
List available components, then exit
vector list [FLAGS] [OPTIONS]| Flags | Description | Environment variable | Default |
|---|---|---|---|
| --help
, -h | Prints help information | |
| Options | Description | Environment variable | Default | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| --format | Format the list in an encoding schema Enum options
| text |
vector tap
Observe events flowing into components (transforms, sinks) and
out of components (sources, transforms). Events are sampled at
a specified interval.
vector tap [FLAGS] [OPTIONS] [ARGUMENTS]| Flags | Description | Environment variable | Default |
|---|---|---|---|
| --duration_ms
, -d | Specifies a duration (in milliseconds) to sample logs (e.g. passing in 10000 will sample logs for 10 seconds then exit). | | |
| --help
, -h | Prints help information | | |
| --meta
, -m | Event output includes the associated component_id as metadata. The actual event is nested under an event key. | | |
| --no-reconnect
, -n | Whether to reconnect if the underlying Vector API connection drops. By default, tap will attempt to reconnect if the connection drops. | | |
| --quiet
, -q | Quiet output includes only events. By default, diagnostic messages may appear on stderr. | |
| Options | Description | Environment variable | Default | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| --format
, -f | Encoding format for events printed to screen Enum options
| json | |||||||||
| --inputs-of | Components (transforms, sinks) to observe for their inputs (comma-separated; accepts glob patterns) | | |||||||||
| --interval
, -i | Interval to sample events at, in milliseconds | 500 | |||||||||
| --limit
, -l | Maximum number of events to sample each interval | 100 | |||||||||
| --outputs-of | Components (sources, transforms) to observe for their inputs (comma-separated; accepts glob patterns) | | |||||||||
| --url
, -u | Vector GraphQL API server endpoint | |
| Arguments | Required | Description | Type | Default |
|---|---|---|---|---|
components | false | Components (sources, transforms) to observe for their
outputs (comma-separated; accepts glob patterns). The
default value is * only if no other patterns are specified
(i.e. via --outputs-of or --inputs-of); otherwise the
default value is empty. | list | * |
vector test
Run Vector config unit tests, then exit. This command is experimental and
therefore subject to change. For guidance on how to write unit tests check
out the unit testing documentation.
vector test [OPTIONS] [ARGUMENTS]| Options | Description | Environment variable | Default |
|---|---|---|---|
| --config-json | Read configuration from one or more files. Wildcard paths are supported. JSON file
format is assumed. | VECTOR_CONFIG_JSON | |
| --config-toml | Test configuration from one or more files. Wildcard paths are
supported. TOML file format is assumed. | VECTOR_CONFIG_TOML | |
| --config-yaml | Read configuration from one or more files. Wildcard paths are supported. YAML file
format is assumed. | VECTOR_CONFIG_YAML | |
| Arguments | Required | Description | Type | Default |
|---|---|---|---|---|
paths | false | Any number of Vector config files to test. If none are specified
the default config path /etc/vector/vector.yaml will be targeted | list | /etc/vector/vector.yaml |
vector top
Display topology and metrics in the console, for a local or remote Vector
instance
vector top [FLAGS] [OPTIONS]| Flags | Description | Environment variable | Default |
|---|---|---|---|
| --help
, -h | Prints help information | | |
| --human-metrics
, -H | Humanize metrics, using numeric suffixes - e.g. 1,100 = 1.10 k,
1,000,000 = 1.00 M | | |
| --no-reconnect
, -n | Whether to reconnect if the underlying Vector API connection drops. By default, top will attempt to reconnect if the connection drops. | |
| Options | Description | Environment variable | Default |
|---|---|---|---|
| --refresh-interval
, -i | How often the screen refreshes (in milliseconds) | 500 | |
| --url
, -u | The URL for the GraphQL endpoint of the running Vector instance | |
vector validate
Validate the target config, then exit
vector validate [FLAGS] [OPTIONS] [ARGUMENTS]| Flags | Description | Environment variable | Default |
|---|---|---|---|
| --deny-warnings
, -d | Fail validation on warnings | | |
| --help
, -h | Prints help information | | |
| --no-environment
, -ne | Disables environment checks. That includes component
checks and health checks | | |
| --skip-healthchecks
, -ne | Disables health checks during validation. | |
| Options | Description | Environment variable | Default |
|---|---|---|---|
| --config-json | Any number of Vector config files to validate.
JSON file format is assumed. | | |
| --config-toml | Any number of Vector config files to validate.
TOML file format is assumed. | | |
| --config-yaml | Any number of Vector config files to validate.
YAML file format is assumed. | |
| Arguments | Required | Description | Type | Default |
|---|---|---|---|---|
paths | false | Any number of Vector config files to validate. If none are specified
the default config path /etc/vector/vector.yaml will be targeted | list | /etc/vector/vector.yaml |
vector vrl
Vector Remap Language CLI
vector vrl [FLAGS] [OPTIONS] [ARGUMENTS]| Flags | Description | Environment variable | Default |
|---|---|---|---|
| --help
, -h | Prints help information | | |
| --print-object
, -o | Print the (modified) object, instead of the result of the final expression. The same result can be achieved by using | |
| Options | Description | Environment variable | Default |
|---|---|---|---|
| --input
, -i | File containing the object(s) to manipulate. Leave empty to use stdin. | | |
| --program
, -p | File containing the program to execute. Can be used instead of PROGRAM. | |
| Arguments | Required | Description | Type | Default |
|---|---|---|---|---|
program | false | The program to execute. For example, ".foo = true" sets the object’s foo
field to true. | string | none |
Environment variables
AWS_ACCESS_KEY_ID
common optional string literalThe AWS access key id. Used for AWS authentication when communicating with AWS services.
AWS_CONFIG_FILE
common optional string literalSpecifies the location of the file that the AWS CLI uses to store configuration profiles.
Default: ~/.aws/configAWS_DEFAULT_REGION
common optional string literalThe default AWS region.
AWS_PROFILE
common optional string literalSpecifies the name of the CLI profile with the credentials and options to use. This can be the name of a profile stored in a credentials or config file.
Default: defaultAWS_ROLE_SESSION_NAME
common optional string literalSpecifies a name to associate with the role session. This value appears in CloudTrail logs for commands performed by the user of this profile.
AWS_SECRET_ACCESS_KEY
common optional string literalThe AWS secret access key. Used for AWS authentication when communicating with AWS services.
AWS_SESSION_TOKEN
common optional string literalThe AWS session token. Used for AWS authentication when communicating with AWS services.
AWS_SHARED_CREDENTIALS_FILE
common optional string literalSpecifies the location of the file that the AWS CLI uses to store access keys.
Default: ~/.aws/credentialsDOCKER_CERT_PATH
common optional string literalPath to look for TLS certificates when tls configuration is absent.
Vector will use:
$DOCKER_CERT_PATH/ca.pem: CA certificate.$DOCKER_CERT_PATH/cert.pem: TLS certificate.$DOCKER_CERT_PATH/key.pem: TLS key.
DOCKER_CONFIG
common optional string literalPath to look for TLS certificates when both
tls configuration and DOCKER_CERT_PATH are absent.DOCKER_HOST
common optional string literalThe Docker host to connect to when
docker_host configuration is absent.GOOGLE_APPLICATION_CREDENTIALS
common optional string literalThe filename for a Google Cloud service account credentials JSON file used for authentication.
PROCFS_ROOT
common optional string literalSets an arbitrary path to the system’s procfs root. This can be
used to expose host metrics from within a container. Vector uses the system’s
/proc by default.RUST_BACKTRACE
common optional boolEnables Rust backtraces when errors are logged. We recommend using
this only when debugging, as it can degrade Vector’s performance.
SYSFS_ROOT
common optional string literalSets an arbitrary path to the system’s sysfs root. This can be used
to expose host metrics from within a container. Vector uses the system’s
/sys by
default.VECTOR_ALLOW_EMPTY_CONFIG
common optional boolAllow the configuration to run without any components. This is useful for loading in an empty stub config that will later be replaced with actual components. Note that this is likely not useful without also watching for config file changes as described in
--watch-config.VECTOR_COLOR
common optional string literal enumControl when ANSI terminal formatting is used.
Default: autoEnum options
string
literal
| Option | Description |
|---|---|
always | Always enable ANSI terminal formatting. |
auto | Detect ANSI terminal formatting and enable if supported. |
never | Disable ANSI terminal formatting. |
VECTOR_CONFIG
common optional string literalRead configuration from one or more files. Wildcard paths are supported. If no files are
specified the default config path
Default: /etc/vector/vector.yaml is targeted. TOML, YAML and
JSON file formats are supported. The format to interpret the file with is determined from
the file extension (.yaml, .toml, .json). Vector falls back to YAML if it can’t
detect a supported format./etc/vector/vector.yamlVECTOR_CONFIG_DIR
common optional string literalRead configuration from files in one or more directories. The file format is detected
from the file name. Files not ending in
.toml, .json, .yaml, or .yml are
ignored.VECTOR_CONFIG_JSON
common optional string literalRead configuration from one or more files. Wildcard paths are supported. JSON file
format is assumed.
VECTOR_CONFIG_TOML
common optional string literalTest configuration from one or more files. Wildcard paths are
supported. TOML file format is assumed.
VECTOR_CONFIG_YAML
common optional string literalRead configuration from one or more files. Wildcard paths are supported. YAML file
format is assumed.
VECTOR_GRACEFUL_SHUTDOWN_LIMIT_SECS
common optional uintSet the duration in seconds to wait for graceful shutdown after SIGINT or SIGTERM are received. After the duration has passed, Vector will force shutdown. To never force shutdown, use
Default: --no-graceful-shutdown-limit.60VECTOR_HOSTNAME
common optional string literalOverrides the hostname used in Vector’s logs and metrics. This is useful when running Vector in a container or on other systems where the hostname is not meaningful.
The example of how it can be used in Kubernetes pod template:
env:
- name: VECTOR_HOSTNAME
valueFrom:
fieldRef:
fieldPath: spec.nodeName
VECTOR_INTERNAL_LOG_RATE_LIMIT
common optional uintSet the internal log rate limit. This limits Vector from emitting identical logs more than once over the given number of seconds.
Default: 10VECTOR_LOG
common optional string literal enumVector’s log level. Each log level includes messages from higher priority levels.
Default: INFOEnum options
string
literal
| Option | Description |
|---|---|
DEBUG | Includes logs useful for debugging or troubleshooting Vector. The same as -v |
ERROR | Only show error logs. The same as -qq |
INFO | Include logs about Vector’s operation. This is the default. |
TRACE | Most verbose log level. Can be used for troubleshooting Vector. The same as -vv |
WARN | Include warnings. The same as -q |
VECTOR_LOG_FORMAT
common optional string literal enumSet the logging format
Default: textEnum options
string
literal
| Option | Description |
|---|---|
json | Output Vector’s logs as JSON. |
text | Output Vector’s logs as text. |
VECTOR_NO_GRACEFUL_SHUTDOWN_LIMIT
common optional boolNever time out while waiting for graceful shutdown after SIGINT or SIGTERM received. This is useful when you would like for Vector to attempt to send data until terminated by a SIGKILL. Overrides/cannot be set with
--graceful-shutdown-limit-secs.VECTOR_OPENSSL_NO_PROBE
common optional boolDisable probing and configuration of root certificate locations on the system for OpenSSL.
The probe functionality manipulates the SSL_CERT_FILE and SSL_CERT_DIR environment variables in the Vector process. This behavior can be problematic for users of the exec source, which by default inherits the environment of the Vector process.
VECTOR_REQUIRE_HEALTHY
common optional boolExit on startup if any sinks fail healthchecks.
VECTOR_STRICT_ENV_VARS
common optional boolTurn on strict mode for environment variable interpolation. When set, interpolation of a missing
environment variable in configuration files will cause an error instead of a warning, which will
result in a failure to load any such configuration file. This option is deprecated and will be
removed in a future version to remove the ability to downgrade missing environment variables to
warnings.
Default: trueVECTOR_THREADS
common optional uintThe number of threads to use for processing. The default is the number of available cores.
VECTOR_WATCH_CONFIG
common optional boolWatch for changes in the configuration file and reload accordingly
VECTOR_WATCH_CONFIG_METHOD
common optional string literalMethod for watching config files.
recommend - recommended event based watcher for host OS
poll - poll watcher can be used in cases where event based watcher doesn’t work, e.g., when attaching the configuration via NFS.
recommendedVECTOR_WATCH_CONFIG_POLL_INTERVAL_SECONDS
common optional uintPoll for config changes at given interval
only applicable if
Default: poll is set in --watch-config-method30