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
--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`
--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

Option	Description
`always`	Always enable ANSI terminal formatting.
`auto`	Detect ANSI terminal formatting and enable if supported.
`never`	Disable ANSI terminal formatting.

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

Option	Description
`json`	Output Vector's logs as JSON.
`text`	Output Vector's logs as text.

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]

Example

vector graph --config /etc/vector/vector.yaml | dot -Tsvg > graph.svg

Options Description Environment variable Default

--color

Control when ANSI terminal formatting is used.

Enum options

Option	Description
`always`	Always enable ANSI terminal formatting.
`auto`	Detect ANSI terminal formatting and enable if supported.
`never`	Disable ANSI terminal formatting.

VECTOR_COLOR

auto

--config ,
-c

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

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

Option	Description
`json`	Output Vector's logs as JSON.
`text`	Output Vector's logs as text.

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 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]

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

Option	Description
`avro`	Output components in Apache Avro format
`json`	Output components as JSON
`text`	Output 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]

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

Option	Description
`json`	Output events as JSON
`logfmt`	Output events as logfmt
`yaml`	Output 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

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
--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 `.` as the final expression.

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 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

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 literal

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

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

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`

Examples

DEBUG

INFO

VECTOR_LOG_FORMAT

common optional string literal enum

Set the logging format

Default: text

Enum 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 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