@gromo-fintech/central-utility-service

Shared observability library for Gromo backend services. Provides Sentry error tracking with built-in PII redaction, signal quality control, and framework adapters for NestJS, Express, and Fastify.

Installation

npm install @gromo-fintech/central-utility-service

Quick Start

NestJS

// main.ts — before NestFactory.create()
import { initObservability } from '@gromo-fintech/central-utility-service';

initObservability({
  service: 'gromo-loan-service',
  framework: 'nestjs',
});

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  // ...
}

// app.module.ts
import { ObservabilityModule } from '@gromo-fintech/central-utility-service';

@Module({
  imports: [
    ObservabilityModule.forRoot({ service: 'gromo-loan-service' }),
  ],
})
export class AppModule {}

Express

const { initObservability, sentryErrorMiddleware } = require('@gromo-fintech/central-utility-service');

initObservability({ service: 'notification-wrapper', framework: 'express' });

const app = express();
// ... routes ...
app.use(sentryErrorMiddleware()); // after routes, before your error response middleware
app.use(yourExistingErrorMiddleware);

Fastify

const { initObservability, sentryFastifyErrorHandler } = require('@gromo-fintech/central-utility-service');

initObservability({ service: 'gromoappbackend', framework: 'fastify' });

const sentryHandler = sentryFastifyErrorHandler();
fastify.addHook('onError', (request, reply, error, done) => {
  sentryHandler(error, request, reply);
  done();
});

Clustered Services

For services that use Node.js clustering, initialize only in the worker process:

if (cluster.isWorker) {
  initObservability({ service: 'gromo-recommendation-service', framework: 'nestjs' });
}

Environment Variables

| Variable | Required | Description | Default | |---|---|---|---| | SENTRY_DSN | Yes | Sentry project DSN URL | — | | SENTRY_ENABLED | Yes | true / 1 / yes / on to enable | false | | SENTRY_ENVIRONMENT | No | staging / production | NODE_ENV | | SENTRY_RELEASE | No | Git SHA or version tag | — | | SENTRY_TRACES_SAMPLE_RATE | No | 0.0–1.0 (% of requests to trace) | 0 | | SENTRY_PROFILES_SAMPLE_RATE | No | 0.0–1.0 (% of traces to profile) | 0 |

Configuration Options

initObservability({
  service: 'my-service',              // required — tags every event
  framework: 'nestjs',                // 'nestjs' | 'express' | 'fastify'
  healthCheckPaths: ['/deep-health'], // paths to exclude (default: ['/deep-health'])
  additionalSensitiveKeys: /myField/i,// merged with default PII regex
  additionalAllowedHeaders: ['x-custom'],// merged with default header allowlist
  beforeSendHook: (event) => event,   // custom hook after library's beforeSend
  sentryOptions: {                    // pass-through to Sentry.init()
    skipOpenTelemetrySetup: true,     // e.g. when service has its own OTEL
  },
});

What It Does

Captures (actionable errors only)

• Unexpected 5xx server errors
• Unhandled promise rejections
• Uncaught exceptions
• Third-party integration failures

Skips (expected behaviour — no noise)

• Validation errors (400)
• Authentication failures (401, 403)
• Not found (404)
• Health check paths
• Business domain errors

PII Redaction (automatic)

• Keys matching pan, aadhaar, account, ifsc, mobile, phone, email, token, authorization, cookie, password, secret, otp, cvv, dob, ssn → [REDACTED]
• Query strings stripped from URLs
• Only safe headers forwarded: content-type, user-agent, x-request-id, x-correlation-id, x-forwarded-for, gpuid

Context Tags (on every event)

• service — which repo/service
• request_method — GET/POST/etc
• request_url — sanitized path
• correlation_id — from x-correlation-id header
• user_id — from gpuid header
• process_event — unhandledRejection or uncaughtException (for process-level errors)

API Reference

| Export | Type | Description | |---|---|---| | initObservability(config) | Function | Initialize Sentry with full config. Call once at boot. | | ObservabilityModule.forRoot(config) | NestJS Module | Registers SentryExceptionFilter as global APP_FILTER. | | sentryErrorMiddleware() | Express Middleware | Error middleware that captures 5xx to Sentry. | | sentryFastifyErrorHandler() | Fastify Handler | Error handler that captures unexpected errors to Sentry. | | SentryExceptionFilter | NestJS Filter | Catch-all exception filter (used by ObservabilityModule). | | shouldEnableSentry() | Function | Check if Sentry is enabled (DSN + flag). | | redactSensitiveKeys(value, regex) | Function | Recursively redact object keys matching regex. | | sanitizeUrl(url) | Function | Strip query string from URL. |