@prilog/monitoring 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Prilog
+
+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

@@ -0,0 +1,80 @@
+# @prilog/monitoring
+
+Prilog monitoring for Node.js, built on OpenTelemetry. Collect application logs, distributed traces, and exceptions, and connect them to your Prilog System Map and issue analysis.
+
+## Install
+
+```bash
+npm install @prilog/monitoring
+```
+
+## Initialize
+
+Select **Add free Prilog monitoring** for your service in Prilog and copy its DSN into the `PRILOG_DSN` environment variable.
+
+Create an `instrumentation.cjs` file:
+
+```javascript
+const { init } = require('@prilog/monitoring');
+
+const monitoring = init({
+  dsn: process.env.PRILOG_DSN,
+  serviceName: 'checkout-api',
+});
+
+module.exports = monitoring;
+```
+
+Load this file before your application imports. For an application with an existing `npm start` script:
+
+```bash
+NODE_OPTIONS="--require=./instrumentation.cjs" npm start
+```
+
+If you already set `NODE_OPTIONS`, add the `--require=./instrumentation.cjs` option to it. The `.cjs` extension works in both CommonJS and ESM projects.
+
+Initialization sends a startup log and span. Once Prilog receives them, it verifies your monitoring connection automatically. Without a DSN, initialization returns a disabled monitor.
+
+## Logs, traces, and exceptions
+
+Supported Node framework/client instrumentation, console capture, and uncaught-exception capture are enabled by default.
+
+```javascript
+const { withSpan, log, captureException } = require('@prilog/monitoring');
+
+withSpan('checkout.validate', () => {
+  log('info', 'Order validated', { 'order.id': 'example-order' });
+});
+
+// In an existing handled-error path:
+captureException(new Error('Payment declined'));
+```
+
+`withSpan(name, callback, attributes?)` accepts synchronous or asynchronous callbacks, returns their result, and records and rethrows errors. `log(level, message, attributes?)` supports `trace`, `debug`, `info`, `warn`, `error`, and `fatal`. `captureException(error, attributes?)` records a handled exception and its stack trace.
+
+## Configuration
+
+Pass these options to `init`:
+
+| Option | Description | Default |
+| --- | --- | --- |
+| `dsn` | Your service's ingest DSN; `PRILOG_DSN` takes precedence | `PRILOG_DSN` |
+| `serviceName` | Service identity; `OTEL_SERVICE_NAME` takes precedence | `application` |
+| `environment` | Deployment environment | `NODE_ENV` or `production` |
+| `release` | Application release/version | `PRILOG_RELEASE`, `GITHUB_SHA`, or `unknown` |
+| `sampleRate` | Root trace sampling ratio, between 0 and 1 | `1` |
+| `captureConsole` | Capture console output as structured logs | `true` |
+| `captureUncaught` | Capture uncaught exceptions | `true` |
+| `autoInstrument` | Enable supported Node framework/client instrumentation | `true` |
+| `instrumentations` | OpenTelemetry auto-instrumentation configuration overrides | `{}` |
+| `resourceAttributes` | Additional OpenTelemetry resource attributes | `{}` |
+
+## Shutdown
+
+Await `monitoring.shutdown()` from your application's existing graceful-shutdown handler to flush pending telemetry. When the SDK owns the uncaught-exception handler, it flushes the captured error with a bounded timeout and exits with status 1.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).
+
+Source and issue tracker: [Prilog-ai/prilog-monitoring](https://github.com/Prilog-ai/prilog-monitoring).

package/index.cjs

@@ -0,0 +1,136 @@
+'use strict';
+
+const { context, trace, SpanStatusCode } = require('@opentelemetry/api');
+const { logs } = require('@opentelemetry/api-logs');
+const { NodeSDK } = require('@opentelemetry/sdk-node');
+const { BatchLogRecordProcessor } = require('@opentelemetry/sdk-logs');
+const { OTLPLogExporter } = require('@opentelemetry/exporter-logs-otlp-http');
+const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http');
+const { resourceFromAttributes } = require('@opentelemetry/resources');
+const { ParentBasedSampler, TraceIdRatioBasedSampler } = require('@opentelemetry/sdk-trace-base');
+const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
+
+const stateKey = Symbol.for('prilog.monitoring.sdk');
+const levels = { trace: 1, debug: 5, info: 9, log: 9, warn: 13, error: 17, fatal: 21 };
+
+function configuration(dsn) {
+  const url = new URL(dsn);
+  if (!['http:', 'https:'].includes(url.protocol) || !url.username || url.password || url.search || url.hash) {
+    throw new Error('Invalid Prilog monitoring DSN');
+  }
+  const key = decodeURIComponent(url.username);
+  url.username = '';
+  return { endpoint: url.toString().replace(/\/$/, ''), headers: { 'X-Prilog-OTLP-Token': key } };
+}
+
+function init(options = {}) {
+  if (globalThis[stateKey]) return globalThis[stateKey].api;
+  const dsn = process.env.PRILOG_DSN || options.dsn;
+  if (!dsn) return { enabled: false, shutdown: async () => {} };
+  const config = configuration(dsn);
+  const endpoint = (process.env.OTEL_EXPORTER_OTLP_ENDPOINT || config.endpoint).replace(/\/$/, '');
+  const rate = options.sampleRate ?? 1;
+  if (!Number.isFinite(rate) || rate < 0 || rate > 1) throw new Error('sampleRate must be between zero and one');
+  process.env.OTEL_METRICS_EXPORTER ??= 'none';
+  const sdk = new NodeSDK({
+    resource: resourceFromAttributes({
+      'service.name': process.env.OTEL_SERVICE_NAME || options.serviceName || 'application',
+      'deployment.environment.name': options.environment || process.env.NODE_ENV || 'production',
+      'service.version': options.release || process.env.PRILOG_RELEASE || process.env.GITHUB_SHA || 'unknown',
+      'prilog.sdk.version': '0.1.0',
+      ...options.resourceAttributes,
+    }),
+    traceExporter: new OTLPTraceExporter({ url: `${endpoint}/v1/traces`, headers: config.headers, timeoutMillis: 5000 }),
+    logRecordProcessors: [new BatchLogRecordProcessor(new OTLPLogExporter({ url: `${endpoint}/v1/logs`, headers: config.headers, timeoutMillis: 5000 }))],
+    sampler: new ParentBasedSampler({ root: new TraceIdRatioBasedSampler(rate) }),
+    instrumentations: options.autoInstrument === false ? [] : [getNodeAutoInstrumentations({
+      '@opentelemetry/instrumentation-fs': { enabled: false },
+      ...options.instrumentations,
+    })],
+  });
+  sdk.start();
+  const originals = new Map();
+  let emitting = false;
+  if (options.captureConsole !== false) {
+    for (const level of ['debug', 'info', 'log', 'warn', 'error']) {
+      const original = console[level];
+      const wrapper = function (...args) {
+        original.apply(console, args);
+        if (emitting) return;
+        emitting = true;
+        try { log(level, args.map(value => value instanceof Error ? value.stack : typeof value === 'string' ? value : safeJSON(value)).join(' ')); }
+        finally { emitting = false; }
+      };
+      originals.set(level, { original, wrapper });
+      console[level] = wrapper;
+    }
+  }
+  const ownsFatalHandler = options.captureUncaught !== false && process.listenerCount('uncaughtException') === 0;
+  const onException = error => {
+    captureException(error, { 'exception.escaped': true });
+    if (ownsFatalHandler && process.listeners('uncaughtException').every(handler => handler === onException)) {
+      process.stderr.write(`${error.stack || error}\n`);
+      const timeout = setTimeout(() => process.exit(1), 3000);
+      void api.shutdown().catch(() => {}).finally(() => { clearTimeout(timeout); process.exit(1); });
+    }
+  };
+  const exceptionEvent = ownsFatalHandler ? 'uncaughtException' : 'uncaughtExceptionMonitor';
+  if (options.captureUncaught !== false) process.on(exceptionEvent, onException);
+  let closing;
+  const api = {
+    enabled: true,
+    shutdown() {
+      if (closing) return closing;
+      process.removeListener(exceptionEvent, onException);
+      process.removeListener('beforeExit', onExit);
+      for (const [level, { original, wrapper }] of originals) if (console[level] === wrapper) console[level] = original;
+      closing = sdk.shutdown();
+      return closing;
+    },
+  };
+  const onExit = () => { void api.shutdown().catch(() => {}); };
+  process.once('beforeExit', onExit);
+  globalThis[stateKey] = { api };
+  withSpan('prilog.startup', () => log('info', 'Prilog monitoring initialized', { 'prilog.startup': true }));
+  return api;
+}
+
+function log(level, message, attributes = {}) {
+  logs.getLogger('prilog.monitoring', '0.1.0').emit({
+    severityNumber: levels[level] || 9, severityText: level.toUpperCase(), body: String(message),
+    attributes, context: context.active(),
+  });
+}
+
+function captureException(error, attributes = {}) {
+  if (!(error instanceof Error)) error = new Error(String(error));
+  const active = trace.getActiveSpan();
+  const span = active || trace.getTracer('prilog.monitoring').startSpan('exception');
+  context.with(trace.setSpan(context.active(), span), () => {
+    span.recordException(error);
+    span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
+    log('error', error.message, { 'exception.type': error.name, 'exception.message': error.message, 'exception.stacktrace': error.stack || '', ...attributes });
+  });
+  if (!active) span.end();
+}
+
+function withSpan(name, fn, attributes = {}) {
+  return trace.getTracer('prilog.monitoring').startActiveSpan(name, { attributes }, span => {
+    try {
+      const result = fn(span);
+      if (result && typeof result.then === 'function') {
+        return Promise.resolve(result).catch(error => { captureException(error); throw error; }).finally(() => span.end());
+      }
+      span.end();
+      return result;
+    } catch (error) {
+      captureException(error);
+      span.end();
+      throw error;
+    }
+  });
+}
+
+function safeJSON(value) { try { return JSON.stringify(value, (key, item) => /password|secret|authorization|cookie|api[_-]?key|access_token|refresh_token/i.test(key) ? '[REDACTED]' : item); } catch { return String(value); } }
+
+module.exports = { init, captureException, withSpan, log, configuration };

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@prilog/monitoring",
+  "version": "0.1.0",
+  "description": "OpenTelemetry logs, traces and exception capture for Prilog",
+  "repository": { "type": "git", "url": "git+https://github.com/Prilog-ai/prilog-monitoring.git" },
+  "homepage": "https://github.com/Prilog-ai/prilog-monitoring#readme",
+  "bugs": { "url": "https://github.com/Prilog-ai/prilog-monitoring/issues" },
+  "license": "MIT",
+  "main": "index.cjs",
+  "exports": { ".": "./index.cjs" },
+  "files": ["index.cjs", "LICENSE"],
+  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
+  "engines": { "node": ">=18" },
+  "scripts": { "test": "node --test test.cjs", "prepublishOnly": "npm test" },
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/api-logs": "^0.200.0",
+    "@opentelemetry/auto-instrumentations-node": "^0.60.0",
+    "@opentelemetry/exporter-logs-otlp-http": "^0.200.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.200.0",
+    "@opentelemetry/resources": "^2.0.0",
+    "@opentelemetry/sdk-logs": "^0.200.0",
+    "@opentelemetry/sdk-node": "^0.200.0",
+    "@opentelemetry/sdk-trace-base": "^2.0.0"
+  }
+}