# logxer — complete library (all audiences)

_Generated whole-library download. See `agent-manifest.json` → `library` for discovery._

## Table of contents

- **Overview** (`00-overview`, developers)
- **Env and package logging** (`01-env-package-logging`, developers)
- **MongoDB transport** (`02-mongodb-transport`, developers)
- **Runtime observability** (`03-runtime-observability`, developers)
- **Package log levels stack** (`04-package-log-levels`, developers)
- **CLI** (`05-cli`, developers)
- **Agent logging** (`06-agent-logging`, developers)
- **API and web UI** (`07-api-and-web`, developers)

---

# Overview — developers

# Overview — Developers

**Audience:** Engineers evaluating or adopting `@x12i/logxer`.  
**Related:** [Env logging](../01-env-package-logging/developers/BOOK.md) · [API and web](../07-api-and-web/developers/BOOK.md)

---

## 1. What it is

Logxer is a standardized **logging gateway** for Node.js:

- Console and file outputs (plain Node `fs` for files)
- Optional **MongoDB** sink and fetch helpers
- PII/credentials sanitization (opt-in)
- Correlation trails, shadow logging, diagnostics, and story/scope helpers
- Published agent instruction docs

This monorepo also ships a private **Fastify API** and **React web UI** for querying Mongo-backed logs. Only `@x12i/logxer` (and `@x12i/logxer-docs`) are published to npm.

As of **5.2.0**, unused transport deps (pino/winston/consola) were removed; `@x12i/helpers` is an **optional peer** for a future GCS sink (disabled by default). Cloud SDKs live in `@x12i/helpers@3` as optional peers — installing Logxer alone does not pull Firebase/AWS.

---

## 2. Install

```bash
npm install @x12i/logxer
```

Requires Node.js 18+.

For assembled docs packs (agents / chapter markdown):

```bash
npm i -D @x12i/logxer-docs
```

---

## 3. Minimal example

```ts
import { createLogxer } from '@x12i/logxer';

const log = createLogxer(
  { packageName: 'MY_APP', envPrefix: 'MY_APP' },
  { logToConsole: true, logLevel: 'info' }
);

log.info('service started', { jobId: 'job-1' });
log.warn('degraded path', { reason: 'retry' });
```

Env-first alternative (no second arg): set `MY_APP_LOG_TO_CONSOLE=true` and `MY_APP_LOGS_LEVEL=info`.

---

## 4. Where to go next

1. [Env and package logging](../01-env-package-logging/developers/BOOK.md) — ERC / `LOGS_LEVEL`
2. [MongoDB transport](../02-mongodb-transport/developers/BOOK.md) — persistence
3. [API and web UI](../07-api-and-web/developers/BOOK.md) — ops stack
4. [Agent logging](../06-agent-logging/developers/BOOK.md) — agent contracts

---

# Env and package logging — developers

# Env and package logging — Developers

**Audience:** Package authors and app hosts.  
**Canonical detail:** also in `@x12i/logxer` → `docs/package-usage.md`.

---

## 1. Package-level contract

Each package owns **one** env prefix (e.g. `MY_LIB`) and configures verbosity with:

```dotenv
MY_LIB_LOGS_LEVEL=warn
```

Allowed values: `verbose`, `debug`, `info`, `warn`, `error`, `off` (aliases `none`/`silent`).

**Default** when neither `_LOGS_LEVEL` nor legacy `_LOG_LEVEL` is set: **`warn`**.

Cross-cutting knobs (console, file, format) are **host-level**, not repeated per package.

---

## 2. Create logger

```ts
import { createLogxer } from '@x12i/logxer';

export const logger = createLogxer({
  packageName: 'MyLib',
  envPrefix: 'MY_LIB'
});
```

Helpers: `resolvePackageLogsLevel`, `parsePackageLogsLevelString`, `packageLogsLevelEnvKey`. Bundler hosts that only need key naming can import `@x12i/logxer/package-levels`.

---

## 3. Host cross-cutting

Set once for the process (replace `{PREFIX}` with the host app prefix):

```dotenv
MY_APP_LOG_TO_CONSOLE=true
MY_APP_LOG_TO_FILE=false
MY_APP_LOG_FORMAT=json
```

Per-dependency verbosity stays on each package’s `*_LOGS_LEVEL`.

---

# MongoDB transport — developers

# MongoDB transport — Developers

**Audience:** Operators enabling persistence.  
**Detail:** `@x12i/logxer` → `docs/mongodb-transport.md`.

---

## 1. Env ladder

URI resolution (first non-empty wins):

1. `logxer_mongo_uri`
2. `mongo_logs_uri`
3. `mongo_uri`
4. `MONGO_LOGXER_URI`
5. `MONGO_URI`

DB name: `logxer_mongo_db` or `MONGO_LOGXER_DB` (default **`logxer`**).  
Min level: `logxer_mongo_db_logs_level` (default **`warn`**).

---

## 2. Sink behavior

When a URI is present, Logxer creates a Mongo output and writes structured envelopes (best-effort). An init probe record helps operators confirm connectivity.

Cloud Storage GCS via `@x12i/helpers` is **not** enabled in this pipeline (`resolveStorageConfigFromEnv` returns disabled).

---

## 3. Fetch helpers

The library exports fetch helpers used by the CLI and API (`fetchLogsByJobId`, session windows, etc.). Prefer the HTTP API for UIs; use helpers from Node scripts or agents.

---

# Runtime observability — developers

# Runtime observability — Developers

**Audience:** Debug tooling authors.  
**Detail:** `docs/runtime-observability.md`, `docs/diagnostics-enhancement.md`.

---

## 1. getJobLogs

```ts
const res = await logxer.getJobLogs({
  jobId,
  graphId,
  nodeId,
  level: ['warn', 'error'],
  limit: 500
});
```

Returns **structured** envelopes from an **in-process** TTL store (not Mongo/GCS/files).

---

## 2. Diagnostics

Opt-in diagnostics attach failure classification, evidence, and causal links for UI filters (`llmRoute`, etc.).

---

## 3. Shadow logging

Per-run shadow capture (TTL, forced-verbose) is ideal for tests. Configure via `shadow` options or env (`{PREFIX}_SHADOW_*`).

---

# Package log levels stack — developers

# Package log levels stack — Developers

**Audience:** Hosts with deep dependency trees.  
**Detail:** `docs/package-log-levels-stack.md`.

---

## 1. Why stacks

When many packages each call `createLogxer`, operators need one place to set levels without editing every package.

---

## 2. Host registry

Use `configurePackageLogLevels` / stack options so the host can push levels into child packages.

---

## 3. Bulk env

`LOGXER_PACKAGE_LEVELS` supports bulk overrides. See the published stack doc for syntax and pass-through (`StackLoggingOptions`).

---

# CLI — developers

# CLI — Developers

**Audience:** Operators querying Mongo from a shell.  
**Detail:** `docs/cli.md`.

---

## 1. Install / invoke

The `logxer` binary ships with `@x12i/logxer`:

```bash
npx logxer --help
```

---

## 2. Typical queries

Query by job, task, session, or machine using the same filters as the HTTP API (`olderThan`, `level`, `limit`).

---

## 3. Diagnostics catalog

CLI can load a diagnostics catalog file for enriched failure classification when querying.

---

# Agent logging — developers

# Agent logging — Developers

**Audience:** Code agents and tool authors.  
**Detail:** `docs/agent-logging.md`, `docs/instructions-for-code-agents.md`.

---

## 1. Agent contract

Prefer structured envelopes with stable correlation keys. Never redact `jobId`, `graphId`, `taskId`, `nodeId`, `sessionId`, `correlationId` (and related defaults) when sanitization is on.

---

## 2. Correlation fields

Attach `jobId` / `sessionId` / trails so UIs and `getJobLogs` can filter. Use `DebugLogAbstract` (`STATE` | `INTENT` | `EVENT` | `TRACE` | `ANOMALY`) for semantic debug kinds.

---

## 3. Instructions entry

```ts
import { getAgentInstructions } from '@x12i/logxer/agent-instructions';
```

Or read `@x12i/logxer/instructions-for-code-agents.md`. Multi-package stacks: `docs/package-log-levels-stack.md`.

---

# API and web UI — developers

# API and web UI — Developers

**Audience:** Operators running the monorepo observability stack.

---

## 1. API setup

```bash
cp packages/logxer-api/.env.example packages/logxer-api/.env
# set logxer_mongo_uri
npm install
npm run build:lib
npm run dev -w @x12i/logxer-api
```

Default API: `http://localhost:3100`.

---

## 2. Endpoints

| Method | Route | Description |
|--------|-------|-------------|
| GET | `/health` | Liveness + Mongo config |
| GET | `/api/logs/job/:jobId` | By job |
| GET | `/api/logs/task/:taskId` | By task |
| GET | `/api/logs/machine` | By host |
| GET | `/api/logs/global` | All hosts |
| GET | `/api/logs/session/:sessionId` | Local session |
| GET | `/api/logs/job-session/:jobId` | Job session window |

Query params: `olderThan`, `level`, `limit`, `host`, `fromTimestamp`, `windowMs`.

---

## 3. Web UI

```bash
npm run dev
```

Runs API + web (`logxer-web` on Vite, typically `http://localhost:5173`). Search forms call the API client; drawers show full envelopes.