Overhaul logging and adopt LogTape (#562)

Replaces the previous logging implementation with LogTape for structured
logging across the MCP server and Cloudflare Workers. This provides
consistent JSON-formatted logs with Sentry integration for monitoring.

- **Adopted LogTape**: Structured logging library with dual sinks
  - Console sink outputs JSON Lines format for log aggregation
  - Sentry sink sends logs directly to Sentry for monitoring
  
- **Four clear logging functions**:
- `logInfo()` - Routine telemetry (connection lifecycle, tool
invocations)
  - `logWarn()` - Operational warnings (rate limits, deprecated usage)
  - `logError()` - Operational errors that are handled gracefully
  - `logIssue()` - System errors that create Sentry Issues
  
- **Environment-based configuration**: `LOG_LEVEL` env var or `NODE_ENV`
fallback (debug in development, info in production)
  
- **HTTP request logging**: Cloudflare middleware automatically logs all
requests with status and duration

Co-Authored-By: Claude Code <noreply@anthropic.com>

Author: dcramer

docs/error-handling.mdc

@@ -195,7 +195,7 @@ return agentTool({
 - Don't wrap API calls in try/catch unless adding value
 - Don't use `withApiErrorHandling` anymore (deprecated)
 - Don't use the old `wrapAgentToolExecute` function (use `agentTool` instead)
-- Don't use `logError()` for expected API errors (4xx)
+- Don't use `logIssue()` for expected API errors (4xx)
 - Don't use `captureException()` for UserInputError or ApiClientError
 - Don't create Sentry issues for user-facing errors
 - **SECURITY: NEVER pass untrusted error messages to AI agents - risk of prompt injection**
@@ -324,4 +324,4 @@ When testing tools, verify:
 3. 5xx errors are captured by Sentry with Event IDs  
 4. Network errors bubble up appropriately
 5. UserInputErrors have clear, actionable messages
-6. ApiClientError in agent tools returns formatted markdown with "**Input Error**" header
+6. ApiClientError in agent tools returns formatted markdown with "**Input Error**" header

docs/logging.mdc

@@ -0,0 +1,131 @@
+---
+description: Logging reference using LogTape and Sentry
+---
+# Logging Reference
+
+How logging works in the Sentry MCP server using LogTape and Sentry. For tracing, spans, or metrics see @docs/monitoring.mdc.
+
+## Overview
+
+We use [LogTape](https://logtape.org/) for structured logging with two sinks:
+- **Console sink**: JSON Lines format for log aggregation
+- **Sentry sink**: Sends logs to Sentry for monitoring
+
+Log levels are controlled by:
+1. `LOG_LEVEL` environment variable (e.g., `"debug"`, `"info"`, `"warning"`, `"error"`)
+2. Falls back to `NODE_ENV`: `"debug"` in development, `"info"` in production
+
+Implementation: @packages/mcp-server/src/logging.ts
+
+## Using the Log Helpers
+
+### logInfo() - Routine telemetry
+```typescript
+import { logInfo } from "@sentry/mcp-server/logging";
+
+logInfo("MCP server started", {
+  loggerScope: ["server", "lifecycle"],
+  extra: { port: 3000 }
+});
+```
+
+### logWarn() - Operational warnings
+```typescript
+import { logWarn } from "@sentry/mcp-server/logging";
+
+logWarn("Rate limit approaching", {
+  loggerScope: ["api", "rate-limit"],
+  extra: { remaining: 10, limit: 100 }
+});
+```
+
+### logError() - Operational errors (no Sentry issue)
+```typescript
+import { logError } from "@sentry/mcp-server/logging";
+
+logError(error, {
+  loggerScope: ["tools", "fetch-trace"],
+  extra: { traceId: "abc123" }
+});
+```
+
+### logIssue() - System errors (creates Sentry issue)
+```typescript
+import { logIssue } from "@sentry/mcp-server/logging";
+
+const eventId = logIssue(error, {
+  loggerScope: ["oauth", "token-refresh"],
+  contexts: {
+    oauth: { client_id: "..." }
+  }
+});
+```
+
+## When to Use Each Helper
+
+**Use `logIssue()` for:**
+- System errors (5xx, network failures, unexpected exceptions)
+- Critical failures that need investigation
+- Creates a Sentry Issue + emits a log entry with Event ID
+
+**Use `logError()` for:**
+- Expected operational errors (trace fetch failed, encoding error)
+- Errors that are handled gracefully
+- Sends to Sentry Logs only (no Issue created)
+
+**Use `logWarn()` for:**
+- Rate limit approaching
+- Deprecated API usage
+- Configuration warnings
+
+**Use `logInfo()` for:**
+- Request lifecycle (connection established, tool invoked)
+- Configuration output
+- Routine telemetry
+
+**Skip logging:**
+- `UserInputError` - Expected validation failures
+- 4xx API responses - Client errors (except 429 rate limits)
+- See @docs/error-handling.mdc for complete rules
+
+## Log Options
+
+All helpers accept:
+
+```typescript
+interface LogOptions {
+  loggerScope?: string | readonly string[];  // e.g., ["cloudflare", "oauth"]
+  extra?: Record<string, unknown>;           // Additional context
+  contexts?: Record<string, Record<string, unknown>>;  // Sentry contexts
+}
+```
+
+`logIssue()` also accepts `attachments` for files to attach to the Sentry event.
+
+## Configuration
+
+**Environment Variables:**
+- `LOG_LEVEL` - Override log level (`"debug"`, `"info"`, `"warning"`, `"error"`)
+- `NODE_ENV` - Determines default level (`"development"` = debug, else info)
+
+**Sinks:**
+- Console: JSON Lines format for log aggregation
+- Sentry: Sends logs to Sentry for monitoring (uses `Sentry.init` config)
+
+## HTTP Request Logging
+
+Cloudflare middleware logs all HTTP requests automatically:
+
+```typescript
+// Middleware in packages/mcp-cloudflare/src/server/logging.ts
+app.use(createRequestLogger(["cloudflare", "http"]));
+
+// Logs: {"level":"INFO","message":"GET /api/search","properties":{"status":200,"duration_ms":42}}
+```
+
+## References
+
+- Implementation: @packages/mcp-server/src/logging.ts
+- Error handling patterns: @docs/error-handling.mdc
+- Monitoring and tracing: @docs/monitoring.mdc
+- LogTape docs: https://logtape.org/

docs/monitoring.mdc

@@ -19,30 +19,7 @@ Different Sentry SDKs for different environments:
 
 ### Error Logging
 
-```typescript
-import { captureException, withScope } from "@sentry/core";
-
-export function logError(
-  error: Error | unknown,
-  contexts?: Record<string, any>,
-  attachments?: Record<string, any>
-): string | undefined {
-  // Skip UserInputErrors - these are expected
-  if (error instanceof UserInputError) {
-    return;
-  }
-
-  return withScope((scope) => {
-    if (contexts) scope.setContext("mcp", contexts);
-    if (attachments) {
-      for (const [key, data] of Object.entries(attachments)) {
-        scope.addAttachment({ data, filename: key });
-      }
-    }
-    return captureException(error);
-  });
-}
-```
+See `logIssue` in @packages/mcp-server/src/logging.ts (documented in @docs/logging.mdc) for the canonical way to create an Issue and structured log entry.
 
 ### Tracing Pattern
 

packages/mcp-cloudflare/src/server/app.ts

@@ -8,22 +8,22 @@ import chatOauth from "./routes/chat-oauth";
 import chat from "./routes/chat";
 import search from "./routes/search";
 import metadata from "./routes/metadata";
-import { logError } from "@sentry/mcp-server/logging";
+import { logIssue } from "@sentry/mcp-server/logging";
+import { createRequestLogger } from "./logging";
 import mcpRoutes from "./routes/mcp";
 
 const app = new Hono<{
   Bindings: Env;
 }>()
+  .use("*", createRequestLogger())
   // Set user IP address from X-Real-IP header for Sentry
   .use("*", async (c, next) => {
-    // Extract client IP from headers in order of preference
     const clientIP =
       c.req.header("X-Real-IP") ||
       c.req.header("CF-Connecting-IP") ||
       c.req.header("X-Forwarded-For")?.split(",")[0]?.trim();
 
     if (clientIP) {
-      // Set the user context with the correct IP address
       Sentry.setUser({ ip_address: clientIP });
     }
 
@@ -43,12 +43,9 @@ const app = new Hono<{
     "*",
     csrf({
       origin: (origin, c) => {
-        // If no Origin header is present, this cannot be a CSRF attack
-        // (CSRF requires a cross-origin request which always has an Origin header)
         if (!origin) {
           return true;
         }
-        // If Origin is present, verify it matches the request URL's origin
         const requestUrl = new URL(c.req.url);
         return origin === requestUrl.origin;
       },
@@ -78,7 +75,7 @@ const app = new Hono<{
 
 // TODO: propagate the error as sentry isnt injecting into hono
 app.onError((err, c) => {
-  logError(err);
+  logIssue(err);
   return c.text("Internal Server Error", 500);
 });
 

packages/mcp-cloudflare/src/server/lib/approval-dialog.ts

@@ -2,7 +2,7 @@ import type {
   AuthRequest,
   ClientInfo,
 } from "@cloudflare/workers-oauth-provider";
-import { logError } from "@sentry/mcp-server/logging";
+import { logError, logIssue, logWarn } from "@sentry/mcp-server/logging";
 import { sanitizeHtml } from "./html-utils";
 
 const COOKIE_NAME = "mcp-approved-clients";
@@ -71,9 +71,13 @@ async function verifySignature(
       signatureBytes.buffer,
       enc.encode(data),
     );
-  } catch (e) {
-    // Handle errors during hex parsing or verification
-    console.error("Error verifying signature:", e);
+  } catch (error) {
+    logError(error, {
+      loggerScope: ["cloudflare", "approval-dialog"],
+      extra: {
+        message: "Error verifying signature",
+      },
+    });
     return false;
   }
 }
@@ -99,7 +103,9 @@ async function getApprovedClientsFromCookie(
   const parts = cookieValue.split(".");
 
   if (parts.length !== 2) {
-    console.warn("Invalid cookie format received.");
+    logWarn("Invalid approval cookie format", {
+      loggerScope: ["cloudflare", "approval-dialog"],
+    });
     return null; // Invalid format
   }
 
@@ -110,24 +116,30 @@ async function getApprovedClientsFromCookie(
   const isValid = await verifySignature(key, signatureHex, payload);
 
   if (!isValid) {
-    console.warn("Cookie signature verification failed.");
+    logWarn("Approval cookie signature verification failed", {
+      loggerScope: ["cloudflare", "approval-dialog"],
+    });
     return null; // Signature invalid
   }
 
   try {
     const approvedClients = JSON.parse(payload);
     if (!Array.isArray(approvedClients)) {
-      console.warn("Cookie payload is not an array.");
+      logWarn("Approval cookie payload is not an array", {
+        loggerScope: ["cloudflare", "approval-dialog"],
+      });
       return null; // Payload isn't an array
     }
     // Ensure all elements are strings
     if (!approvedClients.every((item) => typeof item === "string")) {
-      console.warn("Cookie payload contains non-string elements.");
+      logWarn("Approval cookie payload contains non-string elements", {
+        loggerScope: ["cloudflare", "approval-dialog"],
+      });
       return null;
     }
     return approvedClients as string[];
   } catch (e) {
-    logError(new Error(`Error parsing cookie payload: ${e}`, { cause: e }));
+    logIssue(new Error(`Error parsing cookie payload: ${e}`, { cause: e }));
     return null; // JSON parsing failed
   }
 }
@@ -190,8 +202,13 @@ function encodeState(data: any): string {
     // Use btoa for simplicity, assuming Worker environment supports it well enough
     // For complex binary data, a Buffer/Uint8Array approach might be better
     return btoa(jsonString);
-  } catch (e) {
-    console.error("Error encoding state:", e);
+  } catch (error) {
+    logError(error, {
+      loggerScope: ["cloudflare", "approval-dialog"],
+      extra: {
+        message: "Error encoding approval dialog state",
+      },
+    });
     throw new Error("Could not encode state");
   }
 }
@@ -205,8 +222,13 @@ function decodeState<T = any>(encoded: string): T {
   try {
     const jsonString = atob(encoded);
     return JSON.parse(jsonString);
-  } catch (e) {
-    console.error("Error decoding state:", e);
+  } catch (error) {
+    logError(error, {
+      loggerScope: ["cloudflare", "approval-dialog"],
+      extra: {
+        message: "Error decoding approval dialog state",
+      },
+    });
     throw new Error("Could not decode state");
   }
 }
@@ -773,11 +795,15 @@ export async function parseRedirectApproval(
     permissions = formData
       .getAll("permission")
       .filter((p): p is string => typeof p === "string");
-  } catch (e) {
-    console.error("Error processing form submission:", e);
-    // Rethrow or handle as appropriate, maybe return a specific error response
+  } catch (error) {
+    logError(error, {
+      loggerScope: ["cloudflare", "approval-dialog"],
+      extra: {
+        message: "Error processing approval form submission",
+      },
+    });
     throw new Error(
-      `Failed to parse approval form: ${e instanceof Error ? e.message : String(e)}`,
+      `Failed to parse approval form: ${error instanceof Error ? error.message : String(error)}`,
     );
   }
 

packages/mcp-cloudflare/src/server/lib/constraint-utils.ts

@@ -1,6 +1,6 @@
 import type { Constraints } from "@sentry/mcp-server/types";
 import { SentryApiService, ApiError } from "@sentry/mcp-server/api-client";
-import { logError } from "@sentry/mcp-server/logging";
+import { logIssue } from "@sentry/mcp-server/logging";
 
 /**
  * Verify that provided org/project constraints exist and the user has access
@@ -58,7 +58,7 @@ export async function verifyConstraintsAccess(
           : error.message;
       return { ok: false, status: error.status, message };
     }
-    const eventId = logError(error);
+    const eventId = logIssue(error);
     return {
       ok: false,
       status: 502,
@@ -85,7 +85,7 @@ export async function verifyConstraintsAccess(
             : error.message;
         return { ok: false, status: error.status, message };
       }
-      const eventId = logError(error);
+      const eventId = logIssue(error);
       return {
         ok: false,
         status: 502,