obz-vl: VictoriaLogs Provider
Quick Reference
| Field | Value |
|---|
| Aliases | vl, victorialogs |
| Signal | Log |
| Query language | LogsQL |
| Auth | Bearer token, Basic auth, or none |
| Provider flags | --account-id, --project-id |
| Supported cmds | log search, field-names, field-values, hits, stats |
Supported Commands
Core log commands
obz log search # Search log entries using LogsQL
Extension commands
obz log field-names # List available field names (optional --query filter)
obz log field-values # List values for a field (requires --field)
obz log hits # Show log volume over time (optional --step)
obz log stats # Run stats aggregation (requires --query)
Authentication
Configure auth in config.yaml under providers.<name>.auth. Supports
bearer token, basic auth, or no auth.
# config.yaml
providers:
vl:
endpoint: http://localhost:9428
auth:
token: ${env:VL_TOKEN}
Then query with just -p:
obz log search -p vl -q 'error' --from now-1h
Provider-Specific Flags
| Flag | Type | Required | Description |
|---|
--account-id | String | No | Multi-tenant AccountID |
--project-id | String | No | Multi-tenant ProjectID |
These flags are only needed when querying a multi-tenant VictoriaLogs cluster.
obz log search -p vl --account-id 12 --project-id 34 \
-q 'error' --from now-1h
Config File Setup
# ~/.config/obz/config.yaml
providers:
prod-vl:
provider: vl
endpoint: https://vl.prod.example.com
account-id: "12"
project-id: "34"
auth:
token: ${env:VL_TOKEN}
Then:
obz log search -p prod-vl -q 'error' --from now-1h
LogsQL Guide
LogsQL queries are built from filters combined with AND/OR/NOT operators
and optional pipes for post-processing.
Built-in Fields
_msg contains the log message body_time holds the timestamp_stream identifies the log stream (typically {key="value"} pairs)
Filter Types
Word filter (matches exact word in _msg):
error
Phrase filter (matches exact phrase):
"connection refused"
Prefix filter (matches word prefix):
err*
Regex filter:
_msg:re("error|warn")
Field filter (match on a specific field):
level:error
host:web-01
Stream filter (filter by log stream labels):
_stream:{job="api", instance="web-01"}
Time filter (usually set via --from/--to flags instead):
_time:[2024-01-01, 2024-01-02)
Combining Filters
AND (implicit when space-separated):
error _stream:{job="api"}
Explicit AND/OR/NOT:
(error OR warn) AND _stream:{job="api"} NOT "health check"
Pipes
Pipes transform results after filtering:
error | stats by (host) count() as errors
error | sort by (_time) desc | limit 50
error | fields _time, _msg, host
error | uniq by (host)
Common Pitfalls
- Bare words match against
_msg by default. To match a specific field,
use field:value syntax.
- Stream filters use curly braces:
_stream:{job="api"}. Don't forget
the _stream: prefix.
- Regex filters require the
re() wrapper: _msg:re("pattern").
- Pipes use
| as separator. The filter portion comes first, pipes after.
Examples
Simple word search:
obz log search -p vl -q 'error' --from now-1h
Stream-scoped search:
obz log search -p vl -q 'error AND _stream:{job="api"}' --from now-1h
Regex filter on message:
obz log search -p vl -q '_msg:re("timeout|refused")' --from now-6h
Field filter with pipe:
obz log search -p vl \
-q 'level:error | stats by (host) count() as errors' --from now-1d
Multi-tenant query:
obz log search -p vl --account-id 12 --project-id 34 \
-q '"connection reset"' --from now-30m
List field names:
obz log field-names -p vl --from now-1h
List values for a field:
obz log field-values -p vl --field level --from now-1h
Log volume histogram:
obz log hits -p vl -q 'error' --from now-1h --step 5m
Stats aggregation:
obz log stats -p vl -q 'error | stats by (service) count() as errors' --from now-1h