From 6f885c99ab539a70c33390999f7fe084e2a1e59d Mon Sep 17 00:00:00 2001 From: Clayton Cornell <131809008+clayton-cornell@users.noreply.github.com> Date: Fri, 4 Aug 2023 08:59:43 -0700 Subject: [PATCH] Update the Agent CLI topics to clarify flow mode syntax (#4697) * Update executable name * More executable name updates * Change bullet order and add missing info * Switch to command name remove binary Co-authored-by: Robert Fratto * Update metadata change note to caution * Swap command order in usage section * Fix a typo * General cleanup and formatting * Remove a gerund --------- Co-authored-by: Robert Fratto --- docs/sources/flow/reference/cli/_index.md | 16 ++++-- docs/sources/flow/reference/cli/convert.md | 34 ++++++++----- docs/sources/flow/reference/cli/fmt.md | 26 +++++++--- docs/sources/flow/reference/cli/run.md | 59 +++++++++++++--------- docs/sources/flow/reference/cli/tools.md | 28 ++++++---- 5 files changed, 102 insertions(+), 61 deletions(-) diff --git a/docs/sources/flow/reference/cli/_index.md b/docs/sources/flow/reference/cli/_index.md index f8668baa9d9b..0413de50ee71 100644 --- a/docs/sources/flow/reference/cli/_index.md +++ b/docs/sources/flow/reference/cli/_index.md @@ -1,6 +1,8 @@ --- canonical: https://grafana.com/docs/agent/latest/flow/reference/cli/ -title: Command-line interface +description: The Grafana Agent command line interface provides subcommands to perform various operations. +title: The Grafana Agent command line interface +menuTitle: Command-line interface weight: 100 --- @@ -14,10 +16,14 @@ starts Grafana Agent Flow. Available commands: -* [`grafana-agent run`][run]: Start Grafana Agent Flow, given a config file. -* [`grafana-agent fmt`][fmt]: Format a Grafana Agent Flow config file. -* `grafana-agent completion`: Generate shell completion for the `grafana-agent` CLI. -* `grafana-agent help`: Print help for supported commands. +* [`convert`][convert]: Convert a Grafana Agent configuration file. +* [`fmt`][fmt]: Format a Grafana Agent Flow configuration file. +* [`run`][run]: Start Grafana Agent Flow, given a configuration file. +* [`tools`][tools]: Read the WAL and provide statistical information. +* `completion`: Generate shell completion for the `grafana-agent-flow` CLI. +* `help`: Print help for supported commands. [run]: {{< relref "./run.md" >}} [fmt]: {{< relref "./fmt.md" >}} +[convert]: {{< relref "./convert.md" >}} +[tools]: {{< relref "./tools.md" >}} diff --git a/docs/sources/flow/reference/cli/convert.md b/docs/sources/flow/reference/cli/convert.md index db968ecaa250..d99246c3f5d5 100644 --- a/docs/sources/flow/reference/cli/convert.md +++ b/docs/sources/flow/reference/cli/convert.md @@ -2,24 +2,33 @@ canonical: https://grafana.com/docs/agent/latest/flow/reference/cli/convert/ labels: stage: beta -title: grafana-agent convert +description: The `convert` command converts supported configuration formats to River format. +title: convert command +menuTitle: convert weight: 100 --- -# `grafana-agent convert` command +# `convert` command -The `grafana-agent convert` command converts a supported configuration format -to Grafana Agent Flow River format. +The `convert` command converts a supported configuration format to Grafana Agent Flow River format. ## Usage -Usage: `grafana-agent convert [FLAG ...] FILE_NAME` +Usage: + +* `AGENT_MODE=flow grafana-agent convert [FLAG ...] FILE_NAME` +* `grafana-agent-flow convert [FLAG ...] FILE_NAME` + + Replace the following: + + * `FLAG`: One or more flags that define the input and output of the command. + * `FILE_NAME`: The Grafana Agent configuration file. If the `FILE_NAME` argument is not provided or if the `FILE_NAME` argument is -equal to `-`, `grafana-agent convert` converts the contents of standard input. Otherwise, -`grafana-agent convert` reads and converts the file from disk specified by the argument. +equal to `-`, `convert` converts the contents of standard input. Otherwise, +`convert` reads and converts the file from disk specified by the argument. -There are several different flags available for the `grafana-agent convert` command. You can use the `--output` flag to write the contents of the converted config to a specified path. You can use the `--report` flag to generate a diagnostic report. The `--bypass-errors` flag allows you to bypass any [errors] generated during the file conversion. +There are several different flags available for the `convert` command. You can use the `--output` flag to write the contents of the converted config to a specified path. You can use the `--report` flag to generate a diagnostic report. The `--bypass-errors` flag allows you to bypass any [errors] generated during the file conversion. The command fails if the source config has syntactically incorrect configuration or cannot be converted to Grafana Agent Flow River format. @@ -41,12 +50,9 @@ The following flags are supported: ### Defaults Flow Defaults are managed as follows: -* If a provided source config value matches a Flow default value, the -property is left off the Flow output. -* If a non-provided source config value default matches a Flow default value, -the property is left off the Flow output. -* If a non-provided source config value default doesn't match a Flow default -value, the Flow default value is included in the Flow output. +* If a provided source config value matches a Flow default value, the property is left off the Flow output. +* If a non-provided source config value default matches a Flow default value, the property is left off the Flow output. +* If a non-provided source config value default doesn't match a Flow default value, the Flow default value is included in the Flow output. ### Errors diff --git a/docs/sources/flow/reference/cli/fmt.md b/docs/sources/flow/reference/cli/fmt.md index c15b9d6c4037..c92d1ff57f57 100644 --- a/docs/sources/flow/reference/cli/fmt.md +++ b/docs/sources/flow/reference/cli/fmt.md @@ -1,24 +1,34 @@ --- canonical: https://grafana.com/docs/agent/latest/flow/reference/cli/fmt/ -title: grafana-agent fmt -weight: 100 +description: The `fmt` command formats a Grafana Agent configuration file. +title: fmt command +menuTitle: fmt +weight: 200 --- -# `grafana-agent fmt` command +# `fmt` command -The `grafana-agent fmt` command formats a given Grafana Agent Flow configuration file. +The `fmt` command formats a given Grafana Agent Flow configuration file. ## Usage -Usage: `grafana-agent fmt [FLAG ...] FILE_NAME` +Usage: + +* `AGENT_MODE=flow grafana-agent fmt [FLAG ...] FILE_NAME` +* `grafana-agent-flow fmt [FLAG ...] FILE_NAME` + + Replace the following: + + * `FLAG`: One or more flags that define the input and output of the command. + * `FILE_NAME`: The Grafana Agent configuration file. If the `FILE_NAME` argument is not provided or if the `FILE_NAME` argument is -equal to `-`, `grafana-agent fmt` formats the contents of standard input. Otherwise, -`grafana-agent fmt` reads and formats the file from disk specified by the argument. +equal to `-`, `fmt` formats the contents of standard input. Otherwise, +`fmt` reads and formats the file from disk specified by the argument. The `--write` flag can be specified to replace the contents of the original file on disk with the formatted results. `--write` can only be provided when -`grafana-agent fmt` is not reading from standard input. +`fmt` is not reading from standard input. The command fails if the file being formatted has syntactically incorrect River configuration, but does not validate whether Flow components are configured diff --git a/docs/sources/flow/reference/cli/run.md b/docs/sources/flow/reference/cli/run.md index 016be9b25208..fc672a46286f 100644 --- a/docs/sources/flow/reference/cli/run.md +++ b/docs/sources/flow/reference/cli/run.md @@ -1,29 +1,38 @@ --- canonical: https://grafana.com/docs/agent/latest/flow/reference/cli/run/ -title: grafana-agent run -weight: 100 +description: The `run` command runs Grafana Agent in the foreground until an interrupt is received. +title: run command +menuTitle: run +weight: 300 --- -# `grafana-agent run` command +# `run` command -The `grafana-agent run` command runs Grafana Agent Flow in the foreground until an +The `run` command runs Grafana Agent Flow in the foreground until an interrupt is received. ## Usage -Usage: `grafana-agent run [FLAG ...] FILE_NAME` +Usage: -`grafana-agent run` must be provided an argument which points at the River config file -to use. `grafana-agent run` will immediately exit with an error if the River file -wasn't specified, can't be loaded, or contained errors during the initial load. +* `AGENT_MODE=flow grafana-agent run [FLAG ...] FILE_NAME` +* `grafana-agent-flow run [FLAG ...] FILE_NAME` -Grafana Agent Flow will continue to run if subsequent reloads of the config + Replace the following: + + * `FLAG`: One or more flags that define the input and output of the command. + * `FILE_NAME`: Required. The Grafana Agent configuration file. + +If the `FILE_NAME` argument is not provided, or if the configuration file can't be loaded or +contains errors during the initial load, the `run` command will immediately exit and show an error message. + +Grafana Agent Flow will continue to run if subsequent reloads of the configuration file fail, potentially marking components as unhealthy depending on the nature of the failure. When this happens, Grafana Agent Flow will continue functioning in the last valid state. -`grafana-agent run` launches an HTTP server for expose metrics about itself and -components. The HTTP server is also used for exposing a UI at `/` for debugging +`run` launches an HTTP server that exposes metrics about itself and its +components. The HTTP server is also exposes a UI at `/` for debugging running components. The following flags are supported: @@ -32,7 +41,7 @@ The following flags are supported: * `--server.http.memory-addr`: Address to listen for [in-memory HTTP traffic][] on (default `agent.internal:12345`). * `--server.http.listen-addr`: Address to listen for HTTP traffic on (default `127.0.0.1:12345`). -* `--server.http.ui-path-prefix`: Base path where the UI will be exposed (default `/`). +* `--server.http.ui-path-prefix`: Base path where the UI is exposed (default `/`). * `--storage.path`: Base directory where components can store data (default `data-agent/`). * `--disable-reporting`: Disable [usage reporting][] of enabled [components][] to Grafana (default `false`). * `--cluster.enabled`: Start the Agent in clustered mode (default `false`). @@ -47,17 +56,17 @@ The following flags are supported: [usage reporting]: {{< relref "../../../static/configuration/flags.md#report-information-usage" >}} [components]: {{< relref "../../concepts/components.md" >}} -## Updating the config file +## Update the configuration file -The config file can be reloaded from disk by either: +The configuration file can be reloaded from disk by either: * Sending an HTTP POST request to the `/-/reload` endpoint. * Sending a `SIGHUP` signal to the Grafana Agent process. When this happens, the [component controller][] synchronizes the set of running -components with the latest set of components specified in the config file. -Components that are no longer defined in the config file after reloading are -shut down, and components that have been added to the config file since the +components with the latest set of components specified in the configuration file. +Components that are no longer defined in the configuration file after reloading are +shut down, and components that have been added to the configuration file since the previous reload are created. All components managed by the component controller are reevaluated after @@ -94,13 +103,13 @@ align the port numbers on as many nodes as possible to simplify the deployment process. The `--cluster.discover-peers` command-line flag expects a list of tuples in -the form of `provider=XXX key=val key=val ...`. Clustering makes use of the +the form of `provider=XXX key=val key=val ...`. Clustering uses the [go-discover] package to discover peers and fetch their IP addresses, based on the chosen provider and the filtering key-values it supports. Clustering supports the default set of providers available in go-discover and registers the `k8s` provider on top. -If either the key or the value in a pair contains a space, a backslash or +If either the key or the value in a pair contains a space, a backslash, or double quotes, then it must be quoted with double quotes. Within this quoted string, the backslash can be used to escape double quotes or the backslash itself. @@ -122,13 +131,13 @@ Clustered agents are in one of three states: participating in workload distribution. * **Participant**: The agent is participating in workload distribution for - components which have clustering enabled. + components that have clustering enabled. -* **Terminating**: The agent is shutting down, and will no longer assign new +* **Terminating**: The agent is shutting down and will no longer assign new work to itself. -Agents initially join the cluster in the viewer state, and then transition to -the participant state after the processs startup completes. Agents then +Agents initially join the cluster in the viewer state and then transition to +the participant state after the process startup completes. Agents then transition to the terminating state when shutting down. The current state of a clustered agent is shown on the clustering page in the @@ -142,13 +151,13 @@ When you use the `--config.format` command-line argument with a value other than `flow`, Grafana Agent converts the configuration file from the source format to River and immediately starts running with the new configuration. This conversion uses the converter API described in the -[grafana-agent convert][] docs. +[grafana-agent-flow convert][] docs. If you also use the `--config.bypass-conversion-errors` command-line argument, Grafana Agent will ignore any errors from the converter. Use this argument with caution because the resulting conversion may not be equivalent to the original configuration. -[grafana-agent convert]: {{< relref "./convert.md" >}} +[grafana-agent-flow convert]: {{< relref "./convert.md" >}} [clustering]: {{< relref "../../concepts/clustering.md" >}} [go-discover]: https://github.com/hashicorp/go-discover diff --git a/docs/sources/flow/reference/cli/tools.md b/docs/sources/flow/reference/cli/tools.md index 7d2fcd615da0..ef52d5a1ae1c 100644 --- a/docs/sources/flow/reference/cli/tools.md +++ b/docs/sources/flow/reference/cli/tools.md @@ -1,15 +1,16 @@ --- canonical: https://grafana.com/docs/agent/latest/flow/reference/cli/tools/ -title: grafana-agent tools -weight: 100 +description: Command line tools that read the WAL and provide statistical information. +title: tools command +menuTitle: tools +weight: 400 --- -# `grafana-agent tools` command +# `tools` command -The `grafana-agent tools` command contains command line tooling grouped by Flow -component. +The `tools` command contains command line tooling grouped by Flow component. -{{% admonition type="note" %}} +{{% admonition type="caution" %}} Utilities in this command have no backward compatibility guarantees and may change or be removed between releases. {{% /admonition %}} @@ -18,7 +19,10 @@ guarantees and may change or be removed between releases. ### prometheus.remote_write sample-stats -Usage: `grafana-agent tools prometheus.remote_write sample-stats [FLAG ...] WAL_DIRECTORY` +Usage: + +* `AGENT_MODE=flow grafana-agent tools prometheus.remote_write sample-stats [FLAG ...] WAL_DIRECTORY` +* `grafana-agent-flow tools prometheus.remote_write sample-stats [FLAG ...] WAL_DIRECTORY` The `sample-stats` command reads the Write-Ahead Log (WAL) specified by `WAL_DIRECTORY` and collects information on metric samples within it. @@ -38,7 +42,10 @@ The following flag is supported: ### prometheus.remote_write target-stats -Usage: `grafana-agent tools prometheus.remote_write target-stats --job JOB --instance INSTANCE WAL_DIRECTORY` +Usage: + +* `AGENT_MODE=flow grafana-agent tools prometheus.remote_write target-stats --job JOB --instance INSTANCE WAL_DIRECTORY` +* `grafana-agent-flow tools prometheus.remote_write target-stats --job JOB --instance INSTANCE WAL_DIRECTORY` The `target-stats` command reads the Write-Ahead Log (WAL) specified by `WAL_DIRECTORY` and collects metric cardinality information for a specific @@ -57,7 +64,10 @@ The `--job` and `--instance` labels are required. ### prometheus.remote_write wal-stats -Usage: `grafana-agent tools prometheus.remote_write wal-stats WAL_DIRECTORY` +Usage: + +* `AGENT_MODE=flow grafana-agent tools prometheus.remote_write wal-stats WAL_DIRECTORY` +* `grafana-agent-flow tools prometheus.remote_write wal-stats WAL_DIRECTORY` The `wal-stats` command reads the Write-Ahead Log (WAL) specified by `WAL_DIRECTORY` and collects general information about it.