| 1 | # WebSocket |
| 2 | |
| 3 | Netdata supports WebSocket connections for real-time data streaming and interactive features. |
| 4 | |
| 5 | ## WebSocket Protocols |
| 6 | |
| 7 | Netdata supports the following WebSocket protocols: |
| 8 | |
| 9 | - `echo`: A simple echo protocol for testing WebSocket functionality (available only when compiled with internal checks) |
| 10 | - `mcp`: Model-Context Protocol for AI/ML interactions |
| 11 | |
| 12 | These protocols can be specified either in the WebSocket protocol header during the handshake or through the URL path (e.g., `ws://localhost:19999/echo`). |
| 13 | |
| 14 | ## Configuration Options |
| 15 | |
| 16 | ### Maximum Frame Size |
| 17 | |
| 18 | WebSocket communication is done through frames, with most browsers having limitations on maximum frame size (typically around 16MB). |
| 19 | |
| 20 | #### Global Configuration |
| 21 | |
| 22 | Netdata sets a default outgoing frame size limit of 4MB to ensure browser compatibility while maintaining good performance. |
| 23 | |
| 24 | For larger messages, Netdata automatically fragments them into multiple frames for transmission. |
| 25 | |
| 26 | #### Per-Connection Configuration |
| 27 | |
| 28 | Users can customize the maximum outgoing frame size on a per-connection basis by adding the `max_frame_size` parameter to the WebSocket URL: |
| 29 | |
| 30 | ``` |
| 31 | ws://localhost:19999/echo?max_frame_size=32768 |
| 32 | ``` |
| 33 | |
| 34 | This allows specific clients to set their preferred frame size, which is especially useful for: |
| 35 | |
| 36 | - Resource-constrained devices that may need smaller frames |
| 37 | - Environments with specific network limitations |
| 38 | - Custom applications with specific buffer size requirements |
| 39 | |
| 40 | The accepted range for `max_frame_size` is between 1KB (1024 bytes) and 20MB. Values outside this range will be automatically adjusted to the nearest bound. |
| 41 | |
| 42 | ### WebSocket Compression |
| 43 | |
| 44 | Netdata supports permessage-deflate compression per RFC 7692. Compression is negotiated during the WebSocket handshake and can significantly reduce bandwidth usage for text-based protocols. |
| 45 | |
| 46 | The compression settings can be configured through the standard WebSocket extension negotiation mechanism. |
| 47 | |
| 48 | ## Limitations |
| 49 | |
| 50 | - Control frames (ping, pong, close) cannot be compressed and must be less than 125 bytes |
| 51 | - Control frames cannot be fragmented |
| 52 | - The maximum size for decompressed incoming messages is 200MB |
| 53 | - Incoming frames are limited to 20MB |
| 54 | |
| 55 | ## Examples |
| 56 | |
| 57 | ### Basic Connection |
| 58 | ```javascript |
| 59 | // Connect to echo protocol |
| 60 | const ws = new WebSocket('ws://localhost:19999/echo'); |
| 61 | |
| 62 | // Event handlers |
| 63 | ws.onopen = () => console.log('Connected'); |
| 64 | ws.onmessage = (event) => console.log('Received:', event.data); |
| 65 | ws.onerror = (error) => console.error('Error:', error); |
| 66 | ws.onclose = () => console.log('Disconnected'); |
| 67 | |
| 68 | // Send a message |
| 69 | ws.send('Hello, Netdata!'); |
| 70 | ``` |
| 71 | |
| 72 | ### Connection with Custom Frame Size |
| 73 | ```javascript |
| 74 | // Connect with smaller frame size (32KB) |
| 75 | const ws = new WebSocket('ws://localhost:19999/echo?max_frame_size=32768'); |
| 76 | |
| 77 | // Send a large message (will be automatically fragmented) |
| 78 | const largeMessage = new Array(1000000).join('a'); |
| 79 | ws.send(largeMessage); |
| 80 | ``` |
| 81 | |
| 82 | ## Debugging |
| 83 | |
| 84 | Netdata logs WebSocket connection details including compression settings and frame size limits at the DEBUG log level. To view these logs, run Netdata with increased verbosity or check the error log file. |