# Package logging via `.env` (logs-gateway)

**Authoritative contract:** [logs-gateway `docs/package-usage.md`](https://github.com/nx-intelligence/logs-gateway/blob/main/docs/package-usage.md) (published on npm in **`logs-gateway`** **≥ 3.6**). This file summarizes the split Activix cares about and points integrators at the gateway.

- **Per package:** **`<packagePrefix>_LOGS_LEVEL`** (canonical threshold for that library’s `createLogger` `envPrefix`).
- **Cross-cutting:** console, file, format, unified sink — host/app configuration; see **logs-gateway** README (not duplicated per library prefix in this doc).

**Package prefix** is the short token passed as **`envPrefix`** to **`createLogger`** (e.g. Activix uses **`ACTIVIX`**).

---

## Per-package level (`<packagePrefix>_LOGS_LEVEL`)

| Topic | Detail |
|--------|--------|
| **Canonical var** | **`<packagePrefix>_LOGS_LEVEL`** |
| **Legacy** | **`<packagePrefix>_LOG_LEVEL`** applies **only if** `*_LOGS_LEVEL` is **not** set in the environment |
| **Default** | If **both** are **unset**, effective level is **`warn`** (warn + error only)—**not** `info` and **not** silent |
| **Silence** | **`off`**, **`none`**, or **`silent`** |
| **Other values** | `error` \| `warn` \| `info` \| `debug` \| `verbose` (case-insensitive) |

Each package documents its **`packagePrefix`** and the exact `.env` key (e.g. Activix: **`ACTIVIX_LOGS_LEVEL`**).

---

## Cross-cutting (once per app / process)

Where logs go and how they are formatted are **not** repeated per package prefix in this model. Configure them per **logs-gateway** and host-app docs.

When **`<packagePrefix>_LOGS_LEVEL`** silences a package, that package does not emit diagnostics regardless of cross-cutting settings.

---

## Activix

- **Enable key:** **`ENABLE_ACTIVIX_LOGXER=true`** (errors-only by default when omitted; console diagnostics, not logxer)
- **Prefix:** **`ACTIVIX`**
- **Key:** **`ACTIVIX_LOGS_LEVEL`**
- **Errors only:** omit `ENABLE_ACTIVIX_LOGXER`, set it to any value other than `true`, or set `ACTIVIX_LOGS_LEVEL=error` when logxer is enabled
- **Helpers (optional, from `logs-gateway`):** `resolvePackageLogsLevel`, `parsePackageLogsLevelString`, `packageLogsLevelEnvKey`, `legacyPackageLogLevelEnvKey`

---

## Other dependencies

Concrete keys for **xronox-store**, **xronox**, and other stack packages belong in their own READMEs; this doc only describes the **logs-gateway** package-level contract.