Skip to content
kcaymePublic

About

Search, filter, and transform your logs into human-readable format with jlog.nvim

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

jlog.nvim

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.

jlog.nvim demo

Features

  • 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.

Requirements

  • Neovim >= 0.10 (:checkhealth jlog confirms it)

Installation

With lazy.nvim:

{ "kcayme/jlog.nvim", opts = {} }

setup() is optional; without it jlog runs with the defaults below.

Quick start

  1. 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.
  2. Press <CR> on an entry to expand it, E to expand them all.
  3. In the sidebar, type status>=500 under FILTERS, or request_id under GROUP BY, then :w.
  4. Or press <CR> on values in FIELDS to filter by them (one line each, OR between values of a field), g on a field to group by it.
  5. ? in the sidebar lists every key; q closes the workspace.

Configuration

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.

Compact line formatting

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: like inverted, 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.

Statusline plugins

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" } } },
})

Usage

Commands

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.

Keymaps

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)

Filter syntax

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, level and msg also match their fields aliases (e.g. message, severity); level ignores 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.

Highlights

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.

Benchmark

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).

Running tests

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 file

The 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

About

Search, filter, and transform your logs into human-readable format with jlog.nvim

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Contributors

Languages