Skip to content

Commit

Permalink
docs: describe the difference between configuration fields and runtim…
Browse files Browse the repository at this point in the history
…e flags (vectordotdev#17784)

<!--
**Your PR title must conform to the conventional commit spec!**

  <type>(<scope>)!: <description>

  * `type` = chore, enhancement, feat, fix, docs
  * `!` = OPTIONAL: signals a breaking change
* `scope` = Optional when `type` is "chore" or "docs", available scopes
https://github.com/vectordotdev/vector/blob/master/.github/semantic.yml#L20
  * `description` = short description of the change

Examples:

  * enhancement(file source): Add `sort` option to sort discovered files
  * feat(new source): Initial `statsd` source
  * fix(file source): Fix a bug discovering new files
  * chore(external docs): Clarify `batch_size` option
-->

This PR adds docs describing a detail of our UX system around CLI args 😎
  • Loading branch information
DominicBurkart authored Jul 7, 2023
1 parent 98ca627 commit 01e2dfa
Showing 1 changed file with 19 additions and 0 deletions.
19 changes: 19 additions & 0 deletions STYLE.md
Original file line number Diff line number Diff line change
Expand Up @@ -327,3 +327,22 @@ you'll need to use an asynchronous-specific synchronization primitives, namely t
itself. The documentation on `tokio`'s own
[`Mutex`](https://docs.rs/tokio/latest/tokio/sync/struct.Mutex.html), for example, calls out the
specifics of when and where you might need to use it vs the one from `std::sync`.


## New Configuration Fields vs CLI flags

Vector makes the distinction between configuration items that are essential to understand data
pipelines and runtime flags that determine the details of the runtime behavior. The main configuration
generally lives in a file in the current directory or in `/etc/vector`.

Examples of main configuration fields are source, transformation, and sink declaration, as well as
information about where any disk buffers should be persisted.

For configuration items that purely inform details of Vector's runtime behavior, CLI flags without
corresponding configuration fields should be used.

An example of a runtime flag is
`vector run --no-graceful-shutdown-limit`, which tells Vector to ignore SIGINTs and to continue running
as normal until a SIGKILL is received. In this case, as the configuration describes the desired runtime
behavior in a specific environment and not to the underlying data pipeline, no corresponding field in
the configuration file should exist.

0 comments on commit 01e2dfa

Please sign in to comment.