@zentto/obs

Zentto Observability SDK — Kafka-based structured logging, audit trail, performance metrics, and business events for the Zentto ERP ecosystem.

Install

npm install @zentto/obs

Quick Start

import { createObs } from '@zentto/obs';

const obs = createObs({
  service: 'my-service',
  kafka: {
    enabled: process.env.KAFKA_ENABLED === 'true',
    brokers: (process.env.KAFKA_BROKERS || 'localhost:9092').split(','),
  },
});

// Logging
obs.log('info', 'Server started', { port: 4000 });
obs.log('warn', 'Slow query detected', { query: 'SELECT ...', durationMs: 500 });

// Error tracking
obs.error(new Error('Something failed'), { handler: 'getUsers' });

// Audit trail
obs.audit('user.login', { userId: 1, ip: '1.2.3.4', companyId: 5 });

// Performance metrics
obs.perf('db.query', 150, { query: 'SELECT ...', rows: 42 });

// Business events
obs.event('invoice.created', { companyId: 1, total: 1500 });

// Graceful shutdown
process.on('SIGTERM', async () => {
  await obs.disconnect();
  process.exit(0);
});

Express Middleware

import { createObs, httpMiddleware, auditMiddleware, errorHandlerMiddleware } from '@zentto/obs';

const obs = createObs({ service: 'zentto-api', kafka: { enabled: true } });

// HTTP request logging (place early in middleware chain)
app.use(httpMiddleware(obs));

// Audit trail for write operations (POST/PUT/PATCH/DELETE)
app.use('/v1', auditMiddleware(obs, {
  persistFn: (entry) => saveToDatabase(entry), // optional DB callback
}));

// ... your routes ...

// Error handler (place last)
app.use(errorHandlerMiddleware(obs));

Kafka Topics

Topics are auto-generated from the service name:

| Topic Pattern | Content | |---|---| | zentto-{service}-logs | HTTP requests, general logs | | zentto-{service}-errors | Errors, 5xx responses, stack traces | | zentto-{service}-audit | Audit trail (who did what) | | zentto-{service}-performance | Slow requests, DB queries, metrics | | zentto-{service}-events | Business events (invoices, payments, etc.) |

API Reference

createObs(config): ObsInstance

| Option | Type | Default | Description | |---|---|---|---| | service | string | required | Service name (used in topics and logs) | | kafka.enabled | boolean | false | Enable Kafka producer | | kafka.brokers | string[] | ['localhost:9092'] | Kafka broker addresses | | slowThresholdMs | number | 1000 | Threshold for slow request detection | | businessEvents | Record<string, string> | built-in map | Route-to-event mapping for auto-detection |

ObsInstance Methods

| Method | Description | |---|---| | log(level, message, meta?) | General structured log | | error(error, context?) | Error with stack trace | | audit(action, details) | Audit trail entry | | perf(operation, durationMs, meta?) | Performance metric | | event(eventName, data?) | Business event | | httpRequest(entry) | HTTP request log (used by middleware) | | disconnect() | Graceful Kafka shutdown |

Express Middlewares

| Middleware | Description | |---|---| | httpMiddleware(obs, options?) | Logs all HTTP requests/responses, auto-detects business events | | auditMiddleware(obs, options?) | Audit trail for POST/PUT/PATCH/DELETE, optional DB persist | | errorHandlerMiddleware(obs) | Global error handler with Kafka logging |

Environment Variables

KAFKA_ENABLED=true          # Enable Kafka (default: false, console fallback)
KAFKA_BROKERS=host:9092     # Comma-separated broker list
SERVICE_NAME=my-service     # Override service name

Console Fallback

When KAFKA_ENABLED=false or Kafka is unreachable, all logs fall back to console.log/console.error with structured JSON output. The service never crashes due to Kafka unavailability.

Ecosystem

This SDK is used across the Zentto ERP platform:

| Service | Language | Topics | |---|---|---| | zentto-api | TypeScript/Express | zentto-api-* | | zentto-notify | TypeScript/Express | zentto-notify-* | | zentto-broker | TypeScript/Express | zentto-broker-* | | zentto-cache | TypeScript/Express | zentto-cache-* | | zentto-report | Python/Flask | zentto-report-* (Python port) | | zentto-fiscal-agent | C#/.NET 9 | zentto-fiscal-* (C# port) |

License

MIT