RFC-006: Logging and Monitoring Implementation

Overview

Technical implementation plan for observability infrastructure covering logging, error tracking, and metrics.

Implementation Details

1. Sentry Integration

// Frontend (Next.js)
import * as Sentry from "@sentry/nextjs";

Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
  environment: process.env.NODE_ENV,
  integrations: [Sentry.replayIntegration()],
  tracesSampleRate: 1.0,
  replaysSessionSampleRate: 0.1,
});

// Usage with context
Sentry.captureException(error, {
  extra: {
    tenant_id: session.tenant_id,
    session_id: session.id,
    payment_id: transaction.id,
  },
});

2. Structured Logging (Backend)

// Logger utility
interface Logger {
  error(message: string, context: LogContext): void;
  warn(message: string, context: LogContext): void;
  info(message: string, context: LogContext): void;
  debug(message: string, context: LogContext): void;
}

// Usage
logger.info("Payment initiated", {
  tenant_id: tenant.id,
  transaction_id: transaction.id,
  amount: transaction.amount,
});

3. Grafana Dashboard Panels

4. Alert Rules

Alert	Condition	Channel
High Error Rate	>5% errors in 5min	Slack
Payment Failed	Any payment failure	Slack + Email
Printer Offline	No heartbeat in 10min	Slack
API Slow	p95 > 2s	Slack

API Endpoint Logging

// Middleware example
app.use((req, res, next) => {
  const start = Date.now();

  res.on("finish", () => {
    logger.info("API Request", {
      method: req.method,
      path: req.path,
      status: res.statusCode,
      duration: Date.now() - start,
      tenant_id: req.tenant?.id,
    });
  });

  next();
});

Log Retention

Log Type	Retention	Storage
Error logs	90 days	Grafana Cloud
Access logs	30 days	Grafana Cloud
Payment logs	1 year	Grafana Cloud (separate)

Implementation Phases

1. Phase 1: Sentry setup + basic error capture
2. Phase 2: Structured logging in backend
3. Phase 3: OpenTelemetry + Grafana dashboards
4. Phase 4: Alert configuration

Related Files

• ADR-009: ADR-009-logging-monitoring.md