Improve structured logging across SDK and container

.changeset/logging-wide-events.md

@@ -0,0 +1,5 @@
+---
+'@cloudflare/sandbox': patch
+---
+
+Structured logging for Workers Observability and Containers Logs. All operations emit queryable fields (`event`, `outcome`, `durationMs`, `command`, `exitCode`, `sessionId`) that can be filtered and aggregated in the dashboard. Presigned R2 URL parameters and embedded git URL credentials are redacted from all log fields. Set `SANDBOX_LOG_FORMAT=pretty` for readable local dev output.

packages/sandbox-container/src/core/container.ts

@@ -120,11 +120,7 @@ export class Container {
       sessionManager
     );
     const portService = new PortService(portStore, securityAdapter, logger);
-    const gitService = new GitService(
-      securityAdapter,
-      gitLogger,
-      sessionManager
-    );
+    const gitService = new GitService(securityAdapter, sessionManager, gitLogger);
     const interpreterService = new InterpreterService(logger);
     const backupService = new BackupService(logger, sessionManager);
     const desktopService = new DesktopService(logger);

packages/sandbox-container/src/core/router.ts

@@ -67,6 +67,7 @@ export class Router {
     // Create request context
     const context: RequestContext = {
       sessionId: this.extractSessionId(request),
+      sandboxId: request.headers.get('X-Sandbox-Id') ?? undefined,
       corsHeaders: this.getCorsHeaders(),
       requestId: this.generateRequestId(),
       timestamp: new Date()
@@ -204,7 +205,7 @@ export class Router {
   private getCorsHeaders(): Record<string, string> {
     return {
       'Access-Control-Allow-Headers':
-        'Content-Type, Authorization, X-Session-Id',
+        'Content-Type, Authorization, X-Session-Id, X-Sandbox-Id, X-Trace-Id',
       'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
       'Access-Control-Allow-Origin': '*'
     };

packages/sandbox-container/src/core/types.ts

@@ -6,6 +6,7 @@ export interface Handler<TRequest, TResponse> {
 
 export interface RequestContext {
   sessionId?: string;
+  sandboxId?: string;
   corsHeaders: Record<string, string>;
   requestId: string;
   timestamp: Date;
@@ -278,6 +279,7 @@ export interface ProcessOptions {
   cwd?: string;
   encoding?: string;
   autoCleanup?: boolean;
+  origin?: 'user' | 'internal';
 }
 
 export interface CommandResult {

packages/sandbox-container/src/handlers/execute-handler.ts

@@ -55,7 +55,8 @@ export class ExecuteHandler extends BaseHandler<Request, Response> {
           sessionId,
           timeoutMs: body.timeoutMs,
           env: body.env,
-          cwd: body.cwd
+          cwd: body.cwd,
+          origin: body.origin
         }
       );
 
@@ -81,7 +82,8 @@ export class ExecuteHandler extends BaseHandler<Request, Response> {
       sessionId,
       timeoutMs: body.timeoutMs,
       env: body.env,
-      cwd: body.cwd
+      cwd: body.cwd,
+      origin: body.origin
     });
 
     if (!result.success) {
@@ -116,7 +118,8 @@ export class ExecuteHandler extends BaseHandler<Request, Response> {
     const processResult = await this.processService.startProcess(body.command, {
       sessionId,
       env: body.env,
-      cwd: body.cwd
+      cwd: body.cwd,
+      origin: body.origin
     });
 
     if (!processResult.success) {

packages/sandbox-container/src/handlers/git-handler.ts

@@ -61,13 +61,6 @@ export class GitHandler extends BaseHandler<Request, Response> {
 
       return this.createTypedResponse(response, context);
     } else {
-      this.logger.error('Repository clone failed', undefined, {
-        requestId: context.requestId,
-        repoUrl: body.repoUrl,
-        errorCode: result.error.code,
-        errorMessage: result.error.message
-      });
-
       return this.createErrorResponse(result.error, context);
     }
   }

packages/sandbox-container/src/handlers/pty-ws-handler.ts

@@ -33,8 +33,7 @@ export class PtyWebSocketHandler {
 
   async onOpen(ws: ServerWebSocket<PtyWSData>): Promise<void> {
     const { sessionId, connectionId, cols, rows, shell } = ws.data;
-
-    this.logger.debug('PTY WebSocket opened', { sessionId, connectionId });
+    // Lifecycle captured in onClose canonical log line
 
     const result = await this.sessionManager.getPty(sessionId, {
       cols,
@@ -82,7 +81,10 @@ export class PtyWebSocketHandler {
     const conn = this.connections.get(connectionId);
 
     if (!conn) {
-      this.logger.warn('Message for unknown PTY connection', { connectionId });
+      this.logger.warn('pty.message', {
+        connectionId,
+        outcome: 'unknown_connection'
+      });
       return;
     }
 
@@ -96,11 +98,12 @@ export class PtyWebSocketHandler {
   onClose(ws: ServerWebSocket<PtyWSData>, code: number, reason: string): void {
     const { connectionId, sessionId } = ws.data;
 
-    this.logger.debug('PTY WebSocket closed', {
+    this.logger.debug('pty.connection', {
       sessionId,
       connectionId,
       code,
-      reason
+      reason,
+      outcome: 'closed'
     });
 
     const conn = this.connections.get(connectionId);
@@ -112,7 +115,7 @@ export class PtyWebSocketHandler {
 
   onDrain(ws: ServerWebSocket<PtyWSData>): void {
     const { connectionId } = ws.data;
-    this.logger.debug('PTY WebSocket drained', { connectionId });
+    this.logger.debug('pty.drain', { connectionId });
   }
 
   private sendPtyData(
@@ -123,7 +126,7 @@ export class PtyWebSocketHandler {
     const result = ws.sendBinary(data);
 
     if (result === 0) {
-      this.logger.debug('PTY send failed - connection dead', { connectionId });
+      this.logger.debug('pty.send', { connectionId, outcome: 'dead' });
       const conn = this.connections.get(connectionId);
       if (conn) {
         conn.subscription.dispose();
@@ -150,10 +153,17 @@ export class PtyWebSocketHandler {
         }
         pty.resize(control.cols, control.rows);
       } else {
-        this.logger.warn('Unknown PTY control message', { control });
+        this.logger.warn('pty.control', {
+          connectionId: ws.data.connectionId,
+          controlType: control.type,
+          outcome: 'unknown_type'
+        });
       }
     } catch (err) {
-      this.logger.error('Failed to parse PTY control message', err as Error);
+      this.logger.error('pty.control', err as Error, {
+        connectionId: ws.data.connectionId,
+        outcome: 'parse_error'
+      });
       this.sendStatus(ws, {
         type: 'error',
         message: 'Invalid control message'
@@ -168,7 +178,7 @@ export class PtyWebSocketHandler {
     try {
       ws.send(JSON.stringify(status));
     } catch (err) {
-      this.logger.error('Failed to send PTY status', err as Error);
+      this.logger.error('pty.sendStatus', err as Error);
     }
   }
 }

packages/sandbox-container/src/handlers/ws-adapter.ts

@@ -68,21 +68,20 @@ export class WebSocketAdapter {
   /**
    * Handle WebSocket connection open
    */
-  onOpen(ws: ServerWebSocket<WSData>): void {
-    this.logger.debug('WebSocket connection opened', {
-      connectionId: ws.data.connectionId
-    });
+  onOpen(_ws: ServerWebSocket<WSData>): void {
+    // Lifecycle captured in onClose canonical log line
   }
 
   /**
-   * Handle WebSocket connection close
+   * Handle WebSocket connection close — canonical log line for connection lifecycle
    */
   onClose(ws: ServerWebSocket<WSData>, code: number, reason: string): void {
     const connectionId = ws.data.connectionId;
-    this.logger.debug('WebSocket connection closed', {
+    this.logger.debug('ws.connection', {
       connectionId,
       code,
-      reason
+      reason,
+      outcome: 'closed'
     });
 
     for (const [requestId, stream] of this.activeStreams) {
@@ -136,20 +135,18 @@ export class WebSocketAdapter {
 
     const request = parsed as WSRequest;
 
-    this.logger.debug('WebSocket request received', {
-      connectionId: ws.data.connectionId,
-      id: request.id,
-      method: request.method,
-      path: request.path
-    });
-
     try {
       await this.handleRequest(ws, request);
     } catch (error) {
       this.logger.error(
-        'Error handling WebSocket request',
+        'ws.request',
         error instanceof Error ? error : new Error(String(error)),
-        { requestId: request.id }
+        {
+          connectionId: ws.data.connectionId,
+          requestId: request.id,
+          method: request.method,
+          path: request.path
+        }
       );
       this.sendError(
         ws,
@@ -375,9 +372,9 @@ export class WebSocketAdapter {
       }
 
       this.logger.error(
-        'Error reading stream',
+        'ws.stream',
         error instanceof Error ? error : new Error(String(error)),
-        { requestId }
+        { connectionId: ws.data.connectionId, requestId }
       );
       this.sendError(
         ws,
@@ -404,8 +401,9 @@ export class WebSocketAdapter {
       return true;
     } catch (error) {
       this.logger.error(
-        'Failed to send WebSocket message, closing connection',
-        error instanceof Error ? error : new Error(String(error))
+        'ws.send',
+        error instanceof Error ? error : new Error(String(error)),
+        { connectionId: ws.data.connectionId }
       );
       try {
         ws.close(1011, 'Send failed'); // 1011 = unexpected condition