Statistics.adoc

Statistics

Table of Contents

• Introduction
• Subscription Request
• Request Properties - Request Format
• Request Properties - SubscriptionParameters
  • Example
• Subscription Types
  • JSON Based
  • RAW Console Output (No Parameters)
  • RAW Console Output (Parameters Required)
  • Other Endpoints

Introduction

You can get streaming statistical data from the endpoint wss://host-or-ip/ws/stats. The data from the WebSocket is framed oddly, it’s actually a streaming protocol that has been sent and received over WebSocket. The data will not arrive like you might expect. You MUST reassemble the web socket data fragments since the frames may not align with data boundaries. Commands must be sent with a valid SESSION_ID.

The format of data to and from the WebSocket stream is LENGTH\nJSON_PAYLOAD\n. Line feeds are Linux line feeds (e.g. \n).

When the SESSION_ID times out the WebSocket will abruptly close so it’s recommended to refresh it occasionally.

Subscription Request

No data will be received by the socket until the user requests a subscription to a selection of message types.

Request Properties - Request Format

Name	Type	Values	Description
SUBSCRIBE	Array (Object)	Array of SubscriptionParameters	An array of objects to represent individual specific MessageTypes to subscribe to and their parameters.
UNSUBSCRIBE	Array (Object)	Array of SubscriptionParameters	An array of objects to represent individual specific MessageTypes to unsubscribe from and their parameters.
SESSION_ID	String	String	The authorisation string for this session to confirm the user is correctly authenticated.

Request Properties - SubscriptionParameters

Name	Type	Values	Description
name	String	String	The SubscriptionTypes to subscribe.

Example

249
{"SUBSCRIBE":[{"name":"export"},{"name":"discover"},{"name":"pon-stats"},{"name":"interfaces"},{"name":"system-stats"},{"name":"num-routes"},{"name":"config-change"},{"name":"users"}],"UNSUBSCRIBE":[],"SESSION_ID":"b5d5cfdb326c484abb00ca0d9effffff"}

Return values from the stream follow a similar format.

104
{
    "system-stats":
    {
        "cpu": "10",
        "uptime": "57864",
        "mem": "60"
    }
}

The web UI sends a ping every 30 seconds which consists of the following:

66
{"CLIENT_PING":"","SESSION_ID":"f989665499eb406b8600fd50bf1971bc"}

Warning

Failure to send a properly formed subscription request will continue to result in no messages being sent from the server.

Subscription Types

JSON Based

Each one of these subscriptions will output data with the response being full JSON objects.

SubscriptionTypes

Name	Subscription String	Description
Configuration Change	config-change	Returns only when EdgeOS is processing a configuration change.
Device Discovery	discover	Periodic messages containing results from any devices discovered (typically via UBNT Discovery).
Interfaces	interfaces	Periodic messages containing network interface information for each of the EdgeOS network interfaces.
Number Of Routes	num-routes	Periodic messages containing counts of the EdgeOS network routes.
System Statistics	system-stats	Periodic messages containing system statistics about the EdgeOS device
Traffic Analysis	export	Periodic messages containing Traffic Analysis (aka DPI) information.
Users	users	Periodic messages listing the users logged into the EdgeOS device (including via SSH, Web and VPN).
UDAPI Statistics	udapi-statistics	Periodic messages containing device statistics in a specific Ubiquiti Device API (UDAPI) format, used by UNMS.

RAW Console Output (No Parameters)

Each one of these endpoints just dumps the raw console output data within a string {'[Request sub_id]': '<line of text>\n' }

These are subscribed to in the same way as the JSON subscriptions above but while no additional parameters may need to be specified the SubscriptionParameters schema is extended to attribute specific console responses to specific requests.

SubscriptionTypes

Name	Subscription String	Description
Log Feed	log-feed	Basically a tail -f /var/log/messages.
NAT Statistics	nat-stats	Returns per-rule NAT stats.
Port Forwarding Statistics	pf-stats	Contains the statistics from Port Forwarding.

Request Optional Properties - SubscriptionParameters (extended)

Name	Type	Values	Description
sub_id (Optional)	String	String	An identifier to tag plain string responses to this subscription with.

RAW Console Output (Parameters Required)

Each one of these endpoints just dumps the raw console output data within a string {'[Request sub_id]': '<line of text>\n' }

These are subscribed to in the same way as the JSON subscriptions above but some additional parameters may need to be specified.

Name	Subscription String	Description
Bandwidth Test	bwtest-feed	Performs or hosts a bandwidth test (using iperf).
Firewall Statistics	fw-stats	Returns periodic firewall statistics.
Ping	ping-feed	Performs a ping.
Traceroute	traceroute-feed	Performs a tracert to trace a route to a host.
Packet Capture	packets-feed	Performs a packet capture (using tcpdump).

Other Endpoints

There are also the following endpoints that not much is known about (it’s likely the implementation has been removed from ubnt-util but have been left over in the web UI):

Name	Subscription String	Description
LLDP Neighbours (not present in web UI)	lldp-detail	Information about Link Layer Discovery Protocol (LLDP) connected neighbours.
NNI Statistics (not present in ubnt-util)	nni-stats	Lists Network to Network Interface (NNI) statistics.
ONU List (not present in ubnt-util)	onu-list	Lists Optical Network Unit (ONU) details.
PON Statistics (not present in ubnt-util)	pon-stats	Lists Passive Optical Network (PON) statistics.