Skip to main content
emisar

VictoriaLogs queries

v0.1.14

Read-only LogsQL access to VictoriaLogs over its HTTP API: search log entries, hit histograms over time, stats aggregations (instant + range), and field / stream discovery. Every request has an enforced trailing time window. One base URL serves single-node and vmauth-fronted deployments; multitenancy via optional headers.

7 allowed by default
Pack ID
victorialogs
Vendor
emisar
OS
linux
Actions
7
Required binaries. Install these on the host before relying on the pack — an action that calls a missing one fails at run time.
curl

Install

emisar pack install fetches this pack, re-validates it, and verifies its content hash against the --hash below — the exact bytes this page was rendered against, so a tampered copy is rejected — before copying it into the runner's packs dir. The command reloads a running daemon itself; no manual restart.

on the runner host 
sudo emisar pack install victorialogs --hash sha256:4d80ab35ca83b280df856ae5f00fed1be171c9974f02539b2951b8c0257c4190

Setup

Every action calls the VictoriaLogs LogsQL HTTP API at $VL_URL via curl on the runner host. Point VL_URL at the base URL (scheme + host + port); each action appends /select/logsql/.... Set VL_BEARER_TOKEN if the endpoint sits behind vmauth, and VL_ACCOUNT_ID / VL_PROJECT_ID to target a non-default tenant.

Environment

Set these on the runner host, then add each name to execution.inherit_env so the value reaches the action.

  • VL_URL default http://127.0.0.1:9428

    VictoriaLogs base URL — scheme, host, and port, with no trailing path. Behind vmauth, include whatever route prefix maps to the backend.

  • VL_BEARER_TOKEN

    Optional bearer token for vmauth-protected endpoints. Sent as "Authorization: Bearer <token>" over curl stdin, so it never appears in the process arguments or the audit log.

  • VL_ACCOUNT_ID

    Tenant AccountID header. Defaults to 0 when unset.

  • VL_PROJECT_ID

    Tenant ProjectID header. Defaults to 0 when unset.

Notes

  • Any of VL_URL / VL_BEARER_TOKEN / VL_ACCOUNT_ID / VL_PROJECT_ID you set must also be allowlisted in the runner's execution.inherit_env — the action env is scrubbed to PATH/LANG/LC_ALL/TERM by default, so an env present on the host but not allowlisted is silently dropped (the action falls back to its local default or fails auth).
  • Every query has a trailing window (default 1h, maximum 24h), enforced with both the HTTP range and an unconditional _time extra filter. A LogsQL _time filter may narrow that window but cannot widen it. vl.hits and vl.stats_query_range are also limited to 10,081 buckets.
  • These bounds require VictoriaLogs 1.8.0 or newer, where HTTP extra filters propagate to every subquery. Requests also carry a 30-second provider-side timeout; query cardinality can still add cost.
  • Tenancy: the default tenant is AccountID=0 / ProjectID=0. Set VL_ACCOUNT_ID / VL_PROJECT_ID to target another; they are sent as headers over curl stdin.
  • Every action is a read-only GET — none ingest, delete, or mutate logs. No token or tenant header is sent unless its env var is set.

Verify it works

Runs vl.field_names, a low-risk read that confirms the pack can reach its target. Run it on the host once the pack is installed; pack install runs it for you.

on the runner host 
sudo emisar pack verify victorialogs

Install and configure a pack walks through the whole sequence on a host.

Actions 7 total

View on GitHub
  • vl.field_names script low Low — read-only or trivially reversible

    GET /select/logsql/field_names

    List the log field names matching a query, each with a hit count. Use to discover what fields exist before querying. Doubles as the pack's connectivity check.

    View source on GitHub
  • vl.field_values script medium Medium — changes state, easily reversible

    GET /select/logsql/field_values

    List the most frequent values of one log field, each with a hit count. Use to enumerate levels, namespaces, hosts, or any other dimension. Rated medium because the field argument accepts _msg, returning raw log message text (matching vl.query) that no redaction list can enumerate.

    View source on GitHub
  • vl.hits script low Low — read-only or trivially reversible

    GET /select/logsql/hits

    Count log entries matching a LogsQL query, bucketed over time by step — the histogram behind "how many errors per hour?". The trailing window is bounded by the server's retention and the window-to-step ratio to 10,081 buckets.

    View source on GitHub
  • vl.query script medium Medium — changes state, easily reversible

    GET /select/logsql/query

    Run a LogsQL query and return matching log entries as newline-delimited JSON. Every request has a trailing window ending now, bounded only by the server's retention; the limit arg caps how many entries come back.

    View source on GitHub
  • vl.stats_query script low Low — read-only or trivially reversible

    GET /select/logsql/stats_query

    Show instant stats over logs — a LogsQL query containing a "| stats" pipe, evaluated at one point in time and returned in Prometheus instant-query format. Use for totals like counts or sums grouped by a field.

    View source on GitHub
  • vl.stats_query_range script low Low — read-only or trivially reversible

    GET /select/logsql/stats_query_range

    Show stats over logs across a time range — a LogsQL query containing a "| stats" pipe, evaluated at each step and returned in Prometheus range-query (matrix) format. The trailing window is bounded by the server's retention and the window-to-step ratio to 10,081 evaluation timestamps.

    View source on GitHub
  • vl.streams script low Low — read-only or trivially reversible

    GET /select/logsql/streams

    List the log streams matching a query, each with a hit count. A stream is the set of logs sharing the same stream labels (app, host, container, …). Use to see which sources are sending logs.

    View source on GitHub
← Back to registry
Pack reference  Publish your own