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]
FlagsDescriptionEnvironment variableDefault
--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 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_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
--strict-env-vars
Turn 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.
VECTOR_STRICT_ENV_VARS
--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
OptionsDescriptionEnvironment variableDefault
--color
Control when ANSI terminal formatting is used.
Enum options
OptionDescription
alwaysAlways enable ANSI terminal formatting.
autoDetect ANSI terminal formatting and enable if supported.
neverDisable ANSI terminal formatting.
VECTOR_COLORauto
--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_SECS60
--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_LIMIT10
--log-format
Set the logging format
Enum options
OptionDescription
jsonOutput Vector's logs as JSON.
textOutput Vector's logs as text.
VECTOR_LOG_FORMATtext
--threads ,
-t
The number of threads to use for processing. The default is the number of available cores.
VECTOR_THREADS

vector generate

Generate a Vector configuration containing a list of components
vector generate [FLAGS] [OPTIONS] [ARGUMENTS]
FlagsDescriptionEnvironment variableDefault
--fragment ,
-f
Whether to skip the generation of global fields
--help ,
-h
Prints help information
OptionsDescriptionEnvironment variableDefault
--file
Generate config as a file
ArgumentsRequiredDescriptionTypeDefault
pipelinefalsePipeline expression, e.g. stdin/remap,filter/consolestringnone

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]

Example

vector graph --config /etc/vector/vector.yaml | dot -Tsvg > graph.svg
OptionsDescriptionEnvironment variableDefault
--color
Control when ANSI terminal formatting is used.
Enum options
OptionDescription
alwaysAlways enable ANSI terminal formatting.
autoDetect ANSI terminal formatting and enable if supported.
neverDisable ANSI terminal formatting.
VECTOR_COLORauto
--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_SECS60
--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_LIMIT10
--log-format
Set the logging format
Enum options
OptionDescription
jsonOutput Vector's logs as JSON.
textOutput Vector's logs as text.
VECTOR_LOG_FORMATtext
--threads ,
-t
The number of threads to use for processing. The default is the number of available cores.
VECTOR_THREADS

vector help

Prints this message or the help of the given subcommand(s)
vector help

vector list

List available components, then exit
vector list [FLAGS] [OPTIONS]
FlagsDescriptionEnvironment variableDefault
--help ,
-h
Prints help information
OptionsDescriptionEnvironment variableDefault
--format
Format the list in an encoding schema
Enum options
OptionDescription
avroOutput components in Apache Avro format
jsonOutput components as JSON
textOutput components as text
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]
FlagsDescriptionEnvironment variableDefault
--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.
OptionsDescriptionEnvironment variableDefault
--format ,
-f
Encoding format for events printed to screen
Enum options
OptionDescription
jsonOutput events as JSON
logfmtOutput events as logfmt
yamlOutput events as YAML
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
ArgumentsRequiredDescriptionTypeDefault
componentsfalseComponents (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]
OptionsDescriptionEnvironment variableDefault
--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
ArgumentsRequiredDescriptionTypeDefault
pathsfalseAny number of Vector config files to test. If none are specified the default config path /etc/vector/vector.yaml will be targetedlist/etc/vector/vector.yaml

vector top

Display topology and metrics in the console, for a local or remote Vector instance
vector top [FLAGS] [OPTIONS]
FlagsDescriptionEnvironment variableDefault
--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.
OptionsDescriptionEnvironment variableDefault
--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]
FlagsDescriptionEnvironment variableDefault
--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.
OptionsDescriptionEnvironment variableDefault
--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.
ArgumentsRequiredDescriptionTypeDefault
pathsfalseAny number of Vector config files to validate. If none are specified the default config path /etc/vector/vector.yaml will be targetedlist/etc/vector/vector.yaml

vector vrl

Vector Remap Language CLI
vector vrl [FLAGS] [OPTIONS] [ARGUMENTS]
FlagsDescriptionEnvironment variableDefault
--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 . as the final expression.

OptionsDescriptionEnvironment variableDefault
--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.
ArgumentsRequiredDescriptionTypeDefault
programfalseThe program to execute. For example, ".foo = true" sets the object’s foo field to true.stringnone

Environment variables

AWS_ACCESS_KEY_ID

common optional string literal
The AWS access key id. Used for AWS authentication when communicating with AWS services.
Examples
AKIAIOSFODNN7EXAMPLE

AWS_CONFIG_FILE

common optional string literal
Specifies the location of the file that the AWS CLI uses to store configuration profiles.
Default: ~/.aws/config

AWS_DEFAULT_REGION

common optional string literal
The default AWS region.
Examples
/path/to/credentials.json

AWS_PROFILE

common optional string literal
Specifies 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: default
Examples
my-custom-profile

AWS_ROLE_SESSION_NAME

common optional string literal
Specifies a name to associate with the role session. This value appears in CloudTrail logs for commands performed by the user of this profile.
Examples
vector-session

AWS_SECRET_ACCESS_KEY

common optional string literal
The AWS secret access key. Used for AWS authentication when communicating with AWS services.
Examples
wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

AWS_SESSION_TOKEN

common optional string literal
The AWS session token. Used for AWS authentication when communicating with AWS services.
Examples
AQoEXAMPLEH4aoAH0gNCAPy...truncated...zrkuWJOgQs8IZZaIv2BXIa2R4Olgk

AWS_SHARED_CREDENTIALS_FILE

common optional string literal
Specifies the location of the file that the AWS CLI uses to store access keys.
Default: ~/.aws/credentials

DOCKER_CERT_PATH

common optional string literal

Path 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.
Examples
certs/

DOCKER_CONFIG

common optional string literal
Path to look for TLS certificates when both tls configuration and DOCKER_CERT_PATH are absent.
Examples
certs/

DOCKER_HOST

common optional string literal
The Docker host to connect to when docker_host configuration is absent.
Examples
unix:///var/run/docker.sock

GOOGLE_APPLICATION_CREDENTIALS

common optional string literal
The filename for a Google Cloud service account credentials JSON file used for authentication.
Examples
/path/to/credentials.json

PROCFS_ROOT

common optional string literal
Sets 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 bool
Enables 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 literal
Sets 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.
Examples
/mnt/host/sys

VECTOR_ALLOW_EMPTY_CONFIG

common optional bool
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_COLOR

common optional string literal enum
Control when ANSI terminal formatting is used.
Default: auto
Enum options string literal
OptionDescription
alwaysAlways enable ANSI terminal formatting.
autoDetect ANSI terminal formatting and enable if supported.
neverDisable ANSI terminal formatting.

VECTOR_CONFIG

common optional string literal
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.
Default: /etc/vector/vector.yaml

VECTOR_CONFIG_DIR

common optional string literal
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_JSON

common optional string literal
Read configuration from one or more files. Wildcard paths are supported. JSON file format is assumed.

VECTOR_CONFIG_TOML

common optional string literal
Test configuration from one or more files. Wildcard paths are supported. TOML file format is assumed.

VECTOR_CONFIG_YAML

common optional string literal
Read configuration from one or more files. Wildcard paths are supported. YAML file format is assumed.

VECTOR_GRACEFUL_SHUTDOWN_LIMIT_SECS

common optional uint
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.
Default: 60

VECTOR_INTERNAL_LOG_RATE_LIMIT

common optional uint
Set the internal log rate limit. This limits Vector from emitting identical logs more than once over the given number of seconds.
Default: 10

VECTOR_LOG

common optional string literal enum
Vector’s log level. Each log level includes messages from higher priority levels.
Default: INFO
Enum options string literal
OptionDescription
DEBUGIncludes logs useful for debugging or troubleshooting Vector. The same as -v
ERROROnly show error logs. The same as -qq
INFOInclude logs about Vector’s operation. This is the default.
TRACEMost verbose log level. Can be used for troubleshooting Vector. The same as -vv
WARNInclude warnings. The same as -q
Examples
DEBUG
INFO

VECTOR_LOG_FORMAT

common optional string literal enum
Set the logging format
Default: text
Enum options string literal
OptionDescription
jsonOutput Vector’s logs as JSON.
textOutput Vector’s logs as text.

VECTOR_NO_GRACEFUL_SHUTDOWN_LIMIT

common optional bool
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_OPENSSL_NO_PROBE

common optional bool

Disable 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 bool
Exit on startup if any sinks fail healthchecks.

VECTOR_STRICT_ENV_VARS

common optional bool
Turn 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: true

VECTOR_THREADS

common optional uint
The number of threads to use for processing. The default is the number of available cores.

VECTOR_WATCH_CONFIG

common optional bool
Watch for changes in the configuration file and reload accordingly