Observability

Logging#

Server-side: @matters/lib/errors/logger — singleton logger with .info, .warn, .error, .debug, and .child(context) for adding default context.

import { logger } from "@/lib/errors/logger";

logger.info("Webinar published", { webinarId, slug });
logger.error("Salesforce push failed", err, { leadEmail });

Behaviour:

• Development — logs to stdout with timestamps, levels, JSON context.
• Production — only info / warn / error logged (debug suppressed).
• Errors marked level: "error" AND not a 4xx AppException subclass get sent to Sentry with scoped tags + context.

Never use console.log in app code. The logger handles client-vs-server detection and respects the Sentry filter (4xx client errors don't bloat the Sentry dashboard).

Errors#

Custom exception classes from @matters/lib/errors/exceptions:

Logger's Sentry filter intentionally drops 4xx client errors — those are expected, not bugs.

Sentry#

• Configured via lib/config/sentry.ts → shouldEnableSentry(). Enabled only when both NODE_ENV=production and the domain is matters.ai (i.e. not preview deployments, not dev).
• sentry.server.config.ts and sentry.edge.config.ts at the repo root initialise the SDK.
• Source maps upload during build when SENTRY_AUTH_TOKEN is set.
• Errors tagged with errorSource: "logger", errorType: <ExceptionClass>, and arbitrary errorCategory from context.
• Use scoped contexts (scope.setContext("logContext", {...})) for structured debugging.

Recommendation: create a second Sentry project for matters-workspace so workspace errors don't drown the public-site signal. Track in PROD_CHECKLIST.md § 3.6.

Audit logs#

MongoDB audit_logs collection, written by auditMutation (@/lib/security/api-guards) and the lower-level logAuditEvent (lib/security/audit.ts).

Schema documented in Security → Audit Log.

Critical event types (auto-alert to console; future: email/Slack) — the full CRITICAL_EVENTS list in lib/security/audit.ts (12 total):

• multiple_failed_logins
• suspicious_activity
• permission_escalation_attempt
• user_role_changed
• super_admin_action
• rate_limit_exceeded
• honeypot_triggered
• low_recaptcha_score
• recaptcha_verification_failed
• access_denied
• resource_not_found
• system_error

Read with getAuditLogs({ userId?, eventType?, startDate?, endDate?, limit?, skip? }).

Metrics#

• Vercel Analytics — auto-instrumented; pageviews + Web Vitals.
• Glossary view counts — Upstash Redis, aggregated by Vercel Cron daily into MongoDB.
• Webinar registrations — MongoDB counters maintained by the registration flow.

No application-layer Prometheus / Grafana stack today. If you need per-route latency or throughput, check Vercel's Logs + Edge metrics tabs.

Traces#

No distributed tracing today. Next.js exposes an experimental clientTraceMetadata option (it would go in next.config.ts → experimental) that emits page-level metadata to Vercel, but it is not configured today — next.config.ts does not set it. If you need cross-service correlation (WordPress ↔ Next.js ↔ MongoDB), the right level to add it is lib/api/wrapper.ts's request-ID logging.

Where to look when something's wrong#