Exported logs from servers, containers, and CI are often unformatted, one giant line, and sometimes double-encoded even. This plugin presents logs into a more human-readable format, capabilities to search, filter, and group the data, and customizability.
- Any JSON log: JSONL, JSON arrays and timestamped log exports; double-encoded JSON is unwrapped, and nothing is dropped or reformatted.
- Readable view: one compact line or indented JSON per entry, searchable with
/and:g. - Filter and group: a small query language (
status>=500 -health), group by any field, and top values per field in the sidebar. - Big and live files: the first screen of a 500k-line file in about 100ms, and the view follows the file as it grows.
- Customizable: field styles, sidebar, keymaps and highlights.
- Neovim >= 0.10 (
:checkhealth jlogconfirms it)
With lazy.nvim:
{ "kcayme/jlog.nvim", opts = {} }setup() is optional; without it jlog runs with the defaults below.
- Open a log file and run
:JLog(or:JLog path/to/app.log). It opens in its own tab, with the sidebar on the right. - Press
<CR>on an entry to expand it,Eto expand them all. - In the sidebar, type
status>=500underFILTERS, orrequest_idunderGROUP BY, then:w. - Or press
<CR>on values inFIELDSto filter by them (one line each,ORbetween values of a field),gon a field to group by it. ?in the sidebar lists every key;qcloses the workspace.
Defaults (all optional):
require("jlog").setup({
fields = {
time = { "time", "ts", "timestamp", "@timestamp", "time_stamp", "timeStamp" },
level = { "level", "lvl", "severity" },
message = { "msg", "message" },
status = { "status", "status_code" }, -- class-colored (2xx-5xx) when styled inverted/pill
},
compact = {
style = "plain", -- "plain" | "inverted" | "pill"; level defaults to "inverted"
order = {}, -- top-level keys shown first, e.g. { "method", "path", "status" }
fields = {}, -- per key or role: { style = "pill", format = function(ctx) return ctx.value end }
pill = { left = "\238\130\182", right = "\238\130\180" }, -- Nerd Font caps; "" for square ends
style_values = { "level", "status" }, -- keys or roles styled on the value instead of the key
},
view = {
mode = "compact",
sort = "desc", -- "desc" shows the newest entries first
field_colors = true,
-- os.date format for compact-line times (%L is milliseconds), false for HH:MM:SS.mmm as written, or a function:
-- function(t) return t.value end shows the time unformatted
time_format = "%Y-%m-%d %H:%M:%S",
time_utc = false, -- show time_format times in UTC instead of local time
ignore_fields = {}, -- field paths left out of compact lines, e.g. { "hostname", "req.headers" }
},
unwrap = { enable = true, max_depth = 4 },
sidebar = {
width = 45,
position = "right",
line_numbers = false, -- show line numbers in the sidebar
foldable = true, -- fold a section under its header: <CR> on the header, or za
-- apply FILTERS, GROUP BY and LIMIT edits without :w, once edits pause for debounce_ms
auto_apply = { enable = false, debounce_ms = 600 },
fields = { -- how FIELDS lists and styles field names
colors = true, -- false: every name uses JLogFieldName
style = "plain", -- "plain", "inverted" or "pill", like compact fields
pill = { left = "\238\130\182", right = "\238\130\180" }, -- Nerd Font caps; "" for square ends
-- per field path or role, e.g. { level = { style = "pill" } }; a format(ctx) gets ctx.name and ctx.distinct
-- and returns the name's text and optionally a highlight group
styles = {},
pinned = {}, -- field paths or roles listed first, e.g. { "level", "status", "path" }
-- the other fields: "alphabetical", or "count" (in the most entries first; applied once the counts are final,
-- so rows hold still while a file loads)
sort = "alphabetical",
counts = true, -- false hides each value's count; values are still counted to find and order them
},
-- sections in the order shown, e.g. { "fields", "filters", "group" }; one left out is hidden, and :w then keeps
-- the filters or group that field actions and commands set
sections = { "sort", "page", "filters", "group", "limit", "fields" },
},
facets = { top_values = 10 },
-- size and overlap: source lines (JSONL) or array elements
paging = { size = 100000, overlap = 500, filter_scope = "all" },
progress = "auto", -- "auto" (progress messages on Neovim 0.12+), "notify" (always vim.notify) or "off"
keymaps = {
toggle_entry = "<CR>",
toggle_mode = "E",
raw = "gf",
reverse = "R",
clear = "X",
next_entry = "]]",
prev_entry = "[[",
next_error = "]e",
prev_error = "[e",
next_page = "]p",
prev_page = "[p",
next_match_page = "]m",
prev_match_page = "[m",
toggle_scope = "A",
focus_sidebar = "s",
toggle_sidebar = "S",
close = "q",
add_filter = "<CR>",
group_by = "g",
ignore_field = "s",
help = "?",
},
})See docs/options.md for every option.
Each field of a compact line has a style, set globally with compact.style or per field with
compact.fields[key].style (key is a field name or a role: time, level, message, status):
plain:key=value, the key colored per field. Example:method=GET.inverted: the key as a colored block. Example:method =GET.pill: likeinverted, with rounded caps around the key. Example:(method)=GET.
Fields in compact.style_values (by default level and status) are styled on the value instead (500, no key);
remove one to give it a styled key. level is inverted by default, colored by its level; a styled status value takes
its class color (JLogStatus2xx ... JLogStatus5xx); other fields take their key's color. time and message stay
plain unless styled through compact.fields.
compact.order lists top-level keys to show first. compact.fields[key].format(ctx) replaces a field's text: ctx
has value, key and entry, and it returns the text and optionally a highlight group. It runs on every drawn
line; if it errors, the default text is used and jlog warns once per field.
compact = {
order = { "method", "path", "status" },
fields = {
method = { style = "pill" },
duration_ms = {
format = function(ctx)
return ctx.value .. "ms", (tonumber(ctx.value) or 0) > 500 and "DiagnosticError" or nil
end,
},
},
}Pill caps are inline virtual text (never yanked or searched) and need a Nerd Font; pill = { left = "", right = "" }
gives square ends.
The log view shows its counts and filters in the winbar. A statusline plugin that draws winbars, such as lualine with
a winbar section, replaces it; exclude jlog's filetypes jlog and jlog_sidebar:
require("lualine").setup({
options = { disabled_filetypes = { winbar = { "jlog", "jlog_sidebar" } } },
})| Command | Action |
|---|---|
:JLog |
Open a workspace for the current buffer (no-op if one is already open in this tab). |
:JLog {path} |
Open a log file. |
:JLog filter {clause} |
Add a filter clause (see below). |
:JLog filter |
Clear all filter clauses. |
:JLog group {field} |
Group entries by a field. |
:JLog group |
Clear grouping. |
:JLog page {n} |
Go to page n of a paged log. |
:JLog scope all|page |
Show the filter matches of every page in one view, or go back to a page. |
:JLog raw |
Open the source in a new tab. |
:JLog close |
Close the workspace. |
Buffer-local, configurable under keymaps; set any to false to disable it.
| Key | Where | Action |
|---|---|---|
<CR> |
log view | Expand/collapse the entry under the cursor, keeping its compact line on top |
E |
log view | Toggle the whole view between compact and expanded |
gf |
log view | Show the entry's raw source text in a float (press again in the float to jump to the source line, JSONL only) |
R |
log view, sidebar | Reverse order |
X |
log view, sidebar | Clear filters, group and limits |
]] / [[ |
log view | Next / previous entry |
]e / [e |
log view | Next / previous ERROR-level entry |
]p / [p |
log view | Next / previous page of a paged log |
]m / [m |
log view | Next / previous page with filter matches |
A |
log view | Filter matches of every page in one view; again to go back to a page |
s |
log view | Focus the sidebar |
S |
log view, sidebar | Toggle the sidebar |
q |
log view, sidebar | Close the workspace (closes the float in the raw popup) |
<CR> |
sidebar | On a field value, add it as a filter line (OR after the field's other values, else AND); again to remove it |
g |
sidebar | On a field, group by it |
s |
sidebar | On a field, hide it from compact lines, or show it again |
? |
sidebar | Open a guide to these keys (? help on the sidebar's first line) |
Each :JLog filter call or sidebar FILTERS line is one condition. A line starting with OR is an alternative to
the line above; any other line must also match.
service=user-api
AND request_id=req-00000001
OR request_id=req-00000002
This reads as service=user-api AND (request_id=req-00000001 OR request_id=req-00000002).
| Syntax | Meaning |
|---|---|
field=value, field!=value |
Equal, not equal (status=500) |
field>n, >=, <, <= |
Number or time comparison (status>=500, time>=2026-10-22T10:00) |
field~regex |
Vim regex on the field's value |
value |
Vim regex on the whole entry |
-term |
Negate a term |
a b, a AND b |
Both match |
a OR b |
Either matches; AND binds tighter |
"quoted value" |
For spaces or the words AND/OR: msg="request completed" |
- Fields are dotted paths (
req.headers.host).time,levelandmsgalso match theirfieldsaliases (e.g.message,severity);levelignores case. - A missing field never matches, so a negated term matches entries without it.
- A time without a zone is local (UTC with
view.time_utc); a date alone is midnight. - While grouped, a group shows whole if any entry in it matches, within the entries loaded (a page, or the cross-page matches); entries without the group field show only if they match.
Every color jlog draws is a highlight group defined with default = true, so vim.api.nvim_set_hl or :hi overrides
it. See docs/highlights.md for every group and its default.
On 10k to 500k-line JSONL files, jlog's load is compared with jq and vim.json.decode, and opening, searching,
filtering and grouping are timed in a workspace; see bench/results.md. make bench regenerates it
(jq is needed for its column).
Tests use plenary.nvim and run in headless Neovim. tests/minimal_init.lua
looks for plenary under ~/.local/share/nvim/lazy/plenary.nvim.
make test # every test file
make test-file FILE=tests/config.test.lua # one fileThe performance checks (first screen, tick length, filter and group time, memory on 10k to 500k lines) are skipped
unless JLOG_PERF is set; run them on a quiet machine, since they assert wall-clock budgets:
JLOG_PERF=1 make test-file FILE=tests/perf.test.lua