LogCLI is a powerful command-line interface tool for interacting with Grafana Loki, a horizontally scalable, highly available, multi-tenant log aggregation system. This guide provides comprehensive instructions on how to install, configure, and effectively use LogCLI for querying, analyzing, and managing your logs.

For initial setup and integration with Loki, please refer to the main Loki README: here.

LogCLI Installation

To get started, install the LogCLI binary on your system. Below are the steps for macOS, but similar procedures apply to other operating systems.

Install the binary:

$ wget https://github.com/grafana/loki/releases/download/v2.7.0/logcli-darwin-amd64.zip
$ unzip logcli-darwin-amd64.zip
$ sudo mv logcli-darwin-amd64 /usr/local/bin/logcli
$ sudo chmod +x /usr/local/bin/logcli

Environment Configuration

Configure your environment variables to connect LogCLI to your Loki instance. This is crucial for authentication and specifying the Loki API endpoint.

Configure the environment temporarily:

$ export LOKI_ADDR=https://localhost:3100
$ export LOKI_USERNAME=x
$ export LOKI_PASSWORD=x

For permanent configuration, add these exports to your shell's profile file (e.g., ~/.bashrc or ~/.zshrc).

Permanently configure the environment:

$ echo -n "
export LOKI_ADDR=https://localhost:3100
export LOKI_USERNAME=admin
export LOKI_PASSWORD=admin
" >> ~/.bashrc
$ . ~/.bashrc

Discovering Log Labels

LogCLI allows you to discover and list available labels within your Loki instance. Labels are key-value pairs that help in filtering and organizing log streams.

List all available labels:

$ logcli labels
__name__
cluster_name
container_name
environment
job

View all the job labels:

$ logcli labels job
dev/dockerlogs
prod/dockerlogs

Analyzing Log Labels

Gain deeper insights into your log data by analyzing label distributions. This helps in understanding the cardinality and usage of different labels.

Analyze labels for a specific query:

$ logcli series '{job="dev/dockerlogs"}' --analyze-labels
Total Streams:  5
Unique Labels:  4

Label Name      Unique Values  Found In Streams
container_name  5              5
cluster_name    1              5
environment     1              5
job             1              5

Querying Logs

LogCLI provides a flexible query language to retrieve specific log entries based on labels and content filters.

Query by label value:

$ logcli query '{job="dev/dockerlogs"}'

Query by label value and match filter expression:

$ logcli query '{job="dev/dockerlogs"} |= "this string"'

Query by label value and don't match filter expression:

$ logcli query '{job="dev/dockerlogs"} != "this string"'

Query by label value and regex match filter expression:

$ logcli query '{job="dev/dockerlogs"} |~ "this string: (true|false)"'

Query by label value and don't match regex filter expression:

$ logcli query '{job="dev/dockerlogs"} !~ "this string and .+"'

Advanced Query Options

Tail logs in real-time:

$ logcli query '{job="dev/dockerlogs"}' --tail

Query logs since a specific time:

$ logcli query '{job="dev/dockerlogs"}' --since 4h

Retrieve the last N log lines:

$ logcli query '{job="dev/dockerlogs"}' --last 10

Piping query results to other tools:

$ logcli query '{job="dev/dockerlogs"} |= "error"' | grep -i message

Suppress log labels in output:

$ logcli query -q '{job="dev/dockerlogs"}'

Change output format:

$ logcli query -o raw '{job="dev/dockerlogs"}'

Further Resources

For more in-depth tutorials and advanced use cases of LogCLI and Loki, explore the author's blog:

Visit my blog at blog.ruanbekker.com for more detailed tutorials.