Skip to content
LogchefLogchef

Using VictoriaLogs with Logchef

Logchef supports VictoriaLogs as a first-class datasource. The goal is a shared Logchef experience for everyday workflows, with raw LogsQL available when you want VictoriaLogs-native pipes directly. This page covers connecting a source and day-to-day usage; for what Logchef adds on top of VictoriaLogs’ own UI, see VictoriaLogs Explorer.

What Works Well

Section titled “What Works Well”
  • Add a VictoriaLogs datasource with optional tenant headers and immutable source scope
  • Query in LogchefQL for common filtering workflows
  • Drop into LogsQL for native VictoriaLogs features
  • Explore histograms, field values, and saved queries
  • Create alerts in either:
    • Condition mode using LogchefQL
    • Native mode using LogsQL

Ingesting Data

Section titled “Ingesting Data”

Logchef does not ingest into VictoriaLogs directly. You send logs to VictoriaLogs using your normal shipper, then point Logchef at the VictoriaLogs API.

The local development setup in this repo uses Vector with the VictoriaLogs Elasticsearch-compatible ingestion endpoint:

[sinks.victorialogs]
type = "elasticsearch"
inputs = ["remap_logs"]
endpoints = ["http://localhost:9428/insert/elasticsearch/"]
mode = "bulk"
api_version = "v8"
compression = "gzip"


[sinks.victorialogs.request.headers]
VL-Stream-Fields = "service,host,env"
VL-Time-Field = "datetime"
VL-Msg-Field = "message"

See the official VictoriaLogs docs for more ingestion patterns:

Add The Datasource

Section titled “Add The Datasource”

When adding a VictoriaLogs source in Logchef:

  • Set the Base URL to the VictoriaLogs API endpoint
  • Choose auth mode:
    • none — no credentials sent
    • basic auth — username + password, sent as an Authorization: Basic ... header
    • bearer token — sent as Authorization: Bearer <token>
  • Set Account ID and Project ID together if you use multi-tenant VictoriaLogs — both are required together, and both must be numeric (VictoriaLogs tenants are uint32 account/project IDs). Logchef sends them as AccountID / ProjectID request headers on every call.
  • Optionally add custom headers, e.g. an API key for a fronting proxy
  • Optionally define an Immutable Scope Query

Examples of immutable scope:

{app="payments"}
kubernetes.namespace:="prod"

Logchef applies that scope server-side to every query, histogram, field-values lookup, live tail, and alert evaluation for that datasource — it can’t be overridden from the query editor.

When you save the source, Logchef validates the connection by checking /health and then running a small field_names query with your configured auth, tenant headers, and scope applied. This catches a wrong base URL, bad credentials, or an invalid scope filter at setup time rather than on the first real query. Editing a source later and leaving a credential field blank keeps the previously-stored value — you only need to re-enter a username/password/token when you’re changing it (or switching auth mode to “none”, which clears any stored credentials for that source).

Query Modes

Section titled “Query Modes”

LogchefQL

Section titled “LogchefQL”

Use LogchefQL when you want the same simple filter workflow across backends.

level = "error"
service = "api" and status_code >= 500
_msg ~ "timeout"

For VictoriaLogs sources, Logchef compiles LogchefQL to LogsQL before execution.

Examples:

LogchefQL Generated LogsQL
level = "error" level:="error"
status_code >= 500 status_code:>=500
_msg ~ "timeout" _msg:~"(?i)timeout"
service = "api" and env = "prod" (service:="api") AND (env:="prod")

LogsQL

Section titled “LogsQL”

Use native LogsQL when you want VictoriaLogs-specific pipes and advanced query composition.

service:="api" level:="error" | fields _time, _msg, service, level

Use native LogsQL when you need:

  • stats
  • facets
  • fields
  • unpack_json
  • other VictoriaLogs-native pipe flows

Live Tail

Section titled “Live Tail”

VictoriaLogs sources support Live Tail from the explorer’s Live toggle. Unlike ClickHouse (which is polled on an interval), Logchef proxies VictoriaLogs’ native /select/logsql/tail stream directly, so new rows arrive as a genuine push rather than a poll. Live tail is available in LogchefQL mode and in native LogsQL mode; the time-range and limit controls are disabled while a tail is running, since a tail follows new data rather than answering a bounded query.

New rows are streamed into the UI in small batches (flushed whenever enough rows have accumulated, or at least every 200ms so a slow trickle of logs still shows up promptly). If the underlying tail connection drops because VictoriaLogs restarted or the network hiccuped — rather than because you stopped the tail yourself — Logchef surfaces that as a lost connection rather than a normal stop, so it’s clear whether the tail ended because you asked it to or because something broke.

Your source’s immutable scope filter and tenant headers apply to live tail the same way they apply to regular queries — a tail can only ever stream the data the source is scoped to.

Known limitations

Section titled “Known limitations”

A few Logchef features are ClickHouse-only for now and are not available on VictoriaLogs sources:

  • AI SQL generation: the AI assistant only writes ClickHouse SQL.
  • Log context (“surrounding logs”): jumping from a row to the logs around it.
  • Exports / downloads: streaming a full result set to CSV or NDJSON.

Everything else in this guide (explore, histograms, field values, saved queries, live tail, and alerting) works the same as on ClickHouse.

Result Views

Section titled “Result Views”

Logchef keeps the result experience backend-neutral:

  • Table
  • Compact
  • JSON

You do not need a VictoriaLogs-specific result mode for normal exploration. Switch to raw LogsQL when the query itself needs to become VictoriaLogs-specific.

Alerting

Section titled “Alerting”

VictoriaLogs alerts in Logchef should return a single numeric value named value.

Condition Mode

Section titled “Condition Mode”

Condition mode is the simplest path for common threshold alerts:

level = "error" and service = "payments"

Logchef compiles that filter to LogsQL and wraps it in a stats query for evaluation.

Native LogsQL Mode

Section titled “Native LogsQL Mode”

Use native mode when you want full control:

level:="error" service:="payments" | stats count() as value
response_time:* service:="api" | stats avg(response_time) as value

Important rules:

  • Return a single numeric result
  • Alias it as value
  • Let Logchef apply the alert lookback window automatically

Logchef evaluates the query through VictoriaLogs’ stats_query endpoint and prepends a _time:<lookback> filter (e.g. _time:5m) built from the alert’s configured lookback — so in the common case you can leave the time window out of your query entirely. If your native query already includes its own _time: filter, Logchef leaves it alone instead of stacking a second one on top (LogsQL ANDs multiple _time filters together, so adding another would only narrow, or even zero out, a window you already scoped intentionally).

When To Use LogchefQL vs LogsQL

Section titled “When To Use LogchefQL vs LogsQL”

Use LogchefQL when:

  • you want a shared query experience across ClickHouse and VictoriaLogs
  • you are doing straightforward filter-based exploration
  • you are building threshold alerts from common predicates

Use LogsQL when:

  • you need VictoriaLogs pipes directly
  • you want stream-aware field shaping
  • you need stats, facets, or unpacking operators that are outside LogchefQL
Section titled “Recommended Field Mapping”

For VictoriaLogs sources, good defaults are:

  • Timestamp field: _time
  • Severity field: level or your dataset’s severity field
  • Message field in your dataset: _msg if you use VL-Msg-Field

For cleaner exploration, prefer stream fields that represent stable source identity, such as:

  • service
  • host
  • env
  • namespace

Avoid highly-cardinal request-specific fields as stream fields.

Next Steps

Section titled “Next Steps”