loglens

Name: loglens
Author: CloudCorpRecords

本地服务

github.com/CloudCorpRecords数据与分析01 周前更新

代码仓库

关于 loglens

loglens 是面向 Homelab 运维者的本地日志排查命令行工具和 stdio MCP 服务，可检查 JSONL 日志，全程不访问网络。

主要功能

01查看日志存储状态
02查看最新记录或错误
03按词语和条件搜索
04按小时或天统计日志量
05查看时间点附近的记录
06提供命令行和 stdio MCP 服务

适用场景

01检查 Homelab 最近活动
02查找错误或匹配词语的日志
03查看日志量随时间的变化
04检查故障时段附近的记录

MCP 相关

提供 stdio MCP 服务，通过单一分发工具 `cortex` 执行状态、尾部、错误、搜索、时间线、上下文和帮助操作。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "cloudcorprecords-loglens": {
      "command": "npx",
      "args": [
        "-y",
        "@reneturcios/loglens"
      ]
    }
  }
}

启动命令npx -y @reneturcios/loglens

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@reneturcios/loglens0.1.0stdio

ocighcr.io/cloudcorprecords/loglens:0.1.0stdio

工具

收录的工具列表 · 更新于 1 周前

参数	类型	必填	说明
level	string	否	用于筛选的日志级别。
limit	integer	否	要返回的记录数上限。
query	string	否	与日志消息和来源匹配的搜索文本。
since	string	否	时间范围的起始时间，采用 ISO-8601 时间戳格式。
until	string	否	时间范围的结束时间，采用 ISO-8601 时间戳格式。
action	enum	是	要执行的操作：status、tail、errors、search、timeline、context 或 help。status \| tail \| errors \| search \| timeline \| context \| help
bucket	enum	否	时间线分桶大小：hour 或 day。hour \| day
source	string	否	用于筛选的日志来源名称。
timestamp	string	否	用于确定上下文结果中心的时间戳或记录索引。
window_minutes	integer	否	上下文结果中时间戳前后的时间窗口（分钟）。

详细介绍

loglens

loglens 用于调查本地文件中的 homelab 日志：存储中有什么内容、最近收到了什么、哪些内容报错、哪些内容提到了某个词、日志量如何随时间分布，以及某个时刻前后发生了什么。一个二进制文件同时提供命令行界面和 stdio MCP 服务，后者通过单个按操作分派的工具 cortex 提供功能。

这是一个带标签的核心子集。它所模仿的工具会分派 60 个目录操作；loglens 实现了其中 7 个——status、tail、errors、search、timeline、context 和 help——并省略了另外 53 个操作（舰队与拓扑视图、AI 会话分析、关联与异常分析、错误确认、通知和管理）。运行时，help 操作会列出已实现的子集和省略的操作。

日志文件

记录存储在 JSONL 文件中：每行一个 JSON 对象，包含 ts（ISO-8601 时间戳）、level、source 和 message：

{"ts":"2026-10-26T09:15:00.000Z","level":"info","source":"docker/web","message":"container started"}
{"ts":"2026-10-26T09:16:12.000Z","level":"error","source":"syslog","message":"disk almost full"}

路径依次取自 CLI 中的 --file、LOGLENS_LOG_FILE 环境变量，最后使用 ./loglens.jsonl。格式错误的行（JSON 无效、缺少字段、时间戳无法解析）会被跳过并计数，不会导致程序退出。对于数据操作，文件缺失会报错；status 则会报告存储状态，并将 exists 设为 false；help 完全不需要存储。所有逻辑均在本地运行且具有确定性——绝不会访问网络。

安装

npx @reneturcios/loglens status

或者运行容器镜像：

docker run -i ghcr.io/cloudcorprecords/loglens

容器默认启动 MCP 服务（见下文）。传入 CLI 参数即可将其用作 CLI。挂载日志文件，并将 LOGLENS_LOG_FILE 设为文件在容器中的路径。

CLI

export LOGLENS_LOG_FILE=/var/log/homelab.jsonl

loglens status
loglens tail --limit 5 --source docker/web
loglens errors --limit 10
loglens search "disk" --since 2026-10-26T00:00:00.000Z
loglens timeline --bucket day
loglens context 2026-10-26T09:16:12.000Z --window-minutes 5
loglens context 12 --limit 3
loglens help

loglens --version

命令会输出 JSON 结果。tail、errors 和 search 按时间从近到远返回记录；context 则按文件顺序返回。context 接受时间戳（返回与其相差不超过 --window-minutes 的记录，或返回最接近记录周围的 --limit 条记录）或单独的记录索引（返回该位置两侧的 --limit 条记录）。退出代码：成功时为 0，操作失败时为 1（包括日志文件缺失），用法错误时为 2。

MCP 服务

一个二进制文件同时提供两种用法。mcp 子命令会启动 stdio MCP 服务：

npx -y @reneturcios/loglens mcp

MCP 客户端配置：

{
  "mcpServers": {
    "loglens": {
      "command": "npx",
      "args": ["-y", "@reneturcios/loglens", "mcp"],
      "env": { "LOGLENS_LOG_FILE": "/absolute/path/to/logs.jsonl" }
    }
  }
}

工具

工具	输入	返回内容
`cortex`	`action`（必需，取值为 `status`、`tail`、`errors`、`search`、`timeline`、`context`、`help` 之一），以及可选的 `query`、`source`、`level`、`limit`、`since`、`until`、`bucket`（`hour` 或 `day`）、`timestamp`、`window_minutes`	根据操作返回存储摘要、最新的匹配记录、按小时或按天统计的日志量、某个时刻前后的记录，或子集帮助文本。

一个实用的首次调用是 {"action":"status"}，然后使用 tail、errors、search、timeline 或 context 缩小范围。

开发

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, real temp JSONL files, no network
npm run dev     # run the CLI from source via tsx