Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

clarify logcli commands and output #1712

Merged
merged 6 commits into from
Mar 30, 2020
Merged

clarify logcli commands and output #1712

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
5031e7a
clarify logcli commands and output
rfratto Feb 18, 2020
16d69dd
address feedback
rfratto Feb 18, 2020
13ddf0b
address more feedback
rfratto Feb 18, 2020
fe898ad
explain that instant-query is not useful for log lines
rfratto Feb 18, 2020
b16ddee
address review feedback
rfratto Mar 5, 2020
bda0510
sync logcli.md with command output
rfratto Mar 18, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 43 additions & 7 deletions cmd/logcli/main.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,20 +20,55 @@ import (

var (
app = kingpin.New("logcli", "A command-line for loki.").Version(version.Print("logcli"))
quiet = app.Flag("quiet", "suppress everything but log lines").Default("false").Short('q').Bool()
quiet = app.Flag("quiet", "suppress query metadata").Default("false").Short('q').Bool()
statistics = app.Flag("stats", "show query statistics").Default("false").Bool()
outputMode = app.Flag("output", "specify output mode [default, raw, jsonl]").Default("default").Short('o').Enum("default", "raw", "jsonl")
outputMode = app.Flag("output", "specify output mode [default, raw, jsonl]. raw suppresses log labels and timestamp.").Default("default").Short('o').Enum("default", "raw", "jsonl")
timezone = app.Flag("timezone", "Specify the timezone to use when formatting output timestamps [Local, UTC]").Default("Local").Short('z').Enum("Local", "UTC")

queryClient = newQueryClient(app)

queryCmd = app.Command("query", "Run a LogQL query.")
queryCmd = app.Command("query", `Run a LogQL query.

The "query" command is useful for querying for logs. Logs can be
returned in a few output modes:

raw: log line
default: log timestamp + log labels + log line
jsonl: JSON response from Loki API of log line

The output of the log can be specified with the "-o" flag, for
example, "-o raw" for the raw output format.

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. This extra information can be suppressed with the
--quiet flag.

While "query" does support metrics queries, its output contains multiple
data points between the start and end query time. This output is used to
build graphs, like what is seen in the Grafana Explore graph view. If
you are querying metrics and just want the most recent data point
(like what is seen in the Grafana Explore table view), then you should use
the "instant-query" command instead.`)
rangeQuery = newQuery(false, queryCmd)
tail = queryCmd.Flag("tail", "Tail the logs").Short('t').Default("false").Bool()
delayFor = queryCmd.Flag("delay-for", "Delay in tailing by number of seconds to accumulate logs for re-ordering").Default("0").Int()

instantQueryCmd = app.Command("instant-query", "Run an instant LogQL query")
instantQuery = newQuery(true, instantQueryCmd)
instantQueryCmd = app.Command("instant-query", `Run an instant LogQL query.

The "instant-query" command is useful for evaluating a metric query for
a single point in time. This is equivalent to the Grafana Explore table
view; if you want a metrics query that is used to build a Grafana graph,
you should use the "query" command instead.
rfratto marked this conversation as resolved.
Show resolved Hide resolved

This command does not produce useful output when querying for log lines;
you should always use the "query" command when you are running log queries.

For more information about log queries and metric queries, refer to the
LogQL documentation:

https://github.com/grafana/loki/blob/master/docs/logql.md`)
instantQuery = newQuery(true, instantQueryCmd)

labelsCmd = app.Command("labels", "Find values for a given label.")
labelName = labelsCmd.Arg("label", "The name of the label.").HintAction(hintActionLabelNames).String()
Expand Down Expand Up @@ -118,7 +153,7 @@ func newQueryClient(app *kingpin.Application) *client.Client {
app.Flag("tls-skip-verify", "Server certificate TLS skip verify.").Default("false").BoolVar(&client.TLSConfig.InsecureSkipVerify)
app.Flag("cert", "Path to the client certificate. Can also be set using LOKI_CLIENT_CERT_PATH env var.").Default("").Envar("LOKI_CLIENT_CERT_PATH").StringVar(&client.TLSConfig.CertFile)
app.Flag("key", "Path to the client certificate key. Can also be set using LOKI_CLIENT_KEY_PATH env var.").Default("").Envar("LOKI_CLIENT_KEY_PATH").StringVar(&client.TLSConfig.KeyFile)
app.Flag("org-id", "org ID header to be substituted for auth").StringVar(&client.OrgID)
app.Flag("org-id", "adds X-Scope-OrgID to API requests for representing tenant ID. Useful for requesting tenant data when bypassing an auth gateway.").StringVar(&client.OrgID)

return client
}
Expand Down Expand Up @@ -153,11 +188,12 @@ func newQuery(instant bool, cmd *kingpin.CmdClause) *query.Query {
return nil
})

cmd.Arg("query", "eg '{foo=\"bar\",baz=~\".*blip\"} |~ \".*error.*\"'").Required().StringVar(&query.QueryString)
cmd.Flag("limit", "Limit on number of entries to print.").Default("30").IntVar(&query.Limit)
if instant {
cmd.Arg("query", "eg 'rate({foo=\"bar\"} |~ \".*error.*\" [5m])'").Required().StringVar(&query.QueryString)
cmd.Flag("now", "Time at which to execute the instant query.").StringVar(&now)
} else {
cmd.Arg("query", "eg '{foo=\"bar\",baz=~\".*blip\"} |~ \".*error.*\"'").Required().StringVar(&query.QueryString)
cmd.Flag("since", "Lookback window.").Default("1h").DurationVar(&since)
cmd.Flag("from", "Start looking for logs at this absolute time (inclusive)").StringVar(&from)
cmd.Flag("to", "Stop looking for logs at this absolute time (exclusive)").StringVar(&to)
Expand Down
147 changes: 118 additions & 29 deletions docs/getting-started/logcli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,69 +64,158 @@ Configuration values are considered in the following order (lowest to highest):

### Details

```bash
```nohighlight
$ logcli help
usage: logcli [<flags>] <command> [<args> ...]

A command-line for loki.

rfratto marked this conversation as resolved.
Show resolved Hide resolved
Flags:
--help Show context-sensitive help (also try --help-long and --help-man).
-q, --quiet suppress everything but log lines
-o, --output=default specify output mode [default, raw, jsonl]
--addr="https://logs-us-west1.grafana.net"
Server address.
--username="" Username for HTTP basic auth.
--password="" Password for HTTP basic auth.
--ca-cert="" Path to the server Certificate Authority.
--help Show context-sensitive help (also try --help-long and
--help-man).
--version Show application version.
-q, --quiet suppress query metadata
--stats show query statistics
-o, --output=default specify output mode [default, raw, jsonl]. raw
suppresses log labels and timestamp.
-z, --timezone=Local Specify the timezone to use when formatting output
timestamps [Local, UTC]
--addr="http://localhost:3100"
Server address. Can also be set using LOKI_ADDR env
var.
--username="" Username for HTTP basic auth. Can also be set using
LOKI_USERNAME env var.
--password="" Password for HTTP basic auth. Can also be set using
LOKI_PASSWORD env var.
--ca-cert="" Path to the server Certificate Authority. Can also be
set using LOKI_CA_CERT_PATH env var.
--tls-skip-verify Server certificate TLS skip verify.
--cert="" Path to the client certificate.
--key="" Path to the client certificate key.
--org-id=ORG-ID org ID header to be substituted for auth
--cert="" Path to the client certificate. Can also be set using
LOKI_CLIENT_CERT_PATH env var.
--key="" Path to the client certificate key. Can also be set
using LOKI_CLIENT_KEY_PATH env var.
--org-id=ORG-ID adds X-Scope-OrgID to API requests for representing
tenant ID. Useful for requesting tenant data when
bypassing an auth gateway.

Commands:
help [<command>...]
Show help.

query [<flags>] <query> [<regex>]
query [<flags>] <query>
Run a LogQL query.

The "query" command is useful for querying for logs. Logs can be returned in
a few output modes:

raw: log line
default: log timestamp + log labels + log line
jsonl: JSON response from Loki API of log line

The output of the log can be specified with the "-o" flag, for example, "-o
raw" for the raw output format.

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. This extra information can be suppressed with the --quiet flag.

While "query" does support metrics queries, its output contains multiple
data points between the start and end query time. This output is used to
build graphs, like what is seen in the Grafana Explore graph view. If you
are querying metrics and just want the most recent data point (like what is
seen in the Grafana Explore table view), then you should use the
"instant-query" command instead.

instant-query [<flags>] <query>
Run an instant LogQL query.

The "instant-query" command is useful for evaluating a metric query for a
single point in time. This is equivalent to the Grafana Explore table view;
if you want a metrics query that is used to build a Grafana graph, you
should use the "query" command instead.

This command does not produce useful output when querying for log lines; you
should always use the "query" command when you are running log queries.

For more information about log queries and metric queries, refer to the
LogQL documentation:

https://github.com/grafana/loki/blob/master/docs/logql.md

labels [<label>]
Find values for a given label.

$ logcli help query
usage: logcli query [<flags>] <query> [<regex>]
usage: logcli query [<flags>] <query>

Run a LogQL query.

The "query" command is useful for querying for logs. Logs can be returned in a
few output modes:

raw: log line
default: log timestamp + log labels + log line
jsonl: JSON response from Loki API of log line

The output of the log can be specified with the "-o" flag, for example, "-o raw"
for the raw output format.

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.
This extra information can be suppressed with the --quiet flag.

While "query" does support metrics queries, its output contains multiple data
points between the start and end query time. This output is used to build
graphs, like what is seen in the Grafana Explore graph view. If you are querying
metrics and just want the most recent data point (like what is seen in the
Grafana Explore table view), then you should use the "instant-query" command
instead.

Flags:
--help Show context-sensitive help (also try --help-long and --help-man).
-q, --quiet suppress everything but log lines
-o, --output=default specify output mode [default, raw, jsonl]
--addr="https://logs-us-west1.grafana.net"
Server address.
--username="" Username for HTTP basic auth.
--password="" Password for HTTP basic auth.
--ca-cert="" Path to the server Certificate Authority.
--help Show context-sensitive help (also try --help-long and
--help-man).
--version Show application version.
-q, --quiet suppress query metadata
--stats show query statistics
-o, --output=default specify output mode [default, raw, jsonl]. raw
suppresses log labels and timestamp.
-z, --timezone=Local Specify the timezone to use when formatting output
timestamps [Local, UTC]
--addr="http://localhost:3100"
Server address. Can also be set using LOKI_ADDR env
var.
--username="" Username for HTTP basic auth. Can also be set using
LOKI_USERNAME env var.
--password="" Password for HTTP basic auth. Can also be set using
LOKI_PASSWORD env var.
--ca-cert="" Path to the server Certificate Authority. Can also be
set using LOKI_CA_CERT_PATH env var.
--tls-skip-verify Server certificate TLS skip verify.
--cert="" Path to the client certificate.
--key="" Path to the client certificate key.
--cert="" Path to the client certificate. Can also be set using
LOKI_CLIENT_CERT_PATH env var.
--key="" Path to the client certificate key. Can also be set
using LOKI_CLIENT_KEY_PATH env var.
--org-id=ORG-ID adds X-Scope-OrgID to API requests for representing
tenant ID. Useful for requesting tenant data when
bypassing an auth gateway.
--limit=30 Limit on number of entries to print.
--since=1h Lookback window.
--from=FROM Start looking for logs at this absolute time (inclusive)
--from=FROM Start looking for logs at this absolute time
(inclusive)
--to=TO Stop looking for logs at this absolute time (exclusive)
--step=STEP Query resolution step width
--forward Scan forwards through logs.
--local-config="" Execute the current query using a configured storage from a given Loki configuration file.
-t, --tail Tail the logs
--delay-for=0 Delay in tailing by number of seconds to accumulate logs for re-ordering
--no-labels Do not print any labels
--exclude-label=EXCLUDE-LABEL ...
Exclude labels given the provided key during output.
--include-label=INCLUDE-LABEL ...
Include labels given the provided key during output.
--labels-length=0 Set a fixed padding to labels
-t, --tail Tail the logs
--delay-for=0 Delay in tailing by number of seconds to accumulate
logs for re-ordering

Args:
<query> eg '{foo="bar",baz="blip"}'
[<regex>]
<query> eg '{foo="bar",baz=~".*blip"} |~ ".*error.*"'
rfratto marked this conversation as resolved.
Show resolved Hide resolved
```
44 changes: 29 additions & 15 deletions docs/logql.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,33 +1,43 @@
# LogQL: Log Query Language

Loki comes with its very own language for querying logs called *LogQL*. LogQL
can be considered a distributed `grep` with labels for filtering.
Loki comes with its own PromQL-inspired language for queries called *LogQL*.
LogQL can be considered a distributed `grep` that aggregates log sources and
using labels and operators for filtering.

A basic LogQL query consists of two parts: the **log stream selector** and a
There are two types of LogQL queries: *log queries* which return the contents of
log lines, and *metric queries* which extend log queries and calculates values
based on the counts of logs from a log query.

A basic log query consists of two parts: the **log stream selector** and a
**filter expression**. Due to Loki's design, all LogQL queries are required to
contain a log stream selector.

The log stream selector will reduce the number of log streams to a manageable
volume. Depending how many labels you use to filter down the log streams will
affect the relative performance of the query's execution. The filter expression
is then used to do a distributed `grep` over the retrieved log streams.
The log stream selector determines how many log streams (unique sources of log
content, such as files) will be searched. A more granular log stream selector
reduces the number of searched streams to a manageable volume. This means that
the labels passed to the log stream selector will affect the relative
performance of the query's execution. The filter expression is then used to do a
distributed `grep` over the aggregated logs from the matching log streams.

### Log Stream Selector

The log stream selector determines which log streams should be included in your
query. The stream selector is comprised of one or more key-value pairs, where
each key is a **log label** and the value is that label's value.
query results. The stream selector is comprised of one or more key-value pairs,
where each key is a **log label** and the value is that label's value.

The log stream selector is written by wrapping the key-value pairs in a
pair of curly braces:
The log stream selector is written by wrapping the key-value pairs in a pair of
curly braces:

```
{app="mysql",name="mysql-backup"}
```

In this example, log streams that have a label of `app` whose value is `mysql`
_and_ a label of `name` whose value is `mysql-backup` will be included in the
query results.
query results. Note that this will match any log stream whose labels _at least_
contain `mysql-backup` for their name label; if there are multiple streams that
contain that label, logs from all of the matching streams will be shown in the
results.

The `=` operator after the label name is a **label matching operator**. The
following label matching operators are supported:
Expand Down Expand Up @@ -74,10 +84,14 @@ When using `|~` and `!~`,
matching is case-sensitive by default and can be switched to case-insensitive
prefixing the regex with `(?i)`.

## Counting logs
## Metric Queries

LogQL also supports wrapping a log query with functions that allows for counting
entries per stream.

LogQL also supports functions that wrap a query and allow for counting entries
per stream.
Metric queries can be used to calculate things such as the rate of error
messages, or the top N log sources with the most amount of logs over the last 3
hours.

### Range Vector aggregation

Expand Down