diff --git a/doc/RIF_counters.md b/doc/RIF_counters.md new file mode 100644 index 00000000000..d756721deb0 --- /dev/null +++ b/doc/RIF_counters.md @@ -0,0 +1,228 @@ +# Router interface counters in SONiC +### Rev 0.1 + +# Table of Contents + * [List of Tables](#list-of-tables) + * [Revision](#revision) + * [About this Manual](#about-this-manual) + * [Scope](#scope) + * [Definitions/Abbreviation](#definitionsabbreviation) + + * [1 Requirements](#1-overview) + + * [2 CLI format](#2-cli-format) + + * [3 Modules Design](#3-modules-design) + * [3.1 Modules that need to be updated](#31-modules-that-need-to-be-updated) + * [3.1.1 Counter DB](#311-counter-db) + * [3.1.2 CLI](#312-cli) + * [3.1.3 Orchestration Agent](#313-orchestration-agent) + * [3.1.4 Flex Counter](#314-flex-counter) + * [3.1.5 SAI](#318-telemetry) + + * [4 Open questions](#4-open-questions) + +# List of Tables +* [Table 1: Revision](#revision) +* [Table 2: Abbreviations](#definitionsabbreviation) + +###### Revision +| Rev | Date | Author | Change Description | +|:---:|:-----------:|:------------------:|-----------------------------------| +| 0.1 | | Mykola Faryma | Initial version | + +# About this Manual +This document provides general information about RIF counter feature in SONiC. +# Scope +This document describes the high level design of the RIF counters. +# Definitions/Abbreviation +###### Table 2: Abbreviations +| Definitions/Abbreviation | Description | +|--------------------------|--------------------------------------------| +| RIF | Router interface | +| FC | Flex counter | +| API | Application Programmable Interface | +| SAI | Switch Abstraction Interface | + +# 1 Requirements + +Add new CLI commands to show L3 interfaces counters. L3 interface counters refers to router port as well as vlan interface. +The information should be: RX: OK, ERR in packets and bytes. TX: OK, ERR in packets and bytes + +# 2 CLI format +The CLI command format and example output + +``` +$ show interfaces counters rif [OPTOINS] [interface_name] + + Show interface counters + +Options: + + -p, --period TEXT + + --verbose Enable verbose output + + -?, -h, --help Show this message and exit. +``` + +The period option gives the ability to see the counters and RX/TX BPS and PPS. + +The rates are calculated the following way: + +BPS = (new_*_OCTETS - old_*_OCTETS) / delta, + +Where delta is the period specified. The BPS is printed in MB/s, KB/s or B/s depending on the value. + +PPS = (new_*_PACKETS - old_*_PACKETS) / delta + +To clear the counters, the following CLI is available: + +$ sonic-clear interface rifcounters [interface_name] + +We will support both clearing the counters for a single RIF as well as all at once. + +# Example output: + +If the interface name is not provided, all the RIFs counters will be printed: + +$ show interfaces counters rif +``` + IFACE RX_OK RX_BPS RX_PPS RX_ERR TX_OK TX_BPS Tx_PPS TX_ERR +----------- ------- -------- ---------------- ------- -------- --------- -------- +Ethernet0 2180 N/A N/A 0 44697 N/A N/A 0 +Ethernet4 47342 N/A N/A 0 8362 N/A N/A 0 +Ethernet8 2188 N/A N/A 0 9379 N/A N/A 0 +Ethernet12 46882 N/A N/A 0 44448 N/A N/A 0 + ... +Portchannel0002 2833 N/A N/A 0 0 N/A N/A 0 + ... +Vlan2 2833 N/A N/A 0 4170 N/A N/A 0 +``` + +Providing a RIF name will print the counters in a more debug-friendly manner. + +If the interface name does not exist in COUNTERS_RIF_NAME_MAP table, we'll output a warning message. + +$ show interfaces counters rif Portchannel0002 + +``` +Portchannel0002 +--------------- + RX: + 0 packets + 0 bytes + 0 error packets + 0 error bytes + + TX: + 0 packets + 0 bytes + 0 error packets + 0 error bytes +``` +# SAI counters definition: +``` + RX: + packets - SAI_ROUTER_INTERFACE_STAT_IN_PACKETS + bytes - SAI_ROUTER_INTERFACE_STAT_IN_OCTETS + error packets - SAI_ROUTER_INTERFACE_STAT_IN_ERROR_PACKETS + error bytes - SAI_ROUTER_INTERFACE_STAT_IN_ERROR_OCTETS + + TX: + packets - SAI_ROUTER_INTERFACE_STAT_OUT_PACKETS + bytes - SAI_ROUTER_INTERFACE_STAT_OUT_OCTETS + error packets - SAI_ROUTER_INTERFACE_STAT_OUT_ERROR_PACKETS + error bytes - SAI_ROUTER_INTERFACE_STAT_OUT_ERROR_OCTETS +``` + +# 3 Modules Design +## 3.1 Modules that need to be updated + +### 3.1.1 Counter DB + +#### The following new Queue counters should be available for each queue entry in the DB: +- "COUNTERS:rif_vid" + - SAI_ROUTER_INTERFACE_STAT_IN_PACKETS + - SAI_ROUTER_INTERFACE_STAT_IN_OCTETS + - SAI_ROUTER_INTERFACE_STAT_IN_ERROR_PACKETS + - SAI_ROUTER_INTERFACE_STAT_IN_ERROR_OCTETS + - SAI_ROUTER_INTERFACE_STAT_OUT_PACKETS + - SAI_ROUTER_INTERFACE_STAT_OUT_OCTETS + - SAI_ROUTER_INTERFACE_STAT_OUT_ERROR_PACKETS + - SAI_ROUTER_INTERFACE_STAT_OUT_ERROR_OCTETS + +#### Additionally a few mappings should be added: +- "COUNTERS_RIF_TYPE_MAP" - map RIF to its type (e.g. LAG, Vlan) +- "COUNTERS_RIF_NAME_MAP" - map RIF oid to its name + +### 3.1.2 CLI + +Add new show interfaces counters subcommand, add rifstat script, try to reuse portstat code. + +### 3.1.3 SWSS + +IntfsOrch should be updated: + - Add/remove RIFs to Flex counter + - implement the Counters Db maps generation + +### 3.1.4 Flex counter + +Add router interface stats support. Implement new FC group for RIFs. + +Let's set the default FC interval to 1 second, same as for port counters. + +### 3.1.5 SAI + +The sai APIs and calls are: + +sai_router_interface_api -> sai_get_router_interface_stats() + +``` +/** + * @brief Router interface counter IDs in sai_get_router_interface_stats() call + */ +typedef enum _sai_router_interface_stat_t +{ + /** Ingress byte stat count */ + SAI_ROUTER_INTERFACE_STAT_IN_OCTETS, + + /** Ingress packet stat count */ + SAI_ROUTER_INTERFACE_STAT_IN_PACKETS, + + /** Egress byte stat count */ + SAI_ROUTER_INTERFACE_STAT_OUT_OCTETS, + + /** Egress packet stat count */ + SAI_ROUTER_INTERFACE_STAT_OUT_PACKETS, + + /** Byte stat count for packets having errors on router ingress */ + SAI_ROUTER_INTERFACE_STAT_IN_ERROR_OCTETS, + + /** Packet stat count for packets having errors on router ingress */ + SAI_ROUTER_INTERFACE_STAT_IN_ERROR_PACKETS, + + /** Byte stat count for packets having errors on router egress */ + SAI_ROUTER_INTERFACE_STAT_OUT_ERROR_OCTETS, + + /** Packet stat count for packets having errors on router egress */ + SAI_ROUTER_INTERFACE_STAT_OUT_ERROR_PACKETS + +} sai_router_interface_stat_t; +``` + +### 3.1.5 Telemetry + +We can expose the rif counters via sonic telemetry. +The telemetry is able to access the data in SONiC databases according to the schema, +but for more simplicity virtual path can be used. Virtual path allows to querry for counters by interface name, instead of VID. + +Example virtual paths + +| DB target | Virtual Path | Description | +| --- | --- | --- | +| COUNTERS_DB | "RIF_COUNTERS/" | All counters on all interfaces | +| COUNTERS_DB | "RIF_COUNTERS/``*``/````" | One counter on all interfaces | +| COUNTERS_DB | "RIF_COUNTERS/````/````" | One counter on one interface | + +### 4 Open questions