obz-loki

name	obz-loki
description	Grafana Loki provider for obz. Covers log search using LogQL, a label-based query language for log aggregation. This skill should be used when the user mentions "Loki", "Grafana Loki", "LogQL", "obz log search -p loki", or needs to search logs from a Loki instance.

obz-loki: Grafana Loki Provider

Quick Reference

Field	Value
Aliases	loki
Signal	Log
Query language	LogQL
Auth	Bearer token or Basic auth
Provider flags	None
Supported cmds	log search, labels, label-values, fields, stats

Supported Commands

Core log commands

obz log search         # Search log entries using LogQL

Extension commands

obz log labels         # List label names (no flags)
obz log label-values   # List values for a label (requires --label)
obz log fields         # List detected fields (optional --query)
obz log stats          # Run instant aggregation (requires --query with LogQL metric query)

Authentication

Configure auth in config.yaml under providers.<name>.auth. Supports bearer token, basic auth, or no auth.

# config.yaml
providers:
  loki:
    endpoint: http://localhost:3100
    auth:
      token: ${env:LOKI_TOKEN}

For basic auth (common with Grafana Cloud):

    auth:
      username: user
      password: ${env:LOKI_PASS}

Then query with just -p:

obz log search -p loki -q '{job="api"} |= "error"' --from now-1h

LogQL Guide

LogQL is Loki's query language. Every query starts with a log stream selector (labels in curly braces), optionally followed by filter and parser stages.

Stream Selectors

{job="api"}                          # exact match
{job="api", env="prod"}              # multiple labels
{job=~"api|web"}                     # regex match
{job!="debug"}                       # not equal

Line Filters

{job="api"} |= "error"              # line contains "error"
{job="api"} != "health"             # line does NOT contain "health"
{job="api"} |~ "status=[45]\\d{2}"  # line matches regex
{job="api"} !~ "debug|trace"        # line does NOT match regex

Parser Stages

{job="api"} | json                   # parse JSON fields
{job="api"} | logfmt                 # parse logfmt fields
{job="api"} | json | level="error"   # parse then filter by field

Chaining Filters

Filters chain left to right. Each stage narrows the results further:

{job="api"} |= "error" != "timeout" | json | status >= 500

Examples

Basic log search:

obz log search -p loki -q '{job="api"} |= "error"' --from now-1h

Search with regex filter:

obz log search -p loki \
  -q '{job="api"} |~ "status=(500|502|503)"' --from now-6h

Parse JSON logs and filter by field:

obz log search -p loki \
  -q '{job="api"} | json | level="error"' --from now-30m

Multi-label selector:

obz log search -p loki \
  -q '{job="api", env="prod", cluster="us-east"}' --from now-1h

List label names:

obz log labels -p loki

List values for a label:

obz log label-values -p loki --label job

List detected fields:

obz log fields -p loki -q '{job="api"}' --from now-1h

Stats aggregation (instant query):

obz log stats -p loki -q 'count_over_time({job="api"}[5m])' --from now-1h

Tips

• Labels are indexed. Put your most selective label first for better performance.
• Line filters (|=, !=) are fast. Use them before parser stages to reduce the volume of data Loki has to parse.
• Quote your LogQL with single quotes on the CLI to avoid shell interpretation of curly braces and pipes.