victorialogs-query
Skill4 starsChanged 56 days agoMITView on GitHub
Query VictoriaLogs via curl. Use when searching logs with LogsQL, running log stats queries, discovering log fields/streams, analyzing log hit patterns, or exploring log facets. Triggers on: log queries, LogsQL, log search, log stats, field discovery, stream discovery, log facets, log hits, log field values.
1 other project uses a version of this, 1 of them edited.
Adopted by
Most recently taken up by
- TeddyAlbina/skillsedited, first seen Nov 1, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 1
- TeddyAlbina/skills★ 289% same
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository23 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- alertmanager-querySkill
- codebase-designSkill
- code-reviewSkill
- domain-modelingSkill
- grillingSkill
- grill-with-docsSkill
- implementSkill
- improve-codebase-architectureSkill
- investigating-with-observabilitySkill
- project-docs-systemSkill
- skill-creatorSkill
- stream-aggregation-helperSkill
- tddSkill
- to-specSkill
- to-ticketsSkill
- victoriametrics-cardinality-analysisSkill
- victoriametrics-querySkill
- victoriametrics-unused-metrics-analysisSkill
- victoriatraces-querySkill
- vm-trace-analyzerSkill
- wayfinderSkill
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 1 is distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 27
All curl commands load auth from a curl config file:
- Very specific: line 34
When VM_CURL_CONFIG is unset, curl reads /dev/null and sends no auth header.
- Very specific: line 38
ALWAYS pass start on ALL VictoriaLogs endpoints — omitting it scans ALL stored data (extremely expensive).
- Very specific: line 209
All times use RFC3339 format: 2026-03-07T09:00:00Z.
- Very specific: line 271
ALL endpoints accept both GET and POST with application/x-www-form-urlencoded
- Very specific: line 274
Do NOT confuse stats_query (instant, uses time) with stats_query_range (range, uses start/end/step)
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
VictoriaLogs Query
Query VictoriaLogs HTTP API directly via curl. Covers log search, stats queries, field/stream discovery, hits analysis, and facets.
Environment
# $VM_LOGS_URL - base URL
# Example: export VM_LOGS_URL="https://vlselect.example.com"
# $VM_CURL_CONFIG - curl config file with auth header (set for remote, unset for local)
# Remote: export VM_CURL_CONFIG="$HOME/.config/victoriametrics/curl.conf"
# Local: leave unset (defaults to /dev/null - no auth)Auth Pattern
All curl commands load auth from a curl config file:
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
"$VM_LOGS_URL/select/logsql/query?query=*&start=2026-03-07T00:00:00Z&limit=10"When VM_CURL_CONFIG is unset, curl reads /dev/null and sends no auth header. When set, it must point to a mode-0600 curl config file containing header = "Authorization: Bearer <token>". Never print its contents.
Critical Rules
- ALWAYS pass
starton ALL VictoriaLogs endpoints — omitting it scans ALL stored data (extremely expensive). Not technically required by the API, but omitting it is almost never what you want. stats_queryusestime(ALWAYS pass it explicitly; do not rely on a default),stats_query_rangeusesstart/end/stepstepis required forhitsendpoint/select/logsql/queryreturns JSON Lines (one JSON object per line), NOT a JSON array- LogsQL queries with special characters MUST be URL-encoded (use
--data-urlencodefor POST) stats_queryandstats_query_rangequeries MUST contain a| statspipe
Core Endpoints
Log Query
# Basic query (last hour, limit 100)
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
--data-urlencode 'query={namespace="myapp"} error' \
"$VM_LOGS_URL/select/logsql/query?start=2026-03-07T00:00:00Z&limit=100"
# With time range and field selection
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
--data-urlencode 'query={namespace="myapp"} error' \
"$VM_LOGS_URL/select/logsql/query?start=2026-03-07T00:00:00Z&end=2026-03-07T12:00:00Z&limit=50&fields=_time,_msg,level"Parameters: query (required), start (required, RFC3339), end, limit, offset, fields (comma-separated), timeout
Response: JSON Lines (one JSON object per line). Pipe through jq -s . to collect into array, or process line-by-line.
Stats Query (Instant)
# Count errors by level at a point in time
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
--data-urlencode 'query={namespace="myapp"} | stats by (level) count() as total' \
"$VM_LOGS_URL/select/logsql/stats_query?time=2026-03-07T09:00:00Z" | jq .Parameters: query (required, must contain | stats pipe), time (required, RFC3339), start (optional, alternative to time).
Response: Prometheus-compatible JSON format.
Stats Query Range
# Error count over time with 1h steps
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
--data-urlencode 'query={namespace="myapp"} error | stats count() as total' \
"$VM_LOGS_URL/select/logsql/stats_query_range?start=2026-03-07T00:00:00Z&end=2026-03-07T12:00:00Z&step=1h" | jq .Parameters: query (required, must contain | stats pipe), start (required), end, step (e.g., 1h, 5m)
Response: Prometheus matrix format.
Hits (Log Volume)
# Log volume over time
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
--data-urlencode 'query={namespace="myapp"}' \
"$VM_LOGS_URL/select/logsql/hits?start=2026-03-07T00:00:00Z&end=2026-03-07T12:00:00Z&step=1h" | jq .Parameters: query (required), start (required), end, step (required), field (optional, group by field)
Facets (Best Discovery Tool)
# Discover field value distributions
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
--data-urlencode 'query={namespace="myapp"}' \
"$VM_LOGS_URL/select/logsql/facets?start=2026-03-07T00:00:00Z&end=2026-03-07T12:00:00Z" | jq .Parameters: query (required), start (required), end. Returns most frequent values for ALL fields in one call.
Discovery Endpoints
Field Names and Values
# Discover non-stream field names
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
--data-urlencode 'query={namespace="myapp"}' \
"$VM_LOGS_URL/select/logsql/field_names?start=2026-03-07T00:00:00Z" | jq .
# Get values for a specific field
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
--data-urlencode 'query={namespace="myapp"}' \
"$VM_LOGS_URL/select/logsql/field_values?start=2026-03-07T00:00:00Z&field=level&limit=20" | jq .Stream Fields
# Discover stream field names (e.g., namespace, pod)
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
--data-urlencode 'query=*' \
"$VM_LOGS_URL/select/logsql/stream_field_names?start=2026-03-07T00:00:00Z" | jq .
# Get values for a stream field
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
--data-urlencode 'query=*' \
"$VM_LOGS_URL/select/logsql/stream_field_values?start=2026-03-07T00:00:00Z&field=namespace" | jq .Streams and Stream IDs
# List log stream identifiers
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
--data-urlencode 'query={namespace="myapp"}' \
"$VM_LOGS_URL/select/logsql/streams?start=2026-03-07T00:00:00Z&limit=20" | jq .
# List stream IDs
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
--data-urlencode 'query={namespace="myapp"}' \
"$VM_LOGS_URL/select/logsql/stream_ids?start=2026-03-07T00:00:00Z" | jq .LogsQL Quick Reference
LogsQL is space-separated (AND by default). Pipes use |.
# Stream filter (fast, use for namespace/pod selection)
{namespace="myapp"}
# Word filter (matches full words in _msg)
{namespace="myapp"} error
# Multiple words (AND)
{namespace="myapp"} error timeout
# OR filter
{namespace="myapp"} (error OR warning)
# Regex filter on _msg
{namespace="myapp"} ~"err|warn"
# Case-insensitive regex
{namespace="myapp"} ~"(?i)error"
# Field-specific filter
{namespace="myapp"} level:error
# Time filter (alternative to API start/end params)
{namespace="myapp"} _time:1h error
# Negation
{namespace="myapp"} error -"expected error"
# Stats pipe
{namespace="myapp"} _time:1h | stats by (level) count() as total
# Sort pipe
{namespace="myapp"} error | sort by (_time)
# Top pipe
{namespace="myapp"} _time:1h | top 10 (level)Common mistakes:
| grepdoes NOT exist. Use word filters or~"regex".| filteris a valid pipe but ONLY after| statsfor filtering aggregated results.- Time ranges go in API
start/endparams OR_time:filter, NOT both. - Stream field names depend on your ingestion config. ALWAYS discover them first.
- Searching "error" without filtering vmselect: vmselect logs contain PromQL text with "error" — add
-"vm_slow_query_stats"to exclude.
Timestamp Format
All times use RFC3339 format: 2026-03-07T09:00:00Z. Unix timestamps are NOT supported by VictoriaLogs.
Response Parsing (jq)
# Collect JSON Lines into array
... | jq -s .
# Extract message and timestamp from query results
... | jq -s '.[] | {time: ._time, msg: ._msg}'
# Count results from JSON Lines
... | jq -s 'length'
# Extract specific fields
... | jq -s '.[] | {time: ._time, level: .level, msg: ._msg}'
# Stats query — extract metric values
... | jq '.data.result[] | {metric: .metric, value: .value[1]}'
# Stats range query — extract time series
... | jq '.data.result[] | {metric: .metric, values: .values}'
# Facets — list fields and top values
... | jq '.[] | {field: .name, values: [.values[] | .value]}'Common Patterns
# Quick error check for a namespace (last hour)
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
--data-urlencode 'query={namespace="myapp"} error' \
"$VM_LOGS_URL/select/logsql/query?start=$(date -u -d '1 hour ago' +%Y-%m-%dT%H:%M:%SZ)&limit=20"
# Error rate over time
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
--data-urlencode 'query={namespace="myapp"} error | stats count() as errors' \
"$VM_LOGS_URL/select/logsql/stats_query_range?start=2026-03-07T00:00:00Z&step=1h" | jq .
# Discover all namespaces with logs
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
--data-urlencode 'query=*' \
"$VM_LOGS_URL/select/logsql/stream_field_values?start=2026-03-07T00:00:00Z&field=namespace" | jq .
# Search by trace ID in logs
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
--data-urlencode 'query=trace_id:"abc123def456"' \
"$VM_LOGS_URL/select/logsql/query?start=2026-03-07T00:00:00Z&limit=50"Environment Switching
# Check current environment
echo "VM_LOGS_URL: $VM_LOGS_URL"
echo "VM_CURL_CONFIG: ${VM_CURL_CONFIG:-(unset - no auth)}"Important Notes
- POST is preferred for queries with special characters — use
--data-urlencodeto avoid URL encoding issues - ALL endpoints accept both GET and POST with
application/x-www-form-urlencoded fieldparameter is required forfield_valuesandstream_field_valuesendpointsfacetsis the best single-call discovery tool — returns all field distributions at once- Do NOT confuse
stats_query(instant, usestime) withstats_query_range(range, usesstart/end/step) - For full endpoint details, parameters, and response formats, see
references/api-reference.md
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

