@sigx/lynx-observability 0.6.1 → 0.8.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025-2026 Andreas Ekdahl
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2025-2026 Andreas Ekdahl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,107 +1,107 @@
-# @sigx/lynx-observability
-
-Opt-in **production error capture** and **provider-agnostic log/error sinks** for sigx-lynx. Builds on the logger in [`@sigx/lynx-core`](https://sigx.dev/lynx/modules/core/overview/): uncaught errors are funneled in as `error`-level records, and a "sink" is just a `LogTransport`. No hard dependency on any vendor SDK.
-
-> Logging itself ships in the framework (`import { createLogger } from '@sigx/lynx'`). This package adds the *production* pieces — catching crashes and shipping records off-device — and is installed only when you want them.
-
-## 📚 Documentation
-
-Full guides, API reference and live examples → **[https://sigx.dev/lynx/](https://sigx.dev/lynx/)**
-
-## Install
-
-```sh
-pnpm add @sigx/lynx-observability
-```
-
-## Quick start — declarative (recommended)
-
-Declare it in `signalx.config.ts` and it auto-wires in **release** builds — no code in your app entry:
-
-```ts
-// signalx.config.ts
-export default defineLynxConfig({
-    name: 'my-app',
-    logging: {
-        level: 'warn',                     // logger level (also dev: 'debug' / release: 'warn' default)
-        namespaces: { disabled: ['http'] },// silence namespaces at startup
-        production: {
-            sink: { url: 'https://logs.example.com/ingest', headers: { 'x-api-key': KEY }, sampleRate: 0.25 },
-            captureErrors: true,           // default
-        },
-    },
-});
-```
-
-Just install the package (`pnpm add @sigx/lynx-observability`) — `@sigx/lynx-plugin` prepends the init for you in release builds. (Dev uses the console streamer; observability auto-wiring is release-only.)
-
-## Quick start — manual
-
-Or wire it yourself, `Sentry.init()`-style (call once in your app entry):
-
-```ts
-import { initObservability } from '@sigx/lynx-observability';
-
-initObservability({
-    level: 'warn',                    // optional: override the default level
-    captureErrors: true,              // default — catch uncaught errors / rejections
-    sink: {                           // optional remote sink
-        url: 'https://logs.example.com/ingest',
-        headers: { 'x-api-key': API_KEY },
-        sampleRate: 0.25,             // keep 25% of non-error records; errors always kept
-    },
-});
-```
-
-That's it: uncaught errors now flow to your logs (and the `sigx dev` terminal in development), and records at/above the level are batched and POSTed to your endpoint.
-
-## Pieces (compose them yourself)
-
-- **`installErrorCapture(opts?)`** — registers Lynx's `lynx.onError` (background thread) plus `globalThis` `error`/`unhandledrejection` handlers, normalizes whatever was thrown into an `Error`, and logs it at `error` level under the `uncaught` namespace. The `Error` rides in the record's `fields`, so transports can treat it as an exception (with a stack). Idempotent; returns an uninstall function.
-- **`createHttpSink(opts)`** — a batching `LogTransport` that POSTs `{ records: [...] }` as JSON to `opts.url`. Options: `batchSize`, `flushIntervalMs`, `sampleRate`, `minLevel`, `headers`, `excludeNamespaces`. `Error` fields are serialized to `{ name, message, stack }`. It excludes the `http` namespace by default (its own POSTs log there) and swallows its own send failures, so it can't feed back into itself. Has a `.flush()` for graceful shutdown.
-- **`toError(value)`** — the normalization helper, exported for reuse.
-
-```ts
-import { addTransport } from '@sigx/lynx';
-import { createHttpSink, installErrorCapture } from '@sigx/lynx-observability';
-
-addTransport(createHttpSink({ url, minLevel: 'info' }));
-const uninstall = installErrorCapture({ onError: (e) => myAnalytics.track('crash', e.message) });
-```
-
-## Wire format
-
-The sink POSTs:
-
-```json
-{ "records": [ { "level": "error", "namespace": "uncaught", "msg": "[lynx] …", "fields": [ { "name": "TypeError", "message": "…", "stack": "…" } ], "ts": 1733740000000 } ] }
-```
-
-## Provider adapters
-
-There's no built-in vendor coupling — any provider is a `LogTransport`. Errors arrive as `error`-level records with the `Error` in `fields[0]`, so an adapter can split exceptions from breadcrumbs. Example **Sentry** adapter (Sentry is an optional peer in *your* app, not a dependency of this package):
-
-```ts
-import * as Sentry from '@sentry/browser'; // your app's dep
-import { addTransport, installErrorCapture, type LogRecord } from '@sigx/lynx';
-
-Sentry.init({ dsn: SENTRY_DSN });
-
-addTransport((r: LogRecord) => {
-    const err = r.fields.find((f) => f instanceof Error) as Error | undefined;
-    if (r.level.name === 'error' && err) {
-        Sentry.captureException(err);
-    } else {
-        Sentry.addBreadcrumb({ category: r.namespace, message: r.msg, level: r.level.name });
-    }
-});
-installErrorCapture();
-```
-
-The same shape works for Datadog, a custom backend, etc.
-
-## Notes
-
-- `lynx.onError` is **background-thread only** upstream; main-thread error capture may need a separate path in the future.
-- For readable stack traces in release builds, upload your source maps to your provider (out of scope here).
-- Declarative `signalx.config.ts` `logging.production` config auto-wires this package in release builds (see Quick start above); `initObservability()` remains for manual/dev setup.
+# @sigx/lynx-observability
+
+Opt-in **production error capture** and **provider-agnostic log/error sinks** for sigx-lynx. Builds on the logger in [`@sigx/lynx-core`](https://sigx.dev/lynx/modules/core/overview/): uncaught errors are funneled in as `error`-level records, and a "sink" is just a `LogTransport`. No hard dependency on any vendor SDK.
+
+> Logging itself ships in the framework (`import { createLogger } from '@sigx/lynx'`). This package adds the *production* pieces — catching crashes and shipping records off-device — and is installed only when you want them.
+
+## 📚 Documentation
+
+Full guides, API reference and live examples → **[https://sigx.dev/lynx/](https://sigx.dev/lynx/)**
+
+## Install
+
+```sh
+pnpm add @sigx/lynx-observability
+```
+
+## Quick start — declarative (recommended)
+
+Declare it in `signalx.config.ts` and it auto-wires in **release** builds — no code in your app entry:
+
+```ts
+// signalx.config.ts
+export default defineLynxConfig({
+    name: 'my-app',
+    logging: {
+        level: 'warn',                     // logger level (also dev: 'debug' / release: 'warn' default)
+        namespaces: { disabled: ['http'] },// silence namespaces at startup
+        production: {
+            sink: { url: 'https://logs.example.com/ingest', headers: { 'x-api-key': KEY }, sampleRate: 0.25 },
+            captureErrors: true,           // default
+        },
+    },
+});
+```
+
+Just install the package (`pnpm add @sigx/lynx-observability`) — `@sigx/lynx-plugin` prepends the init for you in release builds. (Dev uses the console streamer; observability auto-wiring is release-only.)
+
+## Quick start — manual
+
+Or wire it yourself, `Sentry.init()`-style (call once in your app entry):
+
+```ts
+import { initObservability } from '@sigx/lynx-observability';
+
+initObservability({
+    level: 'warn',                    // optional: override the default level
+    captureErrors: true,              // default — catch uncaught errors / rejections
+    sink: {                           // optional remote sink
+        url: 'https://logs.example.com/ingest',
+        headers: { 'x-api-key': API_KEY },
+        sampleRate: 0.25,             // keep 25% of non-error records; errors always kept
+    },
+});
+```
+
+That's it: uncaught errors now flow to your logs (and the `sigx dev` terminal in development), and records at/above the level are batched and POSTed to your endpoint.
+
+## Pieces (compose them yourself)
+
+- **`installErrorCapture(opts?)`** — registers Lynx's `lynx.onError` (background thread) plus `globalThis` `error`/`unhandledrejection` handlers, normalizes whatever was thrown into an `Error`, and logs it at `error` level under the `uncaught` namespace. The `Error` rides in the record's `fields`, so transports can treat it as an exception (with a stack). Idempotent; returns an uninstall function.
+- **`createHttpSink(opts)`** — a batching `LogTransport` that POSTs `{ records: [...] }` as JSON to `opts.url`. Options: `batchSize`, `flushIntervalMs`, `sampleRate`, `minLevel`, `headers`, `excludeNamespaces`. `Error` fields are serialized to `{ name, message, stack }`. It excludes the `http` namespace by default (its own POSTs log there) and swallows its own send failures, so it can't feed back into itself. Has a `.flush()` for graceful shutdown.
+- **`toError(value)`** — the normalization helper, exported for reuse.
+
+```ts
+import { addTransport } from '@sigx/lynx';
+import { createHttpSink, installErrorCapture } from '@sigx/lynx-observability';
+
+addTransport(createHttpSink({ url, minLevel: 'info' }));
+const uninstall = installErrorCapture({ onError: (e) => myAnalytics.track('crash', e.message) });
+```
+
+## Wire format
+
+The sink POSTs:
+
+```json
+{ "records": [ { "level": "error", "namespace": "uncaught", "msg": "[lynx] …", "fields": [ { "name": "TypeError", "message": "…", "stack": "…" } ], "ts": 1733740000000 } ] }
+```
+
+## Provider adapters
+
+There's no built-in vendor coupling — any provider is a `LogTransport`. Errors arrive as `error`-level records with the `Error` in `fields[0]`, so an adapter can split exceptions from breadcrumbs. Example **Sentry** adapter (Sentry is an optional peer in *your* app, not a dependency of this package):
+
+```ts
+import * as Sentry from '@sentry/browser'; // your app's dep
+import { addTransport, installErrorCapture, type LogRecord } from '@sigx/lynx';
+
+Sentry.init({ dsn: SENTRY_DSN });
+
+addTransport((r: LogRecord) => {
+    const err = r.fields.find((f) => f instanceof Error) as Error | undefined;
+    if (r.level.name === 'error' && err) {
+        Sentry.captureException(err);
+    } else {
+        Sentry.addBreadcrumb({ category: r.namespace, message: r.msg, level: r.level.name });
+    }
+});
+installErrorCapture();
+```
+
+The same shape works for Datadog, a custom backend, etc.
+
+## Notes
+
+- `lynx.onError` is **background-thread only** upstream; main-thread error capture may need a separate path in the future.
+- For readable stack traces in release builds, upload your source maps to your provider (out of scope here).
+- Declarative `signalx.config.ts` `logging.production` config auto-wires this package in release builds (see Quick start above); `initObservability()` remains for manual/dev setup.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sigx/lynx-observability",
-  "version": "0.6.1",
+  "version": "0.8.0",
   "description": "Opt-in production error capture + provider-agnostic log/error sinks for sigx-lynx",
   "type": "module",
   "main": "./dist/index.js",
@@ -38,8 +38,8 @@
     "url": "https://github.com/signalxjs/lynx/issues"
   },
   "dependencies": {
-    "@sigx/lynx-core": "^0.6.1",
-    "@sigx/lynx-http": "^0.6.1"
+    "@sigx/lynx-core": "^0.8.0",
+    "@sigx/lynx-http": "^0.8.0"
   },
   "devDependencies": {
     "@typescript/native-preview": "7.0.0-dev.20260521.1",