Merge pull request #2663 from ankaboot-source/fix/standardize-edge-function-logging

refactor: standardize Edge Function logging with structured JSON logger

Author: baderdean

AGENTS.md

@@ -185,6 +185,47 @@ try {
 - Include context (user ID, operation) in log messages
 - Use appropriate levels: `error`, `warn`, `info`, `debug`
 
+### Edge Function Logging (Deno)
+
+**Use the shared structured logger instead of raw console.log:**
+
+```typescript
+import { createLogger } from "../_shared/logger.ts";
+
+const logger = createLogger("service-name");
+
+// Structured JSON logging with context
+logger.debug("Debug information", { userId: "123" });
+logger.info("Operation completed", { userId: "123", duration: 150 });
+logger.warn("Unexpected state", { details: context });
+logger.error("Operation failed", { error: error.message });
+```
+
+**Best Practices:**
+
+- Output structured JSON for log aggregators (CloudWatch, Datadog)
+- Control verbosity with `LOG_LEVEL` environment variable
+- Use English only for developer/operator logs (not user-facing)
+- Always include relevant context (user ID, operation, IDs)
+- Never log sensitive data (passwords, tokens, PII)
+- Use appropriate levels:
+  - `debug`: Development-only, detailed troubleshooting
+  - `info`: Operational events (token refresh, email sent)
+  - `warn`: Recoverable issues, unexpected states
+  - `error`: Failures requiring attention
+
+**Example Output:**
+
+```json
+{
+  "timestamp": "2026-03-02T14:30:00.000Z",
+  "service": "email-campaigns",
+  "level": "info",
+  "message": "OAuth token refreshed",
+  "email": "user@example.com"
+}
+```
+
 ### Testing
 
 - **Jest** for backend and emails-fetcher
@@ -223,3 +264,24 @@ try {
 - Node.js >= 20.0.0 required
 - Bun >= 1.1.0 required for emails-fetcher
 - Docker and Docker Compose required for local dev
+
+## Planning Documents
+
+### docs/plans Directory
+
+The `docs/plans/` directory contains local planning documents and implementation notes created during development. These files:
+
+- **Should NOT be pushed to the remote repository**
+- Are meant for local development reference only
+- Help track implementation details and decisions
+
+If you create plan documents in `docs/plans/`, they should remain local to your machine and not be shared with the team through git.
+
+### Creating Plan Documents
+
+When creating implementation plans:
+
+1. Save them to `docs/plans/YYYY-MM-DD-<feature-name>.md`
+2. Keep them local - do not commit to git
+3. Use them for local reference during development
+4. Delete them once the feature is complete if desired

supabase/functions/_shared/logger.ts

@@ -1,26 +1,85 @@
-const getCurrentDate = () => {
-  const date = new Date();
-  const day = date.getDate();
+/**
+ * Structured logger for Supabase Edge Functions
+ *
+ * Deno best practices:
+ * - Output structured JSON for log aggregators (CloudWatch, Datadog, etc.)
+ * - Use LOG_LEVEL environment variable to control verbosity
+ * - Consistent ISO 8601 timestamps (UTC)
+ * - English only for developer/operator logs
+ * - Include service name for tracing
+ */
 
-  const month = date.getMonth() + 1;
+export type LogLevel = "debug" | "info" | "warn" | "error";
 
-  const year = date.getFullYear();
+export interface LogContext {
+  [key: string]: unknown;
+}
 
-  return `[${year}-${month}-${day} ${new Date(date).toLocaleTimeString()}]`;
+const LOG_LEVELS: Record<LogLevel, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
 };
 
-const Logger = {
-  error: (message: string) => {
-    console.error(
-      `${getCurrentDate()} %c${message}`,
-      "color: red",
-    );
-  },
-  info: (message: string) => {
-    console.log(
-      `${getCurrentDate()} ${message}`,
-    );
-  },
-};
+function getLogLevel(): LogLevel {
+  const envLevel = Deno.env.get("LOG_LEVEL")?.toLowerCase() as LogLevel;
+  if (envLevel && envLevel in LOG_LEVELS) {
+    return envLevel;
+  }
+  // Default to info in production, debug in development
+  return Deno.env.get("DENO_ENV") === "development" ? "debug" : "info";
+}
+
+function shouldLog(level: LogLevel): boolean {
+  return LOG_LEVELS[level] >= LOG_LEVELS[getLogLevel()];
+}
+
+export function createLogger(service: string) {
+  function log(level: LogLevel, message: string, context?: LogContext): void {
+    if (!shouldLog(level)) {
+      return;
+    }
+
+    const entry = {
+      timestamp: new Date().toISOString(),
+      service,
+      level,
+      message,
+      ...context,
+    };
+
+    const output = JSON.stringify(entry);
+
+    switch (level) {
+      case "error":
+        console.error(output);
+        break;
+      case "warn":
+        console.warn(output);
+        break;
+      case "debug":
+        console.debug(output);
+        break;
+      default:
+        console.log(output);
+    }
+  }
+
+  return {
+    debug: (message: string, context?: LogContext) =>
+      log("debug", message, context),
+    info: (message: string, context?: LogContext) =>
+      log("info", message, context),
+    warn: (message: string, context?: LogContext) =>
+      log("warn", message, context),
+    error: (message: string, context?: LogContext) =>
+      log("error", message, context),
+  };
+}
+
+export type Logger = ReturnType<typeof createLogger>;
 
-export default Logger;
+// Default logger instance for simple imports
+const defaultLogger = createLogger("edge-function");
+export default defaultLogger;