Merge pull request #122 from huggingface/claude/add-ip-session-tracking-01FU71ksN1sabcwQm8UfjWu2

Add IP address tracking to session logs

Author: evalstate

packages/app/src/server/transport/base-transport.ts

@@ -59,6 +59,7 @@ export interface SessionMetadata {
 	};
 	pingFailures?: number;
 	lastPingAttempt?: Date;
+	ipAddress?: string;
 }
 
 /**
@@ -164,6 +165,39 @@ export abstract class BaseTransport {
 		this.metrics.trackNewConnection();
 	}
 
+	/**
+	 * Track an IP address for unique IP metrics
+	 */
+	protected trackIpAddress(ipAddress: string | undefined): void {
+		this.metrics.trackIpAddress(ipAddress);
+	}
+
+	/**
+	 * Extract IP address from request headers
+	 * Handles x-forwarded-for, x-real-ip, and direct IP
+	 */
+	protected extractIpAddress(
+		headers: Record<string, string | string[] | undefined>,
+		directIp?: string
+	): string | undefined {
+		// Try x-forwarded-for first (most reliable for proxied traffic)
+		const forwardedFor = headers['x-forwarded-for'];
+		if (forwardedFor) {
+			// x-forwarded-for can be a comma-separated list, take the first one (original client)
+			const ip = Array.isArray(forwardedFor) ? forwardedFor[0] : forwardedFor;
+			return ip?.split(',')[0]?.trim();
+		}
+
+		// Try x-real-ip (nginx)
+		const realIp = headers['x-real-ip'];
+		if (realIp) {
+			return Array.isArray(realIp) ? realIp[0] : realIp;
+		}
+
+		// Fallback to direct IP (no proxy scenario)
+		return directIp;
+	}
+
 	/**
 	 * Associate a session with a client identity when client info becomes available
 	 */

packages/app/src/server/transport/sse-transport.ts

@@ -78,6 +78,10 @@ export class SseTransport extends StatefulTransport<SSEConnection> {
 			const headers = req.headers as Record<string, string>;
 			extractQueryParamsToHeaders(req, headers);
 
+			// Extract IP address for tracking
+			const ipAddress = this.extractIpAddress(req.headers, req.ip);
+			this.trackIpAddress(ipAddress);
+
 			// Validate auth and track metrics
 			const authResult = await this.validateAuthAndTrackMetrics(headers);
 			if (!authResult.shouldContinue) {
@@ -107,6 +111,7 @@ export class SseTransport extends StatefulTransport<SSEConnection> {
 				isAuthenticated,
 				requestJson: req.body ?? {},
 				capabilities: requestBody?.params?.capabilities,
+				ipAddress,
 			});
 
 			// Create comprehensive cleanup function
@@ -124,6 +129,7 @@ export class SseTransport extends StatefulTransport<SSEConnection> {
 					requestCount: 0,
 					isAuthenticated: authResult.shouldContinue && !!headers['authorization'],
 					capabilities: {},
+					ipAddress,
 				},
 				cleaningUp: false,
 			};

packages/app/src/server/transport/stateless-http-transport.ts

@@ -147,6 +147,11 @@ export class StatelessHttpTransport extends BaseTransport {
 		// Check HF token validity if present
 		const headers = req.headers as Record<string, string>;
 		extractQueryParamsToHeaders(req, headers);
+
+		// Extract IP address for tracking
+		const ipAddress = this.extractIpAddress(req.headers, req.ip);
+		this.trackIpAddress(ipAddress);
+
 		// Extract method name for tracking using shared utility
 		const requestBody = req.body as
 			| { method?: string; params?: { clientInfo?: unknown; capabilities?: unknown; name?: string } }
@@ -168,7 +173,7 @@ export class StatelessHttpTransport extends BaseTransport {
 			if (requestBody?.method === 'initialize') {
 				// Create new session
 				sessionId = randomUUID();
-				this.createAnalyticsSession(sessionId, authResult.userIdentified);
+				this.createAnalyticsSession(sessionId, authResult.userIdentified, ipAddress);
 
 				// Add session ID to response headers
 				res.setHeader('Mcp-Session-Id', sessionId);
@@ -182,6 +187,7 @@ export class StatelessHttpTransport extends BaseTransport {
 					clientVersion: initClientInfo?.version,
 					requestJson: requestBody.params || '{}',
 					capabilities: requestBody?.params?.capabilities,
+					ipAddress,
 				});
 			} else if (sessionId) {
 				// Try to resume existing session
@@ -441,6 +447,7 @@ export class StatelessHttpTransport extends BaseTransport {
 				clientName: analyticsSession?.metadata.clientInfo?.name,
 				clientVersion: analyticsSession?.metadata.clientInfo?.version,
 				requestJson: { method: 'session_delete', sessionId },
+				ipAddress: analyticsSession?.metadata.ipAddress,
 			});
 
 			res.status(200).json({ jsonrpc: '2.0', result: { deleted: true } });
@@ -492,7 +499,7 @@ export class StatelessHttpTransport extends BaseTransport {
 	}
 
 	// Analytics mode methods
-	private createAnalyticsSession(sessionId: string, isAuthenticated: boolean): void {
+	private createAnalyticsSession(sessionId: string, isAuthenticated: boolean, ipAddress?: string): void {
 		const session: AnalyticsSession = {
 			transport: null,
 			server: null, // Server is null in analytics mode
@@ -503,6 +510,7 @@ export class StatelessHttpTransport extends BaseTransport {
 				requestCount: 1,
 				isAuthenticated,
 				capabilities: {},
+				ipAddress,
 			},
 		};
 

packages/app/src/server/utils/query-logger.ts

@@ -266,6 +266,7 @@ export function logSystemEvent(
 		clientVersion?: string;
 		requestJson?: unknown;
 		capabilities?: unknown;
+		ipAddress?: string;
 	}
 ): void {
 	if (!systemLogger) {
@@ -299,6 +300,9 @@ export function logSystemEvent(
 			version: options?.clientVersion || capabilitiesVersion || null,
 			authorized: options?.isAuthenticated ?? false, // renamed from isAuthenticated
 
+			// IP address for session tracking
+			ipAddress: options?.ipAddress || null,
+
 			// Full request data for context
 			capabilities: options?.capabilities ? JSON.stringify(options.capabilities) : null,
 			clientSessionId: options?.clientSessionId || null,

packages/app/src/server/web-server.ts

@@ -319,6 +319,7 @@ export class WebServer {
 						connectionStatus,
 						pingFailures: session.pingFailures || 0,
 						lastPingAttempt: session.lastPingAttempt?.toISOString(),
+						ipAddress: session.ipAddress,
 					};
 				});
 

packages/app/src/shared/transport-metrics.ts

@@ -15,6 +15,7 @@ export interface TransportMetrics {
 		anonymous: number;
 		unauthorized?: number; // 401 errors
 		cleaned?: number; // Only for stateful transports
+		uniqueIps?: number; // Unique IP addresses that have connected
 	};
 
 	// Session lifecycle metrics (only for stateful transports)
@@ -155,6 +156,7 @@ export interface SessionData {
 	connectionStatus?: 'Connected' | 'Distressed' | 'Disconnected';
 	pingFailures?: number;
 	lastPingAttempt?: string; // ISO date string
+	ipAddress?: string;
 }
 
 export interface TransportMetricsResponse {
@@ -415,12 +417,14 @@ export class MetricsCounter {
 	private rollingMinute: RollingWindowCounter;
 	private rollingHour: RollingWindowCounter;
 	private rolling3Hours: RollingWindowCounter;
+	private uniqueIps: Set<string>;
 
 	constructor() {
 		this.metrics = createEmptyMetrics();
 		this.rollingMinute = new RollingWindowCounter(1);
 		this.rollingHour = new RollingWindowCounter(60);
 		this.rolling3Hours = new RollingWindowCounter(180);
+		this.uniqueIps = new Set();
 	}
 
 	/**
@@ -430,15 +434,18 @@ export class MetricsCounter {
 		// Calculate rates (requests per minute) for each window
 		// Note: All values represent "requests per minute" calculated over their respective windows
 		this.metrics.requests.lastMinute = this.rollingMinute.getCount(); // Requests in last 1 minute (already per minute)
-		
+
 		// For longer windows, divide total count by window size to get per-minute rate
 		const hourCount = this.rollingHour.getCount();
 		const threeHourCount = this.rolling3Hours.getCount();
-		
+
 		// Calculate per-minute rates for the longer windows
 		this.metrics.requests.lastHour = Math.round((hourCount / 60) * 100) / 100; // Requests per minute over last hour
 		this.metrics.requests.last3Hours = Math.round((threeHourCount / 180) * 100) / 100; // Requests per minute over last 3 hours
-			
+
+		// Update unique IPs count
+		this.metrics.connections.uniqueIps = this.uniqueIps.size;
+
 		return this.metrics;
 	}
 
@@ -493,6 +500,15 @@ export class MetricsCounter {
 		this.metrics.connections.total++;
 	}
 
+	/**
+	 * Track an IP address
+	 */
+	trackIpAddress(ipAddress: string | undefined): void {
+		if (ipAddress) {
+			this.uniqueIps.add(ipAddress);
+		}
+	}
+
 	/**
 	 * Update active connection count
 	 */

packages/app/src/web/components/StatefulTransportMetrics.tsx

@@ -22,6 +22,7 @@ type SessionData = {
 	connectionStatus?: 'Connected' | 'Distressed' | 'Disconnected';
 	pingFailures?: number;
 	lastPingAttempt?: string;
+	ipAddress?: string;
 };
 
 /**
@@ -171,6 +172,15 @@ export function StatefulTransportMetrics({ metrics }: StatefulTransportMetricsPr
 			header: createSortableHeader('Last Activity'),
 			cell: ({ row }) => <div className="text-sm">{formatRelativeTime(row.getValue<string>('lastActivity'))}</div>,
 		},
+		{
+			accessorKey: 'ipAddress',
+			header: createSortableHeader('IP Address'),
+			cell: ({ row }) => (
+				<div className="font-mono text-sm" title={row.getValue<string>('ipAddress') || 'Unknown'}>
+					{row.getValue<string>('ipAddress') || '-'}
+				</div>
+			),
+		},
 	];
 
 	return (
@@ -250,6 +260,14 @@ export function StatefulTransportMetrics({ metrics }: StatefulTransportMetricsPr
 									{metrics.requests.averagePerMinute}/{metrics.requests.last3Hours}/{metrics.requests.lastHour}
 								</TableCell>
 							</TableRow>
+							<TableRow>
+								<TableCell className="font-medium text-sm">Unique IPs</TableCell>
+								<TableCell className="text-sm font-mono">{metrics.connections.uniqueIps ?? 0}</TableCell>
+								<TableCell className="font-medium text-sm">Client/Server Errors (4xx/5xx)</TableCell>
+								<TableCell className="text-sm font-mono">
+									{metrics.errors.expected}/{metrics.errors.unexpected}
+								</TableCell>
+							</TableRow>
 							{metrics.sessionLifecycle && (
 								<TableRow>
 									<TableCell className="font-medium text-sm">Sessions New/Res-fail/Del</TableCell>
@@ -258,12 +276,6 @@ export function StatefulTransportMetrics({ metrics }: StatefulTransportMetricsPr
 									</TableCell>
 								</TableRow>
 							)}
-							<TableRow>
-								<TableCell className="font-medium text-sm">Client Errors (4xx)</TableCell>
-								<TableCell className="text-sm font-mono">{metrics.errors.expected}</TableCell>
-								<TableCell className="font-medium text-sm">Server Errors (5xx)</TableCell>
-								<TableCell className="text-sm font-mono">{metrics.errors.unexpected}</TableCell>
-							</TableRow>
 							{metrics.pings && (
 								<TableRow>
 									<TableCell className="font-medium text-sm">Pings Sent</TableCell>

packages/app/src/web/components/StatelessTransportMetrics.tsx

@@ -180,10 +180,12 @@ export function StatelessTransportMetrics({ metrics }: StatelessTransportMetrics
 								</TableCell>
 							</TableRow>
 							<TableRow>
-								<TableCell className="font-medium text-sm">Client Errors (4xx)</TableCell>
-								<TableCell className="text-sm font-mono">{metrics.errors.expected}</TableCell>
-								<TableCell className="font-medium text-sm">Server Errors (5xx)</TableCell>
-								<TableCell className="text-sm font-mono">{metrics.errors.unexpected}</TableCell>
+								<TableCell className="font-medium text-sm">Unique IPs</TableCell>
+								<TableCell className="text-sm font-mono">{metrics.connections.uniqueIps ?? 0}</TableCell>
+								<TableCell className="font-medium text-sm">Client/Server Errors (4xx/5xx)</TableCell>
+								<TableCell className="text-sm font-mono">
+									{metrics.errors.expected}/{metrics.errors.unexpected}
+								</TableCell>
 							</TableRow>
 							{(metrics.staticPageHits200 !== undefined || metrics.staticPageHits405 !== undefined) && (
 								<TableRow>