🚧

Note

The Streaming API encoded message must be first decoded using CloudEvents proto file before decoding using the event specific proto file below

Client Monitoring events provide real-time monitoring statistics for clients in your Central network.

Endpoint

Connect to the following WebSocket endpoint to receive monitoring events:

wss://<host>/network-monitoring/v1/clients-events

Ensure that you replace host value with your Central Base URL. Please check out our Getting Started guide for more information.

Proto File

Event messages published by Central are encoded using Google Protocol Buffers and sent over the WebSocket connection in serialized form.

To deserialize these messages, clients must use the following .proto file, which defines the schema used by Central when encoding the monitoring payloads.

syntax = "proto3";

package network_monitoring.clients.v1;

import "google/protobuf/timestamp.proto";

option java_package = "com.hpe.gravity.apistreaming.proto.clients";


// StreamClientMessage - Unified wrapper for all client streaming events.
// Consumers unpack google.protobuf.Any as StreamClientMessage and switch on the oneof case.
message StreamClientMessage {
  oneof client_event {
    ClientState client_state = 1;
    ClientStats client_stats = 2;
  }
}

// ---------------------------------------------------------------------------
// Enums
// ---------------------------------------------------------------------------

// ClientType - Defines the connectivity type of a client.
enum ClientType {
  CLIENT_TYPE_UNSPECIFIED = 0;
  CLIENT_TYPE_WIRELESS = 1;
  CLIENT_TYPE_WIRED = 2;
  CLIENT_TYPE_REMOTE = 3;
}

// ClientStatus - Defines the connection status of a client.
enum ClientStatus {
  CLIENT_STATUS_UNSPECIFIED = 0;
  CLIENT_STATUS_CONNECTING = 1;
  CLIENT_STATUS_CONNECTED = 2;
  CLIENT_STATUS_DISCONNECTED = 3;
  CLIENT_STATUS_FAILED = 4;
  CLIENT_STATUS_BLOCKED = 5;
}

// AuthType - Shared by both WirelessClient and WiredClient.
// AP/GW: 32 network-access types; CX: DOT1X/MAC subset; PVOS: management-plane appended.
enum AuthType {
  AUTH_TYPE_UNSPECIFIED = 0;
  AUTH_TYPE_CAPTIVE_PORTAL = 1;
  AUTH_TYPE_MAC = 2;
  AUTH_TYPE_VPN = 3;
  AUTH_TYPE_DOT1X = 4;
  AUTH_TYPE_STATEFUL_KERBEROS = 5;
  AUTH_TYPE_RADIUS_ACCOUNTING = 6;
  AUTH_TYPE_SECURE_ID = 7;
  AUTH_TYPE_STATEFUL_RADIUS = 8;
  AUTH_TYPE_SWITCH_MANAGEMENT = 9;
  AUTH_TYPE_DOT1X_MACHINE = 10;
  AUTH_TYPE_DOT1X_USER = 11;
  AUTH_TYPE_DOT1X_WIRED_MACHINE = 12;
  AUTH_TYPE_DOT1X_WIRED_USER = 13;
  AUTH_TYPE_PUB_COOKIE = 14;
  AUTH_TYPE_TACACS_PLUS = 15;
  AUTH_TYPE_XSEC = 16;
  AUTH_TYPE_XSEC_MACHINE = 17;
  AUTH_TYPE_XSEC_USER = 18;
  AUTH_TYPE_XSEC_WIRED = 19;
  AUTH_TYPE_XSEC_WIRED_MACHINE = 20;
  AUTH_TYPE_XSEC_WIRED_USER = 21;
  AUTH_TYPE_STATEFUL_NTLM = 22;
  AUTH_TYPE_RAP_AP = 23;
  AUTH_TYPE_VIA_WEB = 24;
  AUTH_TYPE_GIS = 25;
  AUTH_TYPE_TRANSPORT_VPN = 26;
  AUTH_TYPE_VIA_VPN = 27;
  AUTH_TYPE_PUTN_DOT1X = 28;
  AUTH_TYPE_PUTN_MAC = 29;
  AUTH_TYPE_PUTN_CP = 30;
  AUTH_TYPE_PUTN_LMA = 31;
  // PVOS management-plane methods
  AUTH_TYPE_TELNET = 32;
  AUTH_TYPE_WEBUI = 33;
  AUTH_TYPE_SSH = 34;
  AUTH_TYPE_WEB = 35;
  AUTH_TYPE_SNMP = 36;
  AUTH_TYPE_SSH_NONE = 37;
  AUTH_TYPE_LMA = 38;
}

// ---------------------------------------------------------------------------
// Sub-messages
// ---------------------------------------------------------------------------

// CpdiInfo - Client Profiling and Device Identification.
// Populated by all sources (AP, GW, CX, PVOS).
message CpdiInfo {
  string client_function = 1; // e.g. "Workstation", "Phone"
  string client_vendor = 2; // e.g. "Apple", "Dell"
  string client_operating_system = 3; // e.g. "iOS 17", "Windows 11"
  string client_mac_vendor = 4; // OUI-based vendor
  string client_category = 5; // device category
}

// ---------------------------------------------------------------------------
// Common — shared across all client types
// ---------------------------------------------------------------------------

// ClientDetails - Common fields shared across all client types.
message ClientDetails {
  // Mandatory
  string mac_address = 1;
  string tenant_id = 2;
  string site_id = 3;
  string client_name = 4; // priority: username > hostname > mac
  ClientStatus status = 5;
  string connected_device_serial = 6;

  // Optional
  string host_name = 7;
  string user_name = 8;
  AuthType authentication_type = 9;
  string ipv4 = 10;
  string ipv6 = 11; // global unicast IPv6
  string device_name = 12; // AP name / GW name / switch hostname
  string role = 13;
  uint32 vlan_id = 14;
  string vlan_name = 15;
  string port = 16; // switch port or AP wired port name
  CpdiInfo cpdi = 17;
  // Indicates the timestamp of gateway state event, RFC3339 format
  google.protobuf.Timestamp connected_since = 18;
  google.protobuf.Timestamp last_seen = 19;
}

// ---------------------------------------------------------------------------
// Client State — unified state for wireless, wired, and remote clients
// ---------------------------------------------------------------------------

// ClientState - State information for all client types.
// Wireless-specific fields are populated when type = CLIENT_TYPE_WIRELESS.
// Remote-specific fields are populated when type = CLIENT_TYPE_REMOTE.
message ClientState {
  ClientDetails client_details = 1;
  // Indicates the connectivity type of the client.
  ClientType type = 2;

  // Wireless-specific fields (populated when type = CLIENT_TYPE_WIRELESS)
  string radio_mac_address = 3; // radio/VAP MAC
  string wlan_name = 4; // ESSID / WLAN profile name
  string wireless_band = 5; // "2.4 GHz" / "5 GHz" / "6 GHz"
  string wireless_channel = 6; // e.g. "36 (80 MHz)"
  string phy_type = 7; // e.g. "802.11ax"
  string key_management = 8; // e.g. "WPA3-SAE", "WPA2-PSK"
  string wireless_security = 9; // e.g. "CCM-128", "GCM-256"
  int32 snr = 10;
}

// ---------------------------------------------------------------------------
// Stats — client traffic and link statistics
// ---------------------------------------------------------------------------

// ClientStats - Traffic and link statistics for clients.
message ClientStats {
  string tenant_id = 1;
  string site_id = 2;
  string mac_address = 3;
  string client_name = 4;
  // Indicates the timestamp of device stats event, RFC3339 format
  google.protobuf.Timestamp timestamp = 5;
  string connected_device_serial = 6;
  string port = 7;
  string wlan_name = 8; // populated for wireless clients only
  uint64 tx_bytes = 9;
  uint64 rx_bytes = 10;
  uint32 tx_data_frames = 11;
  uint32 rx_data_frames = 12;
  uint32 tx_error_frames = 13;
  uint32 rx_error_frames = 14;
  uint32 tx_drop_frames = 15;
  uint32 rx_drop_frames = 16;
  uint32 tx_retry_frames = 17;
  uint32 rx_retry_frames = 18;
  uint32 speed = 19;
  string duplex = 20;
  int32 snr = 21; // wireless only
}

Supported Event Types

Clients Monitoring supports several event types. These values can be used when filtering events at subscription time.

State Event Types

Stats Event Types