/usr/bin/logcli

usage: logcli [<flags>] <command> [<args> ...]

A command-line for loki.


Flags:
      --[no-]help             Show context-sensitive help (also try --help-long and --help-man).
      --[no-]version          Show application version.
  -q, --[no-]quiet            Suppress query metadata
      --log.level=error       Log level
      --[no-]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]
      --output-timestamp-format=rfc3339
                              Specify the format of timestamps in the default output mode [rfc3339,
                              rfc3339nano, rfc822z, rfc1123z, stampmicro, stampmilli, stampnano,
                              unixdate]
      --cpuprofile=""         Specify the location for writing a CPU profile.
      --memprofile=""         Specify the location for writing a memory profile.
      --[no-]stdin            Take input logs from stdin
      --addr="http://localhost:3100"
                              Server address. Can also be set using LOKI_ADDR env var. ($LOKI_ADDR)
      --username=""           Username for HTTP basic auth. Can also be set using LOKI_USERNAME env
                              var. ($LOKI_USERNAME)
      --password=""           Password for HTTP basic auth. Can also be set using LOKI_PASSWORD env
                              var. ($LOKI_PASSWORD)
      --ca-cert=""            Path to the server Certificate Authority. Can also be set using
                              LOKI_CA_CERT_PATH env var. ($LOKI_CA_CERT_PATH)
      --[no-]tls-skip-verify  Server certificate TLS skip verify. Can also be set using
                              LOKI_TLS_SKIP_VERIFY env var. ($LOKI_TLS_SKIP_VERIFY)
      --cert=""               Path to the client certificate. Can also be set using
                              LOKI_CLIENT_CERT_PATH env var. ($LOKI_CLIENT_CERT_PATH)
      --key=""                Path to the client certificate key. Can also be set using
                              LOKI_CLIENT_KEY_PATH env var. ($LOKI_CLIENT_KEY_PATH)
      --org-id=""             adds X-Scope-OrgID to API requests for representing tenant ID.
                              Useful for requesting tenant data when bypassing an auth gateway.
                              Can also be set using LOKI_ORG_ID env var. ($LOKI_ORG_ID)
      --query-tags=""         adds X-Query-Tags http header to API requests. This header value will
                              be part of `metrics.go` statistics. Useful for tracking the query.
                              Can also be set using LOKI_QUERY_TAGS env var. ($LOKI_QUERY_TAGS)
      --[no-]nocache          adds Cache-Control: no-cache http header to API requests. Can also be
                              set using LOKI_NO_CACHE env var. ($LOKI_NO_CACHE)
      --bearer-token=""       adds the Authorization header to API requests for authentication
                              purposes. Can also be set using LOKI_BEARER_TOKEN env var.
                              ($LOKI_BEARER_TOKEN)
      --bearer-token-file=""  adds the Authorization header to API requests for authentication
                              purposes. Can also be set using LOKI_BEARER_TOKEN_FILE env var.
                              ($LOKI_BEARER_TOKEN_FILE)
      --retries=0             How many times to retry each query when getting an error response
                              from Loki. Can also be set using LOKI_CLIENT_RETRIES env var.
                              ($LOKI_CLIENT_RETRIES)
      --min-backoff=0         Minimum backoff time between retries. Can also be set using
                              LOKI_CLIENT_MIN_BACKOFF env var. ($LOKI_CLIENT_MIN_BACKOFF)
      --max-backoff=0         Maximum backoff time between retries. Can also be set using
                              LOKI_CLIENT_MAX_BACKOFF env var. ($LOKI_CLIENT_MAX_BACKOFF)
      --auth-header="Authorization"
                              The authorization header used. Can also be set using LOKI_AUTH_HEADER
                              env var. ($LOKI_AUTH_HEADER)
      --proxy-url=""          The http or https proxy to use when making requests. Can also be set
                              using LOKI_HTTP_PROXY_URL env var. ($LOKI_HTTP_PROXY_URL)
      --[no-]compress         Request that Loki compress returned data in transit. Can also be set
                              using LOKI_HTTP_COMPRESSION env var. ($LOKI_HTTP_COMPRESSION)
      --[no-]envproxy         Use ProxyFromEnvironment to use net/http ProxyFromEnvironment
                              configuration, eg HTTP_PROXY ($LOKI_ENV_PROXY)

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

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.

    By default we look over the last hour of data; use --since to modify or provide specific start
    and end times with --from and --to respectively.

    Notice that when using --from and --to then ensure to use RFC3339Nano time format, but without
    timezone at the end. The local timezone will be added automatically or if using --timezone flag.
    In default output mode the --output-timestamp-format flag can be used to modify the output
    timestamp.

    Example:

      logcli query
         --timezone=UTC
         --from="2021-01-19T10:00:00Z"
         --to="2021-01-19T20:00:00Z"
         --output=jsonl
         'my-query'

    Example with --output-timestamp-format:

      logcli query
         --timezone=UTC
         --from="2021-01-19T10:00:00Z"
         --to="2021-01-19T20:00:00Z"
         --output-timestamp-format=rfc3339nano
         'my-query'

    The output is limited to 30 entries by default; use --limit to increase.

    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, similar to 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.

    Parallelization:

    You can download an unlimited number of logs in parallel, there are a few flags which control
    this behaviour:

      --parallel-duration
      --parallel-max-workers
      --part-path-prefix
      --overwrite-completed-parts
      --merge-parts
      --keep-parts

    Refer to the help for each flag for details about what each of them do.

    Example:

      logcli query
         --timezone=UTC
         --from="2021-01-19T10:00:00Z"
         --to="2021-01-19T20:00:00Z"
         --output=jsonl
         --parallel-duration="15m"
         --parallel-max-workers="4"
         --part-path-prefix="/tmp/my_query"
         --merge-parts
         'my-query'

    This example will create a queue of jobs to execute, each being 15 minutes in duration.
    In this case, that means, for the 10-hour total duration, there will be forty 15-minute jobs.
    The --limit flag is ignored.

    It will start four workers, and they will each take a job to work on from the queue until all
    the jobs have been completed.

    Each job will save a "part" file to the location specified by the --part-path-prefix. Different
    prefixes can be used to run multiple queries at the same time. The timestamp of the start and
    end of the part is in the file name. While the part is being downloaded, the filename will end
    in ".part", when it is complete, the file will be renamed to remove this ".part" extension.
    By default, if a completed part file is found, that part will not be downloaded again. This can
    be overridden with the --overwrite-completed-parts flag.

    Part file example using the previous command, adding --keep-parts so they are not deleted:

    Since we don't have the --forward flag, the parts will be downloaded in reverse. Two of the
    workers have finished their jobs (last two files), and have picked up the next jobs in the
    queue. Running ls, this is what we should expect to see.

    $ ls -1 /tmp/my_query* /tmp/my_query_20210119T183000_20210119T184500.part.tmp
    /tmp/my_query_20210119T184500_20210119T190000.part.tmp
    /tmp/my_query_20210119T190000_20210119T191500.part.tmp
    /tmp/my_query_20210119T191500_20210119T193000.part.tmp
    /tmp/my_query_20210119T193000_20210119T194500.part
    /tmp/my_query_20210119T194500_20210119T200000.part

    If you do not specify the --merge-parts flag, the part files will be downloaded, and logcli will
    exit, and you can process the files as you wish. With the flag specified, the part files will
    be read in order, and the output printed to the terminal. The lines will be printed as soon as
    the next part is complete, you don't have to wait for all the parts to download before getting
    output. The --merge-parts flag will remove the part files when it is done reading each of them.
    To change this, you can use the --keep-parts flag, and the part files will not be removed.

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://grafana.com/docs/loki/latest/logql/

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

series [<flags>] <matcher>
    Run series query.

    The "series" command will take the provided label matcher and return all the log streams found
    in the time window.

    It is possible to send an empty label matcher '{}' to return all streams.

    Use the --analyze-labels flag to get a summary of the labels found in all streams. This is
    helpful to find high cardinality labels.

fmt
    Formats a LogQL query.

stats [<flags>] <query>
    Run a stats query.

    The "stats" command will take the provided query and return statistics from the index on how
    much data is contained in the matching stream(s). This only works against Loki instances using
    the TSDB index format.

    By default we look over the last hour of data; use --since to modify or provide specific start
    and end times with --from and --to respectively.

    Notice that when using --from and --to then ensure to use RFC3339Nano time format, but without
    timezone at the end. The local timezone will be added automatically or if using --timezone flag.

    Example:

      logcli stats
         --timezone=UTC
         --from="2021-01-19T10:00:00Z"
         --to="2021-01-19T20:00:00Z"
         'my-query'

volume [<flags>] <query>
    Run a volume query.

    The "volume" command will take the provided label selector(s) and return aggregate volumes
    for series matching those volumes. This only works against Loki instances using the TSDB index
    format.

    By default we look over the last hour of data; use --since to modify or provide specific start
    and end times with --from and --to respectively.

    Notice that when using --from and --to then ensure to use RFC3339Nano time format, but without
    timezone at the end. The local timezone will be added automatically or if using --timezone flag.

    Example:

      logcli volume
         --timezone=UTC
         --from="2021-01-19T10:00:00Z"
         --to="2021-01-19T20:00:00Z"
         'my-query'

volume_range [<flags>] <query>
    Run a volume query and return timeseries data.

    The "volume_range" command will take the provided label selector(s) and return aggregate
    volumes for series matching those volumes, aggregated into buckets according to the step value.
    This only works against Loki instances using the TSDB index format.

    By default we look over the last hour of data; use --since to modify or provide specific start
    and end times with --from and --to respectively.

    Notice that when using --from and --to then ensure to use RFC3339Nano time format, but without
    timezone at the end. The local timezone will be added automatically or if using --timezone flag.

    Example:

      	logcli volume_range
      	   --timezone=UTC
      	   --from="2021-01-19T10:00:00Z"
      	   --to="2021-01-19T20:00:00Z"
           --step=1h
      	   'my-query'

detected-fields [<flags>] <query> [<field>]
    Run a query for detected fields..

    The "detected-fields" command will return information about fields detected using either the
    "logfmt" or "json" parser against the log lines returned by the provided query for the provided
    time range.

    The "detected-fields" 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.

    By default we look over the last hour of data; use --since to modify or provide specific start
    and end times with --from and --to respectively.

    Notice that when using --from and --to then ensure to use RFC3339Nano time format, but without
    timezone at the end. The local timezone will be added automatically or if using --timezone flag.

    Example:

      logcli detected-fields
         --timezone=UTC
         --from="2021-01-19T10:00:00Z"
         --to="2021-01-19T20:00:00Z"
         --output=jsonl
         'my-query'

    The output is limited to 100 fields by default; use --field-limit to increase. The query is
    limited to processing 1000 lines per subquery; use --line-limit to increase.

delete create [<flags>] <query>
    Create a new log deletion request.

    The "delete create" command creates a new log deletion request for the specified query and time
    range.

    Example:

      logcli delete create '{job="app"}' --from="2023-01-01T00:00:00Z" --to="2023-01-02T00:00:00Z"

delete list
    List existing log deletion requests.

    The "delete list" command lists all existing log deletion requests for the tenant.

    Example:

      logcli delete list
      logcli delete list --output=json

delete cancel --request-id=REQUEST-ID [<flags>]
    Cancel a log deletion request.

    The "delete cancel" command cancels an existing log deletion request by ID.

    Example:

      logcli delete cancel --request-id="abc123"
      logcli delete cancel --request-id="abc123" --force