@vibesdotdev/logging 0.0.2 → 1.0.0-rc.5

package/dist/docs/logging.docs.descriptor.d.ts

@@ -0,0 +1,4 @@
+import type { DocsTopicDescriptor } from '@vibesdotdev/docs-contracts';
+declare const descriptor: DocsTopicDescriptor;
+export default descriptor;
+//# sourceMappingURL=logging.docs.descriptor.d.ts.map

package/dist/docs/logging.docs.descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logging.docs.descriptor.d.ts","sourceRoot":"","sources":["../../src/docs/logging.docs.descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAEvE,QAAA,MAAM,UAAU,EAAE,mBAsGjB,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/logging.docs.descriptor.js

@@ -0,0 +1,105 @@
+const descriptor = {
+    kind: 'docs/topic',
+    id: 'logging',
+    title: 'Logging',
+    summary: 'Structured logging for Vibes: runtime kinds, the core logger, sinks, outputs, audit and host surfaces',
+    body: {
+        type: 'markdown',
+        sourceType: 'raw',
+        source: `---
+title: Logging
+summary: Structured logging for Vibes — runtime kinds, the core logger, sinks, outputs, audit and host surfaces
+tags: [logging, sinks, outputs, audit, runtime]
+order: 0
+id: logging
+surfaces: [cli, web, in-app]
+hardware: [consumer, cloud]
+---
+
+# Logging
+
+\`@vibesdotdev/logging\` is the structured-logging package for Vibes. Features log
+through \`getLogger(namespace)\`; the runtime decides where entries go by
+resolving the registered \`logging/sink\`, \`logging/formatter\` and
+\`logging/output\` descriptors for the current scope.
+
+## Runtime kinds
+
+| Kind | What it resolves |
+| --- | --- |
+| \`logging/logger\` | Named logger configuration (namespace, level, sinks) |
+| \`logging/sink\` | Where live entries are written (console, stdout, memory, file, browser, otel) |
+| \`logging/formatter\` | How an entry becomes text (\`jsonl\`, \`json\`, \`json5\`, \`pretty\`) |
+| \`logging/output\` | Durable, readable streams with rotation (\`file\`, \`remote\`) |
+| \`logging/audit\` | Append-only audit loggers with retention by category |
+| \`observability/telemetry-instrumentation\` | Provider OpenTelemetry instrumentation factories |
+
+## Quick start
+
+\`\`\`ts
+import { bootstrapVibesRuntime } from '@vibesdotdev/kernel';
+import loggingPlugin from '@vibesdotdev/logging/plugin';
+import loggingConsumerPlugin from '@vibesdotdev/logging/consumer/plugin';
+import { getLogger } from '@vibesdotdev/logging';
+
+// \`environment\` is your host's environment plugin.
+const runtime = await bootstrapVibesRuntime({
+  environment,
+  composition: { kind: 'literal', plugins: [async () => loggingPlugin, async () => loggingConsumerPlugin] }
+});
+
+const log = getLogger('myapp:db', runtime);
+log.info('connected', { host: 'localhost' });
+\`\`\`
+
+## Surfaces
+
+The package root is universal: it runs on Bun, Node, workerd and in the
+browser, and it never writes to stdout. Host-bound pieces live on named subpaths
+and register themselves through their own plugin:
+
+| Subpath | Host | Adds |
+| --- | --- | --- |
+| \`./consumer/plugin\` | Terminal consumer | Colorized console sink and pretty formatter |
+| \`./host\` (base implementation \`./host-files\`: each host registers \`createHostFileLoggingPlugin\` over its own file primitives, as \`@vibesdotdev/host-node/logging\`'s \`nodeLoggingPlugin\` and the Bun host's own logging plugin do) | Bun / Node | \`file\` sink, \`file\` and \`mcp-stdout-capture\` outputs, the file-backed audit logger, scheduled audit retention |
+| \`./browser\`, \`./browser/plugin\` | Browser | \`browser\` sink, \`captureSvelteKitError\` |
+| \`./otel\`, \`./otel/plugin\` | Server | \`otel\` sink (OTLP/HTTP log export) |
+| \`./observability\` | Server | Telemetry bootstrap, error tracker, instrumented fetch — see [\`logging.observability\`](logging.observability) |
+| \`./cli/plugin\` | CLI | The \`vibes logs\` commands — see [\`logging.cli\`](logging.cli) |
+
+## Configuration
+
+Every key is read through the handed runtime (\`runtime.getEnv\`), mostly as
+the declared default of a \`logging\` config setting, never from
+\`process.env\` directly.
+
+| Key | Read by | Purpose |
+| --- | --- | --- |
+| \`VIBES_LOG\` | core, host \`file\` sink | Namespace selectors, e.g. \`app:*,-app:auth\` |
+| \`VIBES_LOG_LEVEL\` / \`LOG_LEVEL\` | core, host \`file\` sink | Baseline level: \`debug\`, \`info\`, \`warn\` or \`error\` (default \`info\`); any other value is refused |
+| \`VIBES_LOG_INFO_SAMPLING_RATE\` | \`logging/logger\` loggers (not the core \`createRuntimeLogger\`) | Fraction of \`info\` entries kept, 0 to 1; every other level is always kept; an empty or malformed value is refused |
+| \`VIBES_LOG_FILE\` | host \`file\` sink | File name inside the log directory (default \`app.log\`) |
+| \`VIBES_LOG_RETENTION_INTERVAL_MS\` | host \`file\` output | Rotated-file cleanup interval (default 1 hour) |
+| \`VIBES_LOG_MAX_SIZE\`, \`VIBES_LOG_MAX_AGE\`, \`VIBES_LOG_MAX_FILES\` | host \`file\` output | Settings \`fileRotationMaxSize\` (\`25MB\`), \`fileRotationMaxAge\` (\`14d\`), \`fileRotationMaxFiles\` (\`8\`): rotation where an output declares none; a malformed value is refused |
+| \`OTEL_SERVICE_NAME\`, \`OTEL_EXPORTER_OTLP_LOGS_ENDPOINT\`, \`OTEL_EXPORTER_OTLP_ENDPOINT\` | \`./otel\` | Log export target |
+
+The log directory itself comes from \`@vibesdotdev/paths\` (\`VIBES_LOG_DIR\`,
+default \`~/.vibes/logs\`).
+
+:::card{title="See also"}
+- [\`logging.levels\`](logging.levels) — levels and namespace filtering
+- [\`logging.structured\`](logging.structured) — structured entries, context and audit
+- [\`logging.transports\`](logging.transports) — sinks, formatters and outputs
+- [\`logging.cli\`](logging.cli) — \`vibes logs\`
+- [\`logging.observability\`](logging.observability) — telemetry and error tracking
+:::
+`
+    },
+    order: 0,
+    tags: ['logging', 'sinks', 'outputs', 'audit', 'runtime'],
+    surfaces: ['cli', 'web', 'in-app'],
+    hardware: ['consumer', 'cloud'],
+    enabled: true
+};
+export default descriptor;
+//# sourceMappingURL=logging.docs.descriptor.js.map

package/dist/docs/logging.docs.descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logging.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/logging.docs.descriptor.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,GAAwB;IACvC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,SAAS;IACb,KAAK,EAAE,SAAS;IAChB,OAAO,EAAE,uGAAuG;IAChH,IAAI,EAAE;QACL,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuFT;KACC;IACD,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,CAAC;IACzD,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC;IAClC,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,OAAO,EAAE,IAAI;CACb,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/observability.docs.descriptor.d.ts

@@ -0,0 +1,4 @@
+import type { DocsTopicDescriptor } from '@vibesdotdev/docs-contracts';
+declare const descriptor: DocsTopicDescriptor;
+export default descriptor;
+//# sourceMappingURL=observability.docs.descriptor.d.ts.map

package/dist/docs/observability.docs.descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability.docs.descriptor.d.ts","sourceRoot":"","sources":["../../src/docs/observability.docs.descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAEvE,QAAA,MAAM,UAAU,EAAE,mBAqJjB,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/observability.docs.descriptor.js

@@ -0,0 +1,152 @@
+const descriptor = {
+    kind: 'docs/topic',
+    id: 'logging.observability',
+    title: 'Observability',
+    summary: 'OpenTelemetry bootstrap and status, provider instrumentation, error tracking, instrumented fetch and the integration settings port',
+    body: {
+        type: 'markdown',
+        sourceType: 'raw',
+        source: `---
+title: Observability
+summary: OpenTelemetry bootstrap and status, provider instrumentation, error tracking, instrumented fetch and the integration settings port
+tags: [logging, observability, opentelemetry, otel, telemetry, signoz, redis, clickhouse]
+parent: logging
+order: 5
+id: logging.observability
+surfaces: [web]
+hardware: [cloud, consumer]
+---
+
+# Observability
+
+\`@vibesdotdev/logging/observability\` wires a server host to an OpenTelemetry
+collector. Every \`@opentelemetry/*\` package loads lazily, so importing the
+barrel never pulls the SDK into a bundle that does not start telemetry.
+
+## Start telemetry
+
+Start telemetry after the host has registered its runtime environment. Settings
+come from the logging config manifest (useful defaults) read through the runtime:
+
+\`\`\`ts
+import { initializeTelemetry, getTelemetryStatus } from '@vibesdotdev/logging/observability';
+
+await initializeTelemetry(runtime); // the host runtime; never throws, failures are logged
+await getTelemetryStatus(runtime);
+// { initialized, enabled, outcome, config: { serviceName, environment, endpoint, protocol, samplingRate } }
+\`\`\`
+
+\`outcome\` (also \`getTelemetryInitializationOutcome(runtime)\`) is the typed
+result of this runtime's last \`initializeTelemetry\` call: \`not-attempted\`,
+\`started\` (with where the exporter headers came from), \`disabled\`
+(\`not-enabled\` or \`explicit-off\`), \`unavailable\` (\`otel-modules-absent\` or
+\`trace-exporter-absent\`), \`already-initialized\`, or \`failed\`
+(\`otel-headers-unresolved\`, \`otel-ambient-headers\`, \`initialization-failed\`,
+\`concurrent-initialization-failed\`, or \`telemetry-owned-by-another-runtime\`:
+the OpenTelemetry SDK's global registry belongs to the first runtime that
+started telemetry). A host that does not start telemetry says why.
+
+The OTLP exporter headers are a credential: they resolve only through
+\`runtime.resolveCredential\` from the declared \`otelHeadersCredential\`
+reference (conventionally secret \`OTEL_EXPORTER_OTLP_HEADERS\`, \`key=value\`
+pairs, comma separated), never from an environment variable or a stored value.
+No declared reference means no headers and no lookup, so a host with no
+secrets store still starts telemetry. A declared credential that is not set
+means no headers; any other resolution failure, or a malformed pair, leaves
+telemetry unstarted with outcome \`failed\`.
+
+Telemetry is enabled when the logging manifest sets \`otelEnabled: true\`, when
+\`OTEL_ENABLED=true\`, or when \`OTEL_EXPORTER_OTLP_ENDPOINT\` is set.
+\`OTEL_ENABLED=false\` stays off even with an endpoint. Service name is
+\`OTEL_SERVICE_NAME\`, else \`SERVICE_TYPE\` mapped to \`vibes-web\` /
+\`vibes-workers\` / \`vibes-mcp\`, else the manifest default \`vibes\`.
+\`NODE_ENV\` fills the environment resource when bound. A missing endpoint uses
+the logging config default. A malformed setting is never replaced by a default:
+an endpoint that is not a URL, an \`OTEL_TRACES_SAMPLER_ARG\` that is not a
+decimal from 0 to 1, or an \`OTEL_EXPORT_INTERVAL\` that is not whole
+milliseconds of at least 1000 fails startup (outcome \`failed\`, reason
+\`telemetry-config-invalid\`, its error \`INVALID_INPUT logging-config-invalid\`
+naming the setting in \`details.fields\`), and \`getTelemetryStatus\` refuses
+with that error. \`initializeTelemetry\` itself never throws.
+
+| Manifest field | Default | Purpose |
+| --- | --- | --- |
+| \`otelEnabled\` | omitted (env on-switch) | Turn telemetry on via composition |
+| \`otelEndpoint\` | \`http://localhost:4317\` | gRPC collector endpoint |
+| \`otelLogsEndpoint\` | \`http://localhost:4318/v1/logs\` | OTLP logs HTTP endpoint |
+| \`otelHeadersCredential\` | omitted (no headers, no lookup) | Credential holding the exporter headers, e.g. \`{ source: 'secret', key: 'OTEL_EXPORTER_OTLP_HEADERS' }\` |
+| \`otelServiceName\` | \`vibes\` | Service name |
+| \`otelServiceVersion\` | \`0.0.1\` | Service version |
+| \`otelEnvironment\` | \`development\` | Deployment environment resource attribute |
+| \`otelHostName\` | \`localhost\` | Host name resource attribute |
+| \`otelSamplingRate\` | \`1.0\` | Trace sampling ratio |
+| \`otelExportInterval\` | \`30000\` | Metric export interval in ms |
+
+\`shutdownTelemetry(runtime)\` flushes and stops the runtime's SDK.
+\`disposeObservability(runtime)\` disposes its telemetry; attach it to your host's own lifecycle (vendor clients such
+as Redis dispose from their own plugin). Observability never installs signal handlers.
+
+## Provider instrumentation
+
+Provider instrumentation (AWS SDK from \`@vibesdotdev/integrations-aws\`,
+Redis/ioredis from \`@vibesdotdev/integrations-redis\`, …) is contributed through
+the \`observability/telemetry-instrumentation\` runtime kind. An integration
+registers a descriptor and a loader whose implementation is an instrumentation
+factory. \`initializeTelemetry(runtime)\` builds every composed entry
+(\`resolveComposedTelemetryInstrumentations(runtime)\`);
+\`resolveTelemetryInstrumentation(runtime, id)\` builds one. An uncomposed id
+resolves to \`null\`; a composed factory that fails to load fails telemetry
+startup, which is logged (initialization never throws). The framework never
+imports a provider package.
+
+\`\`\`ts
+import type { TelemetryInstrumentationDescriptor } from '@vibesdotdev/logging/observability';
+
+const descriptor: TelemetryInstrumentationDescriptor = {
+  kind: 'observability/telemetry-instrumentation',
+  id: 'aws-sdk',
+  config: { package: '@opentelemetry/instrumentation-aws-sdk', version: '0.x' }
+};
+\`\`\`
+
+## Error tracking and instrumented fetch
+
+- \`ErrorTracker.trackError(runtime, type, { message, stack?, context? })\`
+  counts the runtime's errors in a 5-minute window and logs an alert after 5,
+  at most once per 5 minutes. \`ErrorTracker.getStats(runtime)\` and
+  \`ErrorTracker.reset(runtime)\` are available for health pages and tests. Subpath: \`./observability/error-tracker\`.
+- \`instrumentedFetch(runtime, input, init)\` wraps \`fetch\` in a CLIENT span,
+  injects \`traceparent\` and reports through the runtime's logger (the URL it
+  logs and attributes never carries userinfo or query);
+  \`instrumentedJsonFetch(runtime, url, { params, timeout })\` adds query
+  parameters, a timeout and JSON parsing.
+
+## Vendor clients live in their integrations
+
+The SignOz, ClickHouse and Redis clients moved out of logging (RC09):
+
+| Package | Provides | Configuration |
+| --- | --- | --- |
+| \`@vibesdotdev/integrations-signoz\` | \`SignOzClient\`, \`createSignOzClient(runtime, overrides?)\` | manifest \`integrations.signoz\`; secret \`SIGNOZ_API_KEY\` |
+| \`@vibesdotdev/integrations-clickhouse\` | \`clickhouseFor(runtime)\`, \`clickhouseMigrations(runtime)\`, query helpers, rate-limit metrics | manifest \`integrations.clickhouse\`; secret \`CLICKHOUSE_PASSWORD\` |
+| \`@vibesdotdev/integrations-redis\` | \`redisManagerFor(runtime)\`, \`getRedisConnection(runtime)\`, \`redisConnectionsFor(runtime)\`, \`instrumentRedisClient\`, the ioredis/redis telemetry instrumentations, the Workers scheduler lock | manifest \`integrations.redis\`; secrets \`REDIS_URL\`, \`REDIS_<PURPOSE>_URL\` |
+
+They read settings and credentials through \`@vibesdotdev/logging/observability/config\`
+(\`readIntegrationSettings\`, \`resolveOptionalSecret\`, \`isDeclaredBuildHost\`) on the
+runtime they are handed; no environment variable is read. Subpath: \`./observability/config\`.
+
+:::card{title="See also"}
+- [\`logging\`](logging) — package overview
+- [\`logging.transports\`](logging.transports) — the \`otel\` log sink lives in \`./otel\`
+:::
+`
+    },
+    parent: 'logging',
+    order: 5,
+    tags: ['logging', 'observability', 'opentelemetry', 'otel', 'telemetry', 'signoz', 'redis', 'clickhouse'],
+    surfaces: ['web'],
+    hardware: ['cloud', 'consumer'],
+    enabled: true
+};
+export default descriptor;
+//# sourceMappingURL=observability.docs.descriptor.js.map

package/dist/docs/observability.docs.descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/observability.docs.descriptor.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,GAAwB;IACvC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,uBAAuB;IAC3B,KAAK,EAAE,eAAe;IACtB,OAAO,EAAE,oIAAoI;IAC7I,IAAI,EAAE;QACL,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqIT;KACC;IACD,MAAM,EAAE,SAAS;IACjB,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,SAAS,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,OAAO,EAAE,YAAY,CAAC;IACzG,QAAQ,EAAE,CAAC,KAAK,CAAC;IACjB,QAAQ,EAAE,CAAC,OAAO,EAAE,UAAU,CAAC;IAC/B,OAAO,EAAE,IAAI;CACb,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/structured.docs.descriptor.d.ts

@@ -1,4 +1,4 @@
-import type { DocsTopicDescriptor } from '@vibesdotdev/docs';
+import type { DocsTopicDescriptor } from '@vibesdotdev/docs-contracts';
 declare const descriptor: DocsTopicDescriptor;
 export default descriptor;
 //# sourceMappingURL=structured.docs.descriptor.d.ts.map

package/dist/docs/structured.docs.descriptor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"structured.docs.descriptor.d.ts","sourceRoot":"","sources":["../../src/docs/structured.docs.descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAE7D,QAAA,MAAM,UAAU,EAAE,mBAubjB,CAAC;AAEF,eAAe,UAAU,CAAC"}
+{"version":3,"file":"structured.docs.descriptor.d.ts","sourceRoot":"","sources":["../../src/docs/structured.docs.descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAEvE,QAAA,MAAM,UAAU,EAAE,mBA2RjB,CAAC;AAEF,eAAe,UAAU,CAAC"}