clarify logcli commands and output

This commit attempts to do two things: 1. Differentiate between log entries and raw log lines, where the latter is what is produced by `-oraw`. 2. Explain the difference between `logcli query` and `logcli instant-query`. Fixes #1676.
grafana · Mar 30, 2020 · 5031e7a · 5031e7a
1 parent ba51aad
commit 5031e7a
Show file tree

Hide file tree

Showing 2 changed files with 114 additions and 24 deletions.
diff --git a/cmd/logcli/main.go b/cmd/logcli/main.go
@@ -20,20 +20,36 @@ 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 everything but log entries").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")
 	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 default output of this command are log entries (combination of
+timestamp, labels, and log line) along with metainformation about the query
+made to Loki.  The metainformation can be filtered out using the --quiet
+flag. Raw log lines (i.e., no labels or timestamp) can be retrieved using
+-oraw.
+
+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.`)
 	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.
+
+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.`)
+	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()

diff --git a/docs/getting-started/logcli.md b/docs/getting-started/logcli.md
@@ -72,53 +72,128 @@ A command-line for loki.
 
 Flags:
       --help             Show context-sensitive help (also try --help-long and --help-man).
-  -q, --quiet            suppress everything but log lines
+      --version          Show application version.
+  -q, --quiet            suppress everything but log entries
+      --stats            show query statistics
   -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.
+  -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    org ID header to be substituted for auth
 
 Commands:
   help [<command>...]
     Show help.
 
-  query [<flags>] <query> [<regex>]
+  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 metainformation about the query
+    made to Loki. The metainformation can be filtered out using the --quiet
+    flag. Raw log lines (i.e., no labels or timestamp) can be retrieved using
+    -oraw.
+
+    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.
+
+  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.
+
   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 default output of this command are log entries (combination of timestamp,
+labels, and log line) along with metainformation about the query made to Loki.
+The metainformation can be filtered out using the --quiet flag. Raw log lines
+(i.e., no labels or timestamp) can be retrieved using -oraw.
+
+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.
+
 Flags:
       --help             Show context-sensitive help (also try --help-long and --help-man).
-  -q, --quiet            suppress everything but log lines
+      --version          Show application version.
+  -q, --quiet            suppress everything but log entries
+      --stats            show query statistics
   -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.
+  -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    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)
       --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.
+      --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"} |~ ".*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.
+
+Flags:
+      --help             Show context-sensitive help (also try --help-long and --help-man).
+      --version          Show application version.
+  -q, --quiet            suppress everything but log entries
+      --stats            show query statistics
+  -o, --output=default   specify output mode [default, raw, jsonl]
+  -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. 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.
+      --forward          Scan forwards through logs.
       --no-labels        Do not print any labels
       --exclude-label=EXCLUDE-LABEL ...
                          Exclude labels given the provided key during output.
@@ -127,6 +202,5 @@ Flags:
       --labels-length=0  Set a fixed padding to labels
 
 Args:
-  <query>    eg '{foo="bar",baz="blip"}'
-  [<regex>]
+  <query>  eg '{foo="bar",baz=~".*blip"} |~ ".*error.*"'
 ```