@hasna/logs

中文文档
0.5.1发布于 2026/10/16Apache-2.0TypeScriptES Module近 30 天下载 1.2万

Log aggregation + browser script + headless page scanner + performance monitoring for AI agents

原始使用文档
文档目录10 节
  1. Install
  2. Credentials and authority
  3. Environment
  4. CLI Usage
  5. MCP Server
  6. HTTP mode
  7. REST API
  8. PostgreSQL backend
  9. Data Directory
  10. License

@hasna/logs

Log aggregation + browser script + headless page scanner + performance monitoring for AI agents

npm License

Install

npm install -g @hasna/logs

Credentials and authority

Every hosted surface — the CLI, the MCP server and the @hasna/logs/api SDK — resolves its API key and URL through the shared @hasna/contracts client resolver (hasna/apps#1720), fresh on every request:

TierCredentialAuthority
1. explicit argument--api-key / credentials.apiKeybaseUrl option
2. env pointersHASNA_LOGS_API_KEY_OVERRIDE, HASNA_PROFILE, HASNA_LOGS_API_KEY_REF—
3. macOS Keychainhasna.credentials.logs.api-key (account HASNA_STATION, else hostname -s, else USER)hasna.credentials.logs.api-url
4. disk (0400/0600)~/.hasna/logs/config/credentials (HASNA_HOME / HASNA_CONFIG_HOME move the root; XDG is never consulted)same file
5. envHASNA_LOGS_API_KEYHASNA_LOGS_API_URL

With no URL configured the authority defaults to the fleet gateway https://api.hasna.com/logs (the client appends /v1) — a key alone is a complete configuration. The legacy unprefixed LOGS_API_URL / LOGS_API_KEY names are accepted only as the resolver's silent alias fallback for one release and never outrank the canonical HASNA_LOGS_* pair. Retired inputs (~/.hasna/fleet-env, the legacy ~/.hasna cloud / config dotdirs, $XDG_CONFIG_HOME, ~/.logs/config.json) are never read, and no *_MODE / *_STORAGE_MODE variable selects anything.

Hosted mode fails loud. A data-plane command with no resolvable credential exits non-zero with one actionable line — no SQLite fallback, no local-fallback event. A deliberate tier that cannot be honoured (HASNA_PROFILE naming a profile with no key, or a HASNA_LOGS_API_KEY_REF vault pointer this process cannot complete) is refused the same way, never resolved around — and logs-mcp refuses it at startup: before initialize is answered on stdio, and before the Streamable-HTTP listener (--http) binds its port. The on-box SQLite store (~/.hasna/logs/logs.db) is reachable only through the explicit opt-in:

export HASNA_LOGS_LOCAL=1   # alias: LOGS_LOCAL=1

…and a run that lands there prints one local line on stderr — it is never silent. Inspect which transport and source a run would resolve:

logs transport          # e.g. transport: http, source: default, api_key_tier: keychain
logs transport --json

The serve (logs-serve) follows the same rule: HASNA_LOGS_DATABASE_URL selects the PostgreSQL-backed fleet API (validated fail-closed by the vendored storage kit), HASNA_LOGS_LOCAL=1 selects the on-box SQLite collector (with the local line on stderr), and neither configured is a non-zero startup with no SQLite.

Environment

VariableSurfacePurpose
HASNA_LOGS_API_KEYCLI / MCP / @hasna/logs/apiFleet API key (env tier of the credential chain)
HASNA_LOGS_API_URLCLI / MCP / @hasna/logs/apiService authority; defaults to https://api.hasna.com/logs
HASNA_LOGS_API_KEY_OVERRIDE / HASNA_LOGS_API_KEY_REF / HASNA_PROFILECLI / MCP / SDKDeliberate credential pointers (tier 2)
HASNA_STATIONCLI / MCP / SDKmacOS Keychain account selector
HASNA_HOME / HASNA_CONFIG_HOMECLI / MCP / SDKMove the disk credential/config root
HASNA_LOGS_LOCAL (LOGS_LOCAL)CLI / MCP / logs-serveExplicit opt-in for the on-box SQLite store/collector
HASNA_LOGS_DATABASE_URL (LOGS_DATABASE_URL)logs-serve, logs db migrate/statusPostgreSQL connection URL for the hosted serve
HASNA_LOGS_DATA_DIR / HASNA_LOGS_DB_PATHlocal storeOn-box SQLite location (default $HASNA_HOME/logs/logs.db, i.e. ~/.hasna/logs/logs.db; HASNA_HOME moves the data with the config)
HASNA_LOGS_API_TOKEN (LOGS_API_TOKEN)logs-serveAPI token required for /api/* requests
HASNA_LOGS_API_SIGNING_KEYlogs-serveSigning secret for hosted /v1 API keys
HASNA_LOGS_SECRET_KEY (LOGS_SECRET_KEY)logs-serveEncrypt page-scanner credentials at rest
HASNA_LOGS_S3_BUCKETlogs-serveS3 artifact upload bucket
LOGS_PORT / PORTlogs-serveListen port (default 3460)

CLI Usage

logs --help
  • logs list
  • logs tail
  • logs summary
  • logs push
  • logs events
  • logs test-reports
  • logs scan
  • logs diagnose

logs list defaults to a bounded compact identity preview: 25 rows, message and service previews, reversible JSON-string-escaped log IDs for logs get <id>, and a 32 KiB output ceiling. When more rows remain, the footer reports a resumable next_offset; pass it back with --offset. Use --limit and --max-bytes to tune the compact page, --format table for the legacy terminal columns, or --format json for explicit full records. Multi-level hosted filters scan bounded server pages so --offset always counts matching rows and the continuation footer stays truthful even when nonmatching rows precede the next match.

Examples:

logs list
logs list --text timeout --limit 25
logs list --offset 25 --max-bytes 32768
logs get <id>
logs list --format json --limit 25

MCP Server

logs-mcp

Includes log search, raw event search/watch/export, projected test-report search/get, storage sync, scan, issue, and performance tools.

HTTP mode

Run a shared Streamable HTTP MCP server (127.0.0.1 only):

logs-mcp --http               # default port 8864
logs-mcp --http --port 8864
MCP_HTTP=1 logs-mcp
  • Health: GET http://127.0.0.1:8864/health
  • MCP: POST http://127.0.0.1:8864/mcp

Stdio remains the default when no --http flag is passed.

REST API

HASNA_LOGS_DATABASE_URL=postgres://… logs-serve     # PostgreSQL-backed fleet API
HASNA_LOGS_LOCAL=1 logs-serve --local-open          # on-box SQLite collector (says "local" on stderr)

By default the API is locked unless an API token is configured or trusted loopback mode is explicitly enabled:

HASNA_LOGS_API_TOKEN="$(openssl rand -hex 32)" logs-serve
# or, for local-only development:
HASNA_LOGS_LOCAL=1 logs-serve --local-open

Use Authorization: Bearer <token> or X-Logs-Token: <token> for /api/* requests. Browser ingest tokens remain scoped write-only tokens for browser capture and do not grant general API access.

Page scanner credentials are encrypted at rest with a generated local page-auth.key under the logs data directory. For deployments that need a managed secret, set HASNA_LOGS_SECRET_KEY or LOGS_SECRET_KEY:

export HASNA_LOGS_SECRET_KEY="$(openssl rand -hex 32)"

PostgreSQL backend

The hosted serve reads and writes PostgreSQL directly (including AWS RDS). Configure HASNA_LOGS_DATABASE_URL (or the LOGS_DATABASE_URL alias), then apply the schema and inspect it:

logs db migrate            # apply cloud migrations (schema + api_keys)
logs db status

The MCP server exposes the same event/log data plane over the HTTP transport when a credential resolves — there is no DSN on any client and no storage sync in the data plane.

LOGS_DATABASE_URL is accepted as the non-Hasna fallback database URL for one release.

Data Directory

Local-mode data (logs.db, the raw event segments and the persistent agent-registry.db of a local logs-mcp) is stored in ~/.hasna/logs/ — $HASNA_HOME/logs/ when HASNA_HOME replaces the ~/.hasna root, or HASNA_LOGS_DATA_DIR when set. It is only ever created under the explicit HASNA_LOGS_LOCAL=1 opt-in: a hosted logs / logs-mcp / @hasna/logs/sdk process opens no SQLite file (a hosted logs-mcp keeps its agent registry in memory, per process, and its tool descriptions say so).

License

Apache-2.0 -- see LICENSE

版本与发布记录

@hasna/logs 共发布 48 个版本,首次发布于 2026/03/17;过去 12 个月发布了 48 个版本。

版本发布日期距今
0.5.1latest2026/10/161 个月前
0.5.02026/09/072 个月前
0.4.82026/08/212 个月前
0.4.52026/07/243 个月前
0.4.42026/07/094 个月前
0.4.32026/07/084 个月前

关于 @hasna/logs 的常见问题

@hasna/logs 是什么?

Log aggregation + browser script + headless page scanner + performance monitoring for AI agents

如何安装 @hasna/logs?

在项目目录运行 npm install @hasna/logs,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 logs、logs-mcp、logs-serve,可以用 npx logs 直接运行。

@hasna/logs 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@hasna/logs 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@hasna/logs 可以商用吗?

@hasna/logs 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@hasna/logs 的下载量有多少?

根据 npm 官方下载统计,@hasna/logs 在 2026/10/18 – 2026/11/16 这 30 天内被下载 12,037 次,日均约 401 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@hasna/logs 还在维护吗?

最新版本 0.5.1 发布于 2026/10/16(1 个月前);至今共发布 48 个版本,其中过去 12 个月发布了 48 个;首次发布于 2026/03/17。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。