Skip to content

Commit

Permalink
explain that instant-query is not useful for log lines
Browse files Browse the repository at this point in the history
  • Loading branch information
@rfratto
rfratto committed Mar 30, 2020
1 parent 13ddf0b commit fe898ad
Show file tree
Hide file tree
Showing 2 changed files with 122 additions and 75 deletions.
39 changes: 23 additions & 16 deletions cmd/logcli/main.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,27 +29,33 @@ var (

queryCmd = app.Command("query", `Run a LogQL query.
The default output of this command are log entries (combination of
timestamp, labels, and log line) along with various extra information
about the query and its results. Raw log lines (i.e., no labels or timestamp)
can be retrieved by passing the flag "-o raw", while the extra information (URL
queried, set of common labels, excluded labels) can be suppressed with the
--quiet flag.
When running a metrics query, this command outputs multiple data points
between the start and the end query time. This produces values that are
used to build graphs. If you just want a single data point (i.e., the
Grafana explore "table"), then you should use instant-query instead.`)
The "query" command is useful for querying for log lines. The default
output of this command are log entries (a combination of timestamp,
labels, and a log line) along with various extra information about
the performed query and its results. Raw log lines (i.e., without a
label and timestamp) can be retrieved by passing the "-o raw" flag.
The extra information about the query (API URL, set of common labels,
excluded labels) can be suppressed with the --query 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.
This query type can only be used for metrics queries, where the query is
evaluated for a single point in time. This is equivalent to the Grafana
explore "table" view; if you want data that is used to build the Grafana
graph, you should use query instead.`)
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.`)
instantQuery = newQuery(true, instantQueryCmd)

labelsCmd = app.Command("labels", "Find values for a given label.")
Expand Down Expand Up @@ -170,11 +176,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
158 changes: 99 additions & 59 deletions docs/getting-started/logcli.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -71,20 +71,29 @@ usage: logcli [<flags>] <command> [<args> ...]
A command-line for loki.
Flags:
--help Show context-sensitive help (also try --help-long and --help-man).
--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]
-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.
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. 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.
--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 org ID header to be substituted for auth
Commands:
Expand All @@ -94,25 +103,31 @@ Commands:
query [<flags>] <query>
Run a LogQL query.
The default output of this command are log entries (combination of
timestamp, labels, and log line) along with various extra information about
the query and its results. Raw log lines (i.e., no labels or timestamp) can
be retrieved by passing the flag "-o raw", while the extra information (URL
queried, set of common labels, excluded labels) can be suppressed with the
--quiet flag.
When running a metrics query, this command outputs multiple data points
between the start and the end query time. This produces values that are
used to build graphs. If you just want a single data point (i.e., the
Grafana explore "table"), then you should use instant-query instead.
The "query" command is useful for querying for log lines. The default output
of this command are log entries (a combination of timestamp, labels, and a
log line) along with various extra information about the performed query and
its results. Raw log lines (i.e., without a label and timestamp) can be
retrieved by passing the "-o raw" flag. The extra information about the
query (API URL, set of common labels, excluded labels) can be suppressed
with the --query 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.
This query type can only be used for metrics queries, where the query is
evaluated for a single point in time. This is equivalent to the Grafana
explore "table" view; if you want data that is used to build the Grafana
graph, you should use query instead.
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.
labels [<label>]
Find values for a given label.
Expand All @@ -122,36 +137,49 @@ usage: logcli query [<flags>] <query>
Run a LogQL query.
The default output of this command are log entries (combination of timestamp,
labels, and log line) along with various extra information about the query and
its results. Raw log lines (i.e., no labels or timestamp) can be retrieved by
passing the flag "-o raw", while the extra information (URL queried, set of
common labels, excluded labels) can be suppressed with the --quiet flag.
The "query" command is useful for querying for log lines. The default output of
this command are log entries (a combination of timestamp, labels, and a log
line) along with various extra information about the performed query and its
results. Raw log lines (i.e., without a label and timestamp) can be retrieved by
passing the "-o raw" flag. The extra information about the query (API URL, set
of common labels, excluded labels) can be suppressed with the --query flag.
When running a metrics query, this command outputs multiple data points between
the start and the end query time. This produces values that are used to build
graphs. If you just want a single data point (i.e., the Grafana explore
"table"), then you should use instant-query instead.
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).
--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]
-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.
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. 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.
--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 org ID header to be substituted for auth
--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.
Expand All @@ -163,37 +191,49 @@ Flags:
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
--delay-for=0 Delay in tailing by number of seconds to accumulate
logs for re-ordering
Args:
<query> eg '{foo="bar",baz=~".*blip"} |~ ".*error.*"'
$ logcli help instant-query
usage: logcli instant-query [<flags>] <query>
Run an instant LogQL query.
This query type can only be used for metrics queries, where the query is
evaluated for a single point in time. This is equivalent to the Grafana explore
"table" view; if you want data that is used to build the Grafana graph, you
should use query instead.
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.
Flags:
--help Show context-sensitive help (also try --help-long and --help-man).
--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]
-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.
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. 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.
--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 org ID header to be substituted for auth
--limit=30 Limit on number of entries to print.
--now=NOW Time at which to execute the instant query.
Expand All @@ -206,5 +246,5 @@ Flags:
--labels-length=0 Set a fixed padding to labels
Args:
<query> eg '{foo="bar",baz=~".*blip"} |~ ".*error.*"'
<query> eg 'rate({foo="bar"} |~ ".*error.*" [5m])'
```

0 comments on commit fe898ad

Please sign in to comment.