diff --git a/docs/sources/query/logcli/_index.md b/docs/sources/query/logcli/_index.md index d021a6e7fcc58..d75048626c3c9 100644 --- a/docs/sources/query/logcli/_index.md +++ b/docs/sources/query/logcli/_index.md @@ -11,5 +11,5 @@ weight: 600 LogCLI is a command-line tool for querying and exploring logs in Grafana Loki: -* Installation and Reference: [LogCLI](https://grafana.com/docs/loki//query/logcli/logcli/) -* Getting started tutorial: [LogCLI Tutorial](https://grafana.com/docs/loki//query/logcli/logcli-tutorial) \ No newline at end of file +* Installation and Reference: [LogCLI](https://grafana.com/docs/loki//query/logcli/getting-started/) +* Getting started tutorial: [LogCLI Tutorial](https://grafana.com/docs/loki//query/logcli/logcli-tutorial) diff --git a/docs/sources/query/logcli/getting-started.md b/docs/sources/query/logcli/getting-started.md index 3eb0a12400a19..d7d483485e1dd 100644 --- a/docs/sources/query/logcli/getting-started.md +++ b/docs/sources/query/logcli/getting-started.md @@ -3,25 +3,33 @@ title: LogCLI getting started menuTItle: Getting started description: Installation and reference for LogCLI, a command-line tool for querying and exploring logs in Grafana Loki. aliases: -- ../getting-started/logcli/ -- ../tools/logcli/ -- ../query +- ../query/logcli/ weight: 150 --- # LogCLI getting started -LogCLI is the command-line interface to Grafana Loki. -It facilitates running [LogQL](https://grafana.com/docs/loki//query) -queries against a Loki instance. +logcli is a command-line client for Loki that lets you run [LogQL](https://grafana.com/docs/loki//query) queries against your Loki instance. The `query` command will output extra information about the query and its results, such as the API URL, set of common labels, and set of excluded labels. -## Installation +This is useful, for example, if you want to download a range of logs from Loki. Or want to perform analytical administration tasks, for example, discover the number of log streams to understand your label cardinality, or find out the estimated volume of data that a query will search over. You can also use logcli as part of shell scripts. + +If you are a Grafana Cloud user, you can also use logcli to query logs that you have exported to long-term storage with [Cloud Logs Export](https://grafana.com/docs/grafana-cloud/send-data/logs/export/), or any other Loki formatted log data. + +{{< admonition type="note" >}} +Note that logcli is a querying tool, it cannot be used to ingest logs. +{{< /admonition >}} + +## Install logcli + +As a best practice, you should download the version of logcli that matches your Loki version. And upgrade your logcli when you upgrade your version of Loki. ### Binary (Recommended) Download the `logcli` binary from the [Loki releases page](https://github.com/grafana/loki/releases). +Builds are available for Linux, Mac, and Windows. + ### Build LogCLI from source Clone the Loki repository and build `logcli` from source: @@ -43,99 +51,74 @@ cp cmd/logcli/logcli /usr/local/bin/logcli You can set up tab-completion for `logcli` with one of the two options, depending on your shell: - For bash, add this to your `~/.bashrc` file: - ``` - eval "$(logcli --completion-script-bash)" - ``` + + ```bash + eval "$(logcli --completion-script-bash)" + ``` - For zsh, add this to your `~/.zshrc` file: - ``` - eval "$(logcli --completion-script-zsh)" - ``` + + ```bash + eval "$(logcli --completion-script-zsh)" + ``` ## LogCLI usage -### Grafana Cloud example +Once you have installed logcli, you can run it in the following way: -If you are running on Grafana Cloud, use: +`logcli [, ...]` -```bash -export LOKI_ADDR=https://logs-us-west1.grafana.net -export LOKI_USERNAME= -export LOKI_PASSWORD= -``` +`` points to one of the commands, detailed in the [command reference](http://localhost:3002/docs/loki//query/logcli/getting-started/#logcli-command-reference) below. -Otherwise you can point LogCLI to a local instance directly -without needing a username and password: +`` is one of the subcommands available for each command. -```bash -export LOKI_ADDR=http://localhost:3100 -``` +`` is a list of space separated arguments. Arguments can optionally be overridden using environment variables. Environment variables will always take precedence over command line arguments. -{{< admonition type="note" >}} -If you are running Loki behind a proxy server and you have -authentication configured, you will also have to pass in LOKI_USERNAME -and LOKI_PASSWORD, LOKI_BEARER_TOKEN or LOKI_BEARER_TOKEN_FILE accordingly. -{{< /admonition >}} +### Authenticate to Loki -```bash -$ logcli labels job -https://logs-dev-ops-tools1.grafana.net/api/prom/label/job/values -loki-ops/consul -loki-ops/loki-gw -... +To connect to a Loki instance, set the following argument: -$ logcli query '{job="loki-ops/consul"}' -https://logs-dev-ops-tools1.grafana.net/api/prom/query?query=%7Bjob%3D%22loki-ops%2Fconsul%22%7D&limit=30&start=1529928228&end=1529931828&direction=backward®exp= -Common labels: {job="loki-ops/consul", namespace="loki-ops"} -2018-06-25T12:52:09Z {instance="consul-8576459955-pl75w"} 2018/06/25 12:52:09 [INFO] raft: Snapshot to 475409 complete -2018-06-25T12:52:09Z {instance="consul-8576459955-pl75w"} 2018/06/25 12:52:09 [INFO] raft: Compacting logs from 456973 to 465169 -... +- `--addr=http://loki.example.com:3100` or the `LOKI_ADDR` environment variable -$ logcli series -q --match='{namespace="loki",container_name="loki"}' -{app="loki", container_name="loki", controller_revision_hash="loki-57c9df47f4", filename="/var/log/pods/loki_loki-0_8ed03ded-bacb-4b13-a6fe-53a445a15887/loki/0.log", instance="loki-0", job="loki/loki", name="loki", namespace="loki", release="loki", statefulset_kubernetes_io_pod_name="loki-0", stream="stderr"} -``` +For example, to query a local Loki instance directly without needing a username and password: -### Batched queries +```bash +export LOKI_ADDR=http://localhost:3100 -LogCLI sends queries to Loki such that query results arrive in batches. +logcli query '{service_name="website"}' +``` -The `--limit` option for a `logcli query` command caps the quantity of -log lines for a single query. -When not set, `--limit` defaults to 30. -The limit protects the user from overwhelming the system -for cases in which the specified query would have returned a large quantity -of log lines. -The limit also protects the user from unexpectedly large responses. +To connect to a Loki instance which requires authentication, you will need to additionally set the following arguments: -The quantity of log line results that arrive in each batch -is set by the `--batch` option in a `logcli query` command. -When not set, `--batch` defaults to 1000. +- `--username` or the `LOKI_USERNAME` environment variable +- `--password` or the `LOKI_PASSWORD` environment variable -Setting a `--limit` value larger than the `--batch` value causes the -requests from LogCLI to Loki to be batched. -Loki has a server-side limit that defaults to 5000 for the maximum quantity -of lines returned for a single query. -The batching of requests allows you to query for a results set that -is larger than the server-side limit, -as long as the `--batch` value is less than the server limit. +For example, to query Grafana Cloud: -Query metadata is output to `stderr` for each batch. -Set the `--quiet` option on the `logcli query` command line to suppress -the output of the query metadata. +```bash +export LOKI_ADDR=https://logs-us-west1.grafana.net +export LOKI_USERNAME= +export LOKI_PASSWORD= -### Configuration +logcli query '{service_name="website"}' +``` + +To specify a particular tenant, set the following argument: -Configuration values are considered in the following order (lowest to highest): +- `--org-id` or the `LOKI_ORG_ID` environment variable -- Environment variables -- Command-line options +{{< admonition type="note" >}} +If you are running Loki behind a proxy server and you have +[authentication](https://grafana.com/docs/loki//operations/authentication/) configured, you will also have to pass in LOKI_USERNAME +and LOKI_PASSWORD, LOKI_BEARER_TOKEN or LOKI_BEARER_TOKEN_FILE accordingly. +{{< /admonition >}} -### LogCLI command reference +## LogCLI command reference The output of `logcli help`: -```nohighlight -usage: logcli [] [ ...] +```shell +usage: logcli [][ ...] A command-line for Loki. @@ -251,7 +234,7 @@ Commands: The output of `logcli help query`: -``` +```shell usage: logcli query [] Run a LogQL query. @@ -290,7 +273,7 @@ point (like what is seen in the Grafana Explore table view), then you should use Parallelization: -You can download an unlimited number of logs in parallel, there are a few flags which control this behaviour: +You can download an unlimited number of logs in parallel, there are a few flags which control this behavior: --parallel-duration --parallel-max-workers @@ -393,7 +376,7 @@ Flags: file. Default will skip a range if it's part file is already downloaded. --merge-parts Reads the part files in order and writes the output to stdout. Original part files will be deleted with this option. - --keep-parts Overrides the default behaviour of --merge-parts which will delete the part files once all the files have been + --keep-parts Overrides the default behavior of --merge-parts which will delete the part files once all the files have been read. This option will keep the part files. --forward Scan forwards through logs. --no-labels Do not print any labels @@ -418,7 +401,7 @@ Args: The output of `logcli help instant-query`: -``` +```shell usage: logcli instant-query [] Run an instant LogQL query. @@ -488,7 +471,7 @@ Args: The output of `logcli help labels`: -``` +```shell usage: logcli labels [] [