@vantatrace/sdk 0.1.1 → 0.1.2

package/README.md

@@ -1,50 +1,75 @@
-# VantaTrace Node.js SDK
+# 🚀 VantaTrace Node.js SDK
 
-VantaTrace SDK is a lightweight, zero-overhead exception tracking and telemetry client for server-side Node.js applications and Express.js APIs. It intercepts uncaught errors, captures unhandled promise rejections, gathers host/runtime contexts, and streams normalized telemetry payloads asynchronously to your VantaTrace central ingestion server.
+**VantaTrace** is a lightweight, high-performance observability SDK for
+Node.js microservices and Express.js APIs.
 
-## Installation
+It provides real-time **exception tracking, structured telemetry, and
+runtime context capture**, enabling developers to detect, group, and
+debug production issues with minimal overhead.
 
-Install the client package via npm:
-```bash
+Designed for modern distributed systems, VantaTrace runs fully
+asynchronously and never blocks your application runtime.
+
+------------------------------------------------------------------------
+
+## ✨ Key Features
+
+-   ⚡ Zero-blocking architecture --- async ingestion pipeline\
+-   🧠 Smart error grouping (fingerprinting) --- deduplicates identical
+    failures\
+-   🔍 Rich runtime context --- request, system, and environment
+    metadata\
+-   🔒 Secure by default --- automatic redaction of sensitive data\
+-   🌐 Multi-service support --- built for microservices architecture\
+-   📊 Structured telemetry --- normalized event payloads\
+-   🧩 Express.js integration --- plug-and-play middleware
+
+------------------------------------------------------------------------
+
+## 📦 Installation
+
+``` bash
 npm install @vantatrace/sdk
 ```
 
-## Quick Start
+------------------------------------------------------------------------
 
-### 1. Initialization
-Initialize the VantaTrace client at the top of your application entrypoint:
+## ⚡ Quick Start
 
-```javascript
+### 1. Initialize SDK
+
+``` javascript
 import { VantaTrace } from '@vantatrace/sdk';
 
 const vantaTrace = new VantaTrace({
-  apiKey: 'YOUR_PROJECT_API_KEY', // Obtain from VantaTrace Admin Console
-  serviceName: 'order-service',    // Name of your microservice
-  environment: 'live',             // 'live' or 'test'. Auto-inferred from API key prefix if   debug: false                     // Set to true to print SDK internal diagnostics
+  apiKey: 'YOUR_PROJECT_API_KEY',
+  serviceName: 'order-service',
+  environment: 'production',
+  debug: false
 });
 ```
 
-### 2. Auto-capture Global Exceptions
-To automatically intercept uncaught exceptions and unhandled promise rejections before the Node process exits:
+------------------------------------------------------------------------
+
+### 2. Enable Global Error Tracking
 
-```javascript
+``` javascript
 vantaTrace.initGlobalHandlers();
 ```
 
-### 3. Express.js Error Handler Middleware
-To log exceptions raised in Express request handlers and routes, mount the middleware at the bottom of your route definitions:
+------------------------------------------------------------------------
+
+### 3. Express Middleware Integration
 
-```javascript
+``` javascript
 import express from 'express';
+
 const app = express();
 
-// ... Define routes and controller endpoints ...
-app.get('/checkout', (req, res) => {
+app.get('/checkout', () => {
   throw new Error('Payment gateway timeout');
 });
 
-// The VantaTrace middleware MUST be registered after all route definitions,
-// but before other custom express error handling middlewares:
 app.use(vantaTrace.expressMiddleware());
 
 app.use((err, req, res, next) => {
@@ -52,46 +77,61 @@ app.use((err, req, res, next) => {
 });
 ```
 
-### 4. Manual Exception Capturing
-To manually trace handled exceptions, assign custom contextual parameters, or specify severity:
+------------------------------------------------------------------------
+
+### 4. Manual Error Capturing
 
-```javascript
+``` javascript
 try {
-  // perform some actions
+  await processOrder();
 } catch (error) {
   vantaTrace.captureException(error, {
     userId: 'user_8872',
     route: '/api/v1/orders',
     method: 'POST',
-    severity: 'warning', // optional: 'critical', 'warning', or 'info'
+    severity: 'warning',
     metadata: {
       orderId: 'ord_128d9a',
-      amount: 149.50
+      amount: 149.5
     }
   });
 }
 ```
 
-#### Severity Shortcuts
-You can also use dedicated helper methods to automatically assign severity:
+------------------------------------------------------------------------
 
-```javascript
-// Capture a critical system failure
-vantaTrace.captureCritical(error, { userId: 'user_8872' });
+## ⚙️ Severity Levels
 
-// Capture a warning
+``` javascript
+vantaTrace.captureCritical(error);
 vantaTrace.captureWarning(error);
-
-// Capture general information / handled failures
 vantaTrace.captureInfo(error);
 ```
 
-## Features
+------------------------------------------------------------------------
+
+## 🧠 How It Works
+
+Application Error → SDK Capture → Context Enrichment → Fingerprinting →
+Async Queue → Ingestion API → Dashboard
+
+------------------------------------------------------------------------
+
+## 🔒 Security
+
+Sensitive fields are automatically redacted: password, token,
+authorization, cookie, x-api-key
+
+------------------------------------------------------------------------
+
+## ⚡ Performance
+
+-   \<1ms overhead
+-   Async non-blocking execution
+-   Batched ingestion
+
+------------------------------------------------------------------------
+
+## 📊 Architecture
 
-- **Reference Normalization**: Safe serialization of deep call stacks, native errors, and custom properties.
-- **Asynchronous Delivery**: Telemetry reporting runs asynchronously to ensure it never blocks thread execution or delays HTTP responses.
-- **Auto-Redaction**: Middleware automatically filters out sensitive body parameters (`password`, `token`) and HTTP header keys (`Cookie`, `Authorization`, `x-api-key`) from collected logs.
-- **Host & System Telemetry**: Captures host platform hostname, Node runtime version, PID, CPU architecture, platform type, CPU load averages (`loadavg`), and process uptime automatically.
-- **Memory Tracking**: Auto-captures heap totals, heap usage, external memory footprint, and system-wide free/total RAM during exception triggers.
-- **Error Attributes Extraction**: Captures standard error code fields (`err.code`), HTTP statuses (`err.status`/`err.statusCode`), and any custom enumerable metadata attached to the exception.
-- **Request Context Enrichment**: Express middleware captures client IP address and sanitized headers to assist debugging.
+Microservice → SDK → Ingestion API → Fingerprinting Engine → Dashboard

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vantatrace/sdk",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Drop-in observability SDK for Node.js microservices powering error tracking, structured logging, and real-time telemetry pipelines.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",