@zintrust/trace 0.4.75 → 0.4.77

package/README.md

@@ -9,7 +9,7 @@ Works with both `zin s` (Node.js) and `zin s --wg` (Cloudflare Workers).
 ## Installation
 
 ```bash
-yarn add @zintrust/trace
+npm install @zintrust/trace
 ```
 
 Run the provided migrations to create the three required tables (`zin_trace_entries`, `zin_trace_entries_tags`, `zin_trace_monitoring`):
@@ -63,7 +63,44 @@ Why this is the preferred path:
 - The core runtime can then lazy-load the trace only after databases and the kernel are ready.
 - The plugin activates trace runtime logic only; the dashboard route stays inactive until you register it yourself.
 
-With the stock ZinTrust bootstrap, `TRACE_ENABLED=true` plus the plugin import above activates the watchers and storage integration. Dashboard UI/routes are a separate route-level opt-in.
+With the stock ZinTrust bootstrap, `TRACE_ENABLED=true` plus the plugin import above activates the watchers and storage integration. Dashboard UI/routes are still a separate opt-in unless you also set `TRACE_AUTO_MOUNT=true`.
+
+### Optional: configure filters in `config/trace.ts`
+
+If you prefer project-owned trace configuration over env-only setup, put the filter rules directly in `config/trace.ts`.
+
+```ts
+// config/trace.ts
+import { Env } from '@config/env';
+import type { TraceConfigOverrides } from '@zintrust/trace';
+
+export default {
+  enabled: Env.getBool('TRACE_ENABLED', false),
+  connection: Env.get('TRACE_DB_CONNECTION', '') || undefined,
+  pruneAfterHours: Env.getInt('TRACE_PRUNE_HOURS', 24),
+  slowQueryThreshold: Env.getInt('TRACE_SLOW_QUERY_MS', 100),
+  logMinLevel: Env.get('TRACE_LOG_LEVEL', 'info') as TraceConfigOverrides['logMinLevel'],
+  watchers: {
+    request: {
+      get: { exclude: ['report'] },
+      post: { include: ['auth'] },
+      patch: { include: ['profile'] },
+      delete: { exclude: ['internal'] },
+    },
+    log: { exclude: ['healthcheck'] },
+    exception: { include: ['trace'] },
+    cache: { include: ['session:'] },
+  },
+  redaction: {
+    keys: ['password', 'token', 'secret'],
+    headers: ['authorization', 'cookie'],
+    body: ['password', 'token', 'secret'],
+    query: [],
+  },
+} satisfies TraceConfigOverrides;
+```
+
+All include/exclude matching is contains-based, so a term like `report` matches `/reports/daily`, `monthly-report`, or any other trace content containing that fragment.
 
 ### 3. Mount the dashboard
 
@@ -98,6 +135,19 @@ registerTraceRoutes(router, TraceStorage.resolveStorage(db), {
 
 If you need a manual late bootstrap instead of plugin-driven activation, you can still import `@zintrust/trace/register` yourself, but that is the advanced path rather than the default project setup.
 
+### 4. Optional stock-bootstrap auto-mount
+
+If you want core to expose the trace dashboard without editing your route file, opt in explicitly:
+
+```env
+TRACE_ENABLED=true
+TRACE_AUTO_MOUNT=true
+TRACE_BASE_PATH=/trace
+TRACE_MIDDLEWARE=auth,admin
+```
+
+When `TRACE_AUTO_MOUNT=true`, ZinTrust calls `registerTraceDashboard(...)` during bootstrap using `TRACE_BASE_PATH` and the optional comma-separated `TRACE_MIDDLEWARE` list. Keep this off if you want route ownership to stay fully in application code.
+
 ## CLI commands
 
 When the optional package is installed, ZinTrust auto-registers these commands:
@@ -111,6 +161,14 @@ zin trace:clear
 
 `zin trace:status` reports the active connection, retention window, current entry counts, and the expected dashboard URL derived from your current env and route choices.
 
+### Monitoring tags
+
+The Monitoring page lets you save a short list of tags that you filter by often.
+
+- Add tags like `auth`, `checkout`, `queue:emails`, or `nightly-sync` once, then click them later to jump straight to matching entries.
+- Monitoring tags are just saved dashboard shortcuts. Removing a monitoring tag does not delete trace entries or strip tags from stored data.
+- Use short, exact tag names. The dashboard filters entries by the exact tag value you click.
+
 ---
 
 ## Watchers
@@ -164,6 +222,16 @@ const config = TraceConfig.merge({
     // disable specific watchers
     redis: false,
     view: false,
+    request: {
+      get: { exclude: ['report'] },
+      post: { include: ['auth'] },
+    },
+    log: {
+      exclude: ['healthcheck'],
+    },
+    exception: {
+      include: ['trace'],
+    },
   },
   redaction: {
     body: ['password', 'secret', 'token'],
@@ -184,18 +252,36 @@ ExceptionWatcher.register({ storage, config, db });
 
 `TraceConfig.merge(overrides?)` accepts the following options:
 
-| Option               | Type                                                | Default                            | Description                                                          |
-| -------------------- | --------------------------------------------------- | ---------------------------------- | -------------------------------------------------------------------- |
-| `enabled`            | `boolean`                                           | `false`                            | Master switch — no watchers activate when `false`                    |
-| `connection`         | `string \| undefined`                               | `undefined`                        | Named DB connection for storing entries; uses `'default'` if omitted |
-| `pruneAfterHours`    | `number`                                            | `24`                               | Entries older than this are pruned                                   |
-| `slowQueryThreshold` | `number`                                            | `100`                              | Queries taking longer (ms) are flagged as slow                       |
-| `logMinLevel`        | `'debug' \| 'info' \| 'warn' \| 'error' \| 'fatal'` | `'info'`                           | Minimum log severity captured                                        |
-| `ignoreRoutes`       | `string[]`                                          | `['/trace', '/health', '/ping']`   | Routes excluded from HTTP watcher                                    |
-| `watchers`           | `Record<string, boolean>`                           | `{}`                               | Per-watcher enable/disable flags (`false` = disabled)                |
-| `redaction.headers`  | `string[]`                                          | `['authorization', 'cookie', ...]` | Request header names to redact                                       |
-| `redaction.body`     | `string[]`                                          | `['password', 'token', ...]`       | Request body keys to redact                                          |
-| `redaction.query`    | `string[]`                                          | `[]`                               | Query-string keys to redact                                          |
+| Option               | Type                                                | Default                            | Description                                                                  |
+| -------------------- | --------------------------------------------------- | ---------------------------------- | ---------------------------------------------------------------------------- |
+| `enabled`            | `boolean`                                           | `false`                            | Master switch — no watchers activate when `false`                            |
+| `connection`         | `string \| undefined`                               | `undefined`                        | Named DB connection for storing entries; uses `'default'` if omitted         |
+| `pruneAfterHours`    | `number`                                            | `24`                               | Entries older than this are pruned                                           |
+| `slowQueryThreshold` | `number`                                            | `100`                              | Queries taking longer (ms) are flagged as slow                               |
+| `logMinLevel`        | `'debug' \| 'info' \| 'warn' \| 'error' \| 'fatal'` | `'info'`                           | Minimum log severity captured                                                |
+| `ignoreRoutes`       | `string[]`                                          | `['/trace', '/health', '/ping']`   | Routes excluded from HTTP watcher                                            |
+| `watchers`           | `Record<string, boolean \| { include?, exclude? }>` | `{}`                               | Per-watcher enable/disable flags plus contains-based include/exclude filters |
+| `redaction.keys`     | `string[]`                                          | common auth/card/session keys      | Extra sensitive keys redacted recursively before trace persistence           |
+| `redaction.headers`  | `string[]`                                          | `['authorization', 'cookie', ...]` | Request header names to redact                                               |
+| `redaction.body`     | `string[]`                                          | `['password', 'token', ...]`       | Request body keys to redact                                                  |
+| `redaction.query`    | `string[]`                                          | `[]`                               | Query-string keys to redact                                                  |
+
+Request watcher filters can also be scoped per method. Matching is contains-based against the stored trace content, so values like `report`, `auth`, or `trace` match any request or entry whose content includes those fragments.
+
+```ts
+const config = TraceConfig.merge({
+  watchers: {
+    request: {
+      get: { exclude: ['report'] },
+      post: { include: ['auth'] },
+      patch: { include: ['profile'] },
+    },
+    log: { exclude: ['healthcheck'] },
+    exception: { include: ['trace'] },
+    cache: { include: ['session:'] },
+  },
+});
+```
 
 ---
 
@@ -275,7 +361,7 @@ import {
 ## Security considerations
 
 - **Always** protect the dashboard with middleware (e.g. `middleware: ['admin']`). `@zintrust/trace/ui` exports `registerTraceDashboard(...)` and `registerTraceRoutes(...)`, and neither applies any authentication by default.
-- Sensitive fields in request headers and body are redacted using the `redaction` config before being stored. Review and extend the default redaction lists to match your application's data model.
+- Sensitive fields are redacted using the `redaction` config before they are stored. Review and extend the default `redaction.keys`, `redaction.headers`, `redaction.body`, and `redaction.query` lists to match your application's data model.
 - Use a **dedicated database connection** (`TRACE_DB_CONNECTION`) in production so trace writes cannot impact your primary DB connection pool.
 - Keep `TRACE_ENABLED=false` (or unset) in production unless actively investigating an issue.