get_bandwidth_usage
Monitor and analyze top bandwidth-consuming devices on your network by specifying a time period and device limit. Supports filtering by Firewalla box for detailed insights.
Instructions
Get top bandwidth consuming devices (convenience wrapper around get_device_status)
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| box | No | Filter devices under a specific Firewalla box | |
| limit | No | Number of top devices to return | |
| period | Yes | Time period for bandwidth calculation |
Implementation Reference
- src/tools/handlers/network.ts:403-543 (handler)Core implementation of the get_bandwidth_usage tool handler. Validates 'period' (enum: ['1h','24h','7d','30d']) and 'limit' parameters, fetches data via firewalla.getBandwidthUsage, normalizes bytes to MB/GB, enriches with geo data, and standardizes the response.export class GetBandwidthUsageHandler extends BaseToolHandler { name = 'get_bandwidth_usage'; description = 'Get top bandwidth consuming devices by data usage. Requires limit and period parameters. Data is cached for 5 minutes for performance.'; category = 'network' as const; constructor() { super({ enableGeoEnrichment: true, enableFieldNormalization: true, additionalMeta: { data_source: 'bandwidth_usage', entity_type: 'device_bandwidth', supports_geographic_enrichment: true, supports_field_normalization: true, standardization_version: '2.0.0', }, }); } async execute( args: ToolArgs, firewalla: FirewallaClient ): Promise<ToolResponse> { try { // Parameter validation const periodValidation = ParameterValidator.validateEnum( args?.period, 'period', ['1h', '24h', '7d', '30d'], true ); const limitValidation = ParameterValidator.validateNumber( args?.limit, 'limit', { required: false, defaultValue: 10, ...getLimitValidationConfig(this.name), } ); const validationResult = ParameterValidator.combineValidationResults([ periodValidation, limitValidation, ]); if (!validationResult.isValid) { return this.createErrorResponse( 'Parameter validation failed', ErrorType.VALIDATION_ERROR, undefined, validationResult.errors ); } const usageResponse = await withToolTimeout( async () => firewalla.getBandwidthUsage( periodValidation.sanitizedValue as string, limitValidation.sanitizedValue as number ), this.name ); // Ensure we have results and validate count vs requested limit const results = usageResponse.results || []; const requestedLimit = limitValidation.sanitizedValue as number; // Note: if we get fewer results than requested, this may be due to // insufficient data rather than an error const startTime = Date.now(); // Process bandwidth usage data const bandwidthData = SafeAccess.safeArrayMap(results, (item: any) => ({ device_id: SafeAccess.getNestedValue(item, 'device_id', 'unknown'), device_name: SafeAccess.getNestedValue( item, 'device_name', 'Unknown Device' ), ip: SafeAccess.getNestedValue(item, 'ip', 'unknown'), bytes_uploaded: SafeAccess.getNestedValue(item, 'bytes_uploaded', 0), bytes_downloaded: SafeAccess.getNestedValue( item, 'bytes_downloaded', 0 ), total_bytes: SafeAccess.getNestedValue(item, 'total_bytes', 0), total_mb: Math.round( ((SafeAccess.getNestedValue(item, 'total_bytes', 0) as number) / (1024 * 1024)) * 100 ) / 100, total_gb: Math.round( ((SafeAccess.getNestedValue(item, 'total_bytes', 0) as number) / (1024 * 1024 * 1024)) * 100 ) / 100, })); // Apply geographic enrichment for IP addresses const enrichedBandwidthData = await this.enrichGeoIfNeeded( bandwidthData, ['ip'] ); const unifiedResponseData = { period: periodValidation.sanitizedValue, top_devices: results.length, requested_limit: requestedLimit, bandwidth_usage: enrichedBandwidthData, }; const executionTime = Date.now() - startTime; return this.createUnifiedResponse(unifiedResponseData, { executionTimeMs: executionTime, }); } catch (error: unknown) { // Handle timeout errors specifically if (error instanceof TimeoutError) { return createTimeoutErrorResponse( this.name, error.duration, 10000 // Default timeout from timeout-manager ); } const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred'; return this.createErrorResponse( `Failed to get bandwidth usage: ${errorMessage}`, ErrorType.API_ERROR, { originalError: errorMessage } ); } } }
- src/tools/registry.ts:171-171 (registration)Registers the GetBandwidthUsageHandler in the ToolRegistry constructor, making the tool available to the MCP server.this.register(new GetBandwidthUsageHandler()); // wrapper around get_device_status
- src/tools/registry.ts:41-44 (registration)Imports the GetBandwidthUsageHandler from network.ts for use in tool registration.GetFlowDataHandler, GetBandwidthUsageHandler, GetOfflineDevicesHandler, } from './handlers/network.js';
- src/config/limits.ts:83-83 (helper)Configures rate limits and validation constraints for the get_bandwidth_usage tool.get_bandwidth_usage: STANDARD_LIMITS.BANDWIDTH_ANALYSIS,