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 |
|---|---|---|---|
| --help
, -h | Prints help information | | |
| --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 --verbose. | | |
| --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.toml is targeted. TOML, YAML and
JSON file formats are supported. The format to interpret the file with is determined from
the file extension (.toml, .yaml, .json). Vector falls back to TOML if it can’t
detect a supported format. | VECTOR_CONFIG | /etc/vector/vector.toml | ||||||||
| --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 | | ||||||||
| --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 | |
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.toml is targeted. TOML, YAML and
JSON file formats are supported. The format to interpret the file with is determined from
the file extension (.toml, .yaml, .json). Vector falls back to TOML if it can’t
detect a supported format. | VECTOR_CONFIG | /etc/vector/vector.toml | ||||||||
| --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 | | ||||||||
| --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 | |
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 |
|---|---|---|---|
| --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.toml will be targeted | list | /etc/vector/vector.toml |
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 | |
| 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.toml will be targeted | list | /etc/vector/vector.toml |
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_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.toml is targeted. TOML, YAML and
JSON file formats are supported. The format to interpret the file with is determined from
the file extension (.toml, .yaml, .json). Vector falls back to TOML if it can’t
detect a supported format./etc/vector/vector.tomlVECTOR_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_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_REQUIRE_HEALTHY
common optional boolExit on startup if any sinks fail healthchecks.
VECTOR_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