jarvis-observe
v0.1.1
Published
Lightweight Node.js telemetry observer for J.A.R.V.I.S.
Maintainers
Readme
J.A.R.V.I.S. Node.js Observer SDK
MVP Node.js telemetry SDK for collecting logs and errors and forwarding them to a J.A.R.V.I.S. ingestion endpoint.
Requirements
- Node.js 18+
- CommonJS in this MVP (
require). ESM applications can import the CommonJS default export.
Install locally
npm install ./jarvis-observeInitialize
const jarvis = require("jarvis-observe");
jarvis.init({
endpoint: "https://ingest.jarvis.ai/v1/events",
apiKey: "YOUR_API_KEY",
projectId: "my-project",
serviceId: "backend",
repository: "https://github.com/user/project",
environment: "production"
});init() installs capture hooks automatically. Developers do not need to register
uncaughtExceptionMonitor or unhandledRejection themselves.
What it captures
| Source | Capture mechanism | Notes |
|---|---|---|
| console.log/info/debug/warn/error | Console method wrappers | Original console output is preserved |
| process.stdout | write wrapper | Captures complete lines |
| process.stderr | write wrapper | Can overlap with console/error output |
| Uncaught synchronous exceptions | uncaughtExceptionMonitor | Observes without suppressing Node's default termination |
| Unhandled Promise rejections | unhandledRejection | Does not represent every asynchronous failure |
| Worker errors | Worker error event monitoring | Existing workers can be passed to monitorWorker only through the internal client in this MVP; see limitations |
Explicitly report caught exceptions
Global hooks cannot see exceptions that application code catches and silently handles. Report those explicitly:
try {
await connectToDatabase();
} catch (error) {
jarvis.captureException(error, {
operation: "database.connect"
});
// Continue with the application's normal error handling.
}You can also send a message:
jarvis.captureMessage("Cache warmed", "INFO", {
attributes: { component: "cache" }
});Flush and shutdown
await jarvis.flush();
await jarvis.shutdown();shutdown() restores wrapped console/stream methods and removes J.A.R.V.I.S.
process listeners. It attempts a best-effort flush.
Configuration
| Option | Default | Purpose |
|---|---:|---|
| endpoint | required | HTTP(S) ingestion URL |
| apiKey | required | Bearer token for ingestion |
| projectId | required | J.A.R.V.I.S. project identifier |
| serviceId | required | Service identifier within the project |
| repository | null | Repository identifier |
| environment | development | Environment label |
| instanceId | hostname + PID | Runtime instance identifier |
| queueSize | 5000 | Maximum in-memory queued events |
| batchSize | 50 | Events per request |
| flushInterval | 2000 ms | Periodic flush interval |
| requestTimeout | 5000 ms | HTTP request timeout |
| maxRetries | 3 | Retry count for transient failures |
| captureConsole | true | Wrap console methods |
| captureStdout | true | Capture stdout lines |
| captureStderr | true | Capture stderr lines |
| captureUncaughtExceptions | true | Install uncaughtExceptionMonitor |
| captureUnhandledRejections | true | Install unhandledRejection |
| captureWorkerErrors | true | Monitor worker-thread errors |
Event format
The SDK emits the shared J.A.R.V.I.S. event structure:
schema_version,event_id,timestamp,typeapplication: project, service, repository, environment, instance, runtimedetails: severity, message, error type, stack trace, sourceexecution: trace ID, span ID, request ID, thread nameattributes: capture mechanism and additional metadata
type is log or error. Severity is independent (DEBUG, INFO,
WARNING, ERROR, CRITICAL). The ingestion request body is
{ "events": [ ... ] }.
Important implementation notes
This is a hackathon MVP / starter implementation, not a production-hardened SDK.
- Best-effort crash reporting:
uncaughtExceptionMonitorruns immediately before Node's normal uncaught-exception handling. The process may exit before queued telemetry is delivered. The SDK makes a best-effort flush, but an in-memory queue cannot guarantee delivery. - No lifecycle interference: The SDK uses
uncaughtExceptionMonitor, notuncaughtException, so it does not install a handler that suppresses Node's default crash behaviour. - Duplicate observations:
console.error()commonly writes to stderr. Capturing both console methods and stderr can create duplicate events. This MVP does not implement robust deduplication. - Worker monitoring: Worker errors are observed through the Worker prototype hook for workers created after initialization. Prefer explicit per-worker instrumentation in a production version.
- Caught errors: No global hook can capture every caught exception. Use
captureException()or framework-specific instrumentation. - Queue durability: The queue is in memory. Events can be lost on abrupt termination, queue overflow, or exhausted retries.
droppedEventsis an internal counter and is not yet exposed. - Redaction: Basic pattern-based redaction is only a safeguard, not a guarantee. Avoid logging secrets and add configurable scrubbing before production use.
- Runtime scope: This package targets Node.js. Browser support requires a separate browser entry point using
window.onerror,unhandledrejection, and browser console instrumentation; Node'sprocesshooks do not apply in browsers. - Privacy: Logs and stack traces can contain personal data, tokens, or internal paths. Obtain appropriate consent, configure filtering, and define retention policies.
Suggested next hardening steps
- Add reliable deduplication across console and stream capture.
- Add durable disk buffering or a bounded retry/requeue strategy.
- Expose dropped-event and delivery metrics.
- Add framework integrations (Express/Fastify/NestJS) and request context propagation.
- Add browser SDK as a separate package entry point.
- Add tests for capture, restoration, batching, retry, shutdown, and redaction.
