@effectstream/log 0.100.14 → 0.100.15

package/README.md

@@ -0,0 +1,83 @@
+# @effectstream/log
+
+OpenTelemetry-instrumented structured logging for EffectStream. Wraps
+`tslog` and the OpenTelemetry SDK behind a single `log` object that emits
+both pretty console output (`log.local`) and OTLP traces/logs to your
+collector (`log.remote`).
+
+## Install
+
+```bash
+bun add @effectstream/log
+# or
+npm install @effectstream/log
+```
+
+## Standalone usage
+
+Any Node service that wants colored terminal logs plus OTLP export with one
+dependency.
+
+```typescript
+import {
+  ComponentNames,
+  defaultOtelSetup,
+  log,
+  SeverityNumber,
+} from "@effectstream/log";
+
+// Initialize OpenTelemetry once at startup (optional — defaults work too).
+defaultOtelSetup({ serviceName: "my-app" });
+
+// Local-only: pretty console output, no OTLP.
+log.local(
+  "my-app",                  // component name (any string)
+  "startup",                 // namespace
+  SeverityNumber.INFO,
+  (l) => l("started on port", 3000),
+);
+
+// Remote: console + OpenTelemetry log record + trace correlation.
+log.remote(
+  "my-app",
+  "auth",
+  SeverityNumber.INFO,
+  (l) => l("user logged in", { userId: "u_123" }),
+);
+```
+
+The deferred `(l) => l(...)` form means message construction is skipped
+entirely when the level is filtered out — handy when log arguments are
+expensive to format (`JSON.stringify` of a big object).
+
+Point the SDK at any OTLP-compatible collector (Grafana Alloy, Tempo,
+Honeycomb, …) via the standard `OTEL_EXPORTER_OTLP_ENDPOINT` env var.
+
+## Inside EffectStream
+
+Every package in the framework — sync, runtime, batcher, sm — logs through
+this module so the whole node emits one consistent trace tree. The
+`ComponentNames` constants tag log records by component, which is what
+powers the orchestrator's per-component log views.
+
+## Key exports
+
+- `log.local(component, namespace, level, deferred)` — console-only logging. `level` is `SeverityNumber`; `deferred = (l) => l(...args)` is called only if the level passes the filter.
+- `log.localForce(...)` — bypasses level filtering.
+- `log.remote(...)` — console + OpenTelemetry log record. Same signature as `local`.
+- `log.remoteForce(...)` — `remote` without level filtering.
+- `log.formatMessage(...)` — the formatter used internally; useful for custom transports.
+- `defaultOtelSetup(opts)` — one-call OpenTelemetry SDK setup with sensible defaults.
+- `attachTransport(transport)` — register a custom tslog transport (e.g. ship logs to a file).
+- `SeverityNumber` — re-export of OpenTelemetry severity levels.
+- `ComponentNames` — string-enum constants used to tag logs by component.
+- `Namespace` — `string | string[]` for log namespacing.
+
+## Examples
+
+Runnable: [`test/examples.test.ts`](./test/examples.test.ts).
+
+## Links
+
+- Docs: https://effectstream.github.io/docs/packages/sdk/log
+- Source: https://github.com/PaimaStudios/paima-engine/tree/main/packages/effectstream-sdk/log

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effectstream/log",
-  "version": "0.100.14",
+  "version": "0.100.15",
   "license": "MIT",
   "homepage": "https://effectstream.github.io/docs/",
   "repository": {
@@ -13,7 +13,7 @@
   },
   "exports": "./src/mod.ts",
   "dependencies": {
-    "@effectstream/utils": "0.100.14",
+    "@effectstream/utils": "0.100.15",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/api-logs": "0.56.0",
     "@opentelemetry/exporter-logs-otlp-http": "0.56.0",

package/test/examples.test.ts

@@ -0,0 +1,52 @@
+// Examples for the README.
+
+import { test, expect } from "bun:test";
+import { ComponentNames, log, SeverityNumber } from "../src/mod.ts";
+
+test("README: log.local accepts a deferred message function", () => {
+  let called = 0;
+  log.local(
+    "my-app",
+    "startup",
+    SeverityNumber.INFO,
+    (l) => {
+      called++;
+      l("started on port", 3000);
+    },
+  );
+  // The deferred is invoked synchronously at the appropriate level.
+  expect(called).toBe(1);
+});
+
+test("README: log.remote accepts the same signature as log.local", () => {
+  let called = 0;
+  log.remote(
+    "my-app",
+    "auth",
+    SeverityNumber.INFO,
+    (l) => {
+      called++;
+      l("user logged in", { userId: "u_123" });
+    },
+  );
+  expect(called).toBe(1);
+});
+
+test("README: log.localForce bypasses level filtering", () => {
+  let called = 0;
+  log.localForce(
+    "my-app",
+    "audit",
+    SeverityNumber.DEBUG,
+    (l) => {
+      called++;
+      l("low-severity message that would normally be filtered");
+    },
+  );
+  expect(called).toBe(1);
+});
+
+test("README: ComponentNames are usable as component tags", () => {
+  expect(typeof ComponentNames.EFFECTSTREAM_SYNC).toBe("string");
+  expect(typeof ComponentNames.EFFECTSTREAM_RUNTIME).toBe("string");
+});