diff --git a/broadview_collector/serializers/bst_to_monasca.py b/broadview_collector/serializers/bst_to_monasca.py index 611fa1c..35aaa0b 100644 --- a/broadview_collector/serializers/bst_to_monasca.py +++ b/broadview_collector/serializers/bst_to_monasca.py @@ -19,7 +19,13 @@ import unittest import datetime import time + class BSTToMonasca(BroadViewSerializerBase): + ''' + Class that converts BST object model to OpeStack Monasca metrics. + See broadview-collector/doc/bst_to_monasca_serializer.md for documentation + ''' + def __init__(self): pass diff --git a/doc/bst_to_monasca_serializer.md b/doc/bst_to_monasca_serializer.md new file mode 100644 index 0000000..d7e8c7a --- /dev/null +++ b/doc/bst_to_monasca_serializer.md @@ -0,0 +1,220 @@ +Monasca BST Serializer Format +============================= + +Monasca API supports reporting of metrics in JSON encoding with the following +key/value pairs: + +* timestamp - event time in microseconds (floating point) +* name - metric name +* value - metric value +* dimensions - a set of key/value pairs that provide additional metadata +for the metric + +This document details the format of Monasca metrics as generated by the +BST to Monasca serializer (serializers/bst_to_monasca.py) + +BST +--- + +This section describes in more detail the format currently used for BST +metrics published to Monasca. + +# name + +The name field consists of the suffix "broadview.bst." to which is added +the name of the BST statistic. + +BST statistic names consist of the following: + +* device +* ingress-port-priority-group +* ingress-port-service-pool +* ingress-service-pool +* egress-cpu-queue +* egress-mc-queue +* egress-port-service-pool +* egress-rqe-queue +* egress-service-pool +* egress-uc-queue +* egress-uc-queue-group + +###Example: "name": "broadview.bst.egress-port-service-pool" + +# timestamp + +The timestamp field is a floating point value which represents that time in +microseconds of the statistic. + +###Example: "timestamp": 1459361118000.0 + +# value + +The value field represents that reported value for the statistic. + +###Example: "value": 366 + +# dimensions + +Note the structure of the name field values for BST. Except for device, +the name consists of the string "ingress" or "egress", followed by a '-' +separated list of strings. These names imply some of the metadata that +is recorded in the dimensions field. For example, names which contain +the "-port-" substring will have a "port" dimension. Similarly, a name +with "-service-pool-" substring will have a "service-pool" dimension. + +All statistics will include a dimension named "asic-id" which specifies +the ASIC to which the data corresponds. + +While some of the dimensions are based on the name of the statistic, +other dimensions reflect data transmitted by the agent that has been +given a name in the BroadView BST documentation. + +Finally, be aware that a statistic reported by BroadView often comes in +the form of an aggregate. For a given set of metadata, there might be +multiple values reported. In the case of ingress-port-priority-group, +for example, both um-share-buffer-count and um-headroom-count are reported +together in an array. They share the same metadata: asic-id, port, and +priority-group (as implied by the name of the statistic). broadview-lib +flattens this aggregate report into two separate statistics, one for +um-share-bufffer-count, and one for um-headroom-count. This flattening +aids indexers of the Monasca data; both stats can be retrieved by searching +on ingress-port-priority-group, or a more refined search can obtain just +the um-share-bufffer-count data by providing that dimension as a search +key. Except for the "stat" and value fields, the remaining fields in the +flattened set of reports (e.g., name, timestamp) should be the same. + +The following sections define the metadata that are generated by the BST +to Monasca serializer for each BST statistic. An example for each stat +is provided in the context of a complete report (the data is accessible +via the "dimension" field). + +## device + +* asic-id - the ASIC pertaining to the statistic + +###Example: + + {"timestamp": 1459361118000.0, "name": "broadview.bst.device", "value": 46, "dimensions": {"asic-id": "20"}} + +## ingress-port-priority-group + +* asic-id - the ASIC pertaining to the statistic +* priority-group - the priority group associated with the stat +* port - the port impacted by the statistic +* stat - either um-share-buffer-count or um-headroom-buffer-count + +###Example: + + {"timestamp": 1459361118000.0, "name": "broadview.bst.ingress-port-priority-group", "value": 45500, "dimensions": {"asic-id": "20", "stat": "um-share-buffer-count", "priority-group": 5, "port": "2"}} + + {"timestamp": 1459361118000.0, "name": "broadview.bst.ingress-port-priority-group", "value": 44450, "dimensions": {"asic-id": "20", "stat": "um-headroom-buffer-count", "priority-group": 5, "port": "2"}} + +## ingress-port-service-pool + +* asic-id - the ASIC pertaining to the statistic +* service-pool - the service pool associated with the stat +* port - the port impacted by the statistic +* stat - um-share-buffer-count + +###Example: + + {"timestamp": 1459361118000.0, "name": "broadview.bst.ingress-port-service-pool", "value": 324, "dimensions": {"asic-id": "20", "stat": "um-share-buffer-count", "service-pool": 5, "port": "2"}} + +## ingress-service-pool + +* asic-id - the ASIC pertaining to the statistic +* service-pool - the service pool associated with the stat +* stat - um-share-buffer-count + +###Example: + + {"timestamp": 1459361118000.0, "name": "broadview.bst.ingress-service-pool", "value": 3240, "dimensions": {"asic-id": "20", "stat": "um-share-buffer-count", "service-pool": 1}} + +## egress-cpu-queue + +* asic-id - the ASIC pertaining to the statistic +* queue - the queue associated with the statistic +* stat - either cpu-buffer-count or cpu-queue-entries + +###Example: + + {"timestamp": 1459361118000.0, "name": "broadview.bst.egress-cpu-queue", "value": 4566, "dimensions": {"queue": 3, "asic-id": "20", "stat": "cpu-buffer-count"}} + + {"timestamp": 1459361118000.0, "name": "broadview.bst.egress-cpu-queue", "value": 0, "dimensions": {"queue": 3, "asic-id": "20", "stat": "cpu-queue-entries"}} + +## egress-mc-queue + +* asic-id - the ASIC pertaining to the statistic +* queue - the queue associated with the statistic +* port - the port associated with the statistic +* stat - either mc-buffer-count or mc-queue-entries + +###Example: + + {"timestamp": 1459361118000.0, "name": "broadview.bst.egress-mc-queue", "value": 34, "dimensions": {"queue": 1, "asic-id": "20", "stat": "mc-buffer-count", "port": "1"}} + + {"timestamp": 1459361118000.0, "name": "broadview.bst.egress-mc-queue", "value": 89, "dimensions": {"queue": 1, "asic-id": "20", "stat": "mc-queue-entries", "port": "1"}} + + +## egress-port-service-pool + +* asic-id - the ASIC pertaining to the statistic +* service-pool - the service pool associated with the statistic +* port - the port associated with the statistic +* stat - either um-share-buffer-count, mc-share-buffer-count or mc-share-queue-entries + +###Example: + + {"timestamp": 1459361118000.0, "name": "broadview.bst.egress-port-service-pool", "value": 0, "dimensions": {"asic-id": "20", "stat": "um-share-buffer-count", "service-pool": 5, "port": "2"}} + + {"timestamp": 1459361118000.0, "name": "broadview.bst.egress-port-service-pool", "value": 324, "dimensions": {"asic-id": "20", "stat": "mc-share-buffer-count", "service-pool": 5, "port": "2"}} + + {"timestamp": 1459361118000.0, "name": "broadview.bst.egress-port-service-pool", "value": 0, "dimensions": {"asic-id": "20", "stat": "mc-share-queue-entries", "service-pool": 5, "port": "2"}} + +## egress-rqe-queue + +* asic-id - the ASIC pertaining to the statistic + +###Example: + + {"timestamp": 1459361118000.0, "name": "broadview.bst.egress-rqe-queue", "value": 3333, "dimensions": {"queue": 2, "asic-id": "20", "stat": "rqe-buffer-count"}} + + {"timestamp": 1459361118000.0, "name": "broadview.bst.egress-rqe-queue", "value": 4444, "dimensions": {"queue": 2, "asic-id": "20", "stat": "rqe-queue-entries"}} + + +## egress-service-pool + +* asic-id - the ASIC pertaining to the statistic +* service-pool - the service pool associated with the statistic +* stat - either um-share-buffer-count, mc-share-buffer-count or mc-share-queue-entries + +###Example: + + {"timestamp": 1459361118000.0, "name": "broadview.bst.egress-service-pool", "value": 0, "dimensions": {"asic-id": "20", "stat": "um-share-buffer-count", "service-pool": 2}} + + {"timestamp": 1459361118000.0, "name": "broadview.bst.egress-service-pool", "value": 0, "dimensions": {"asic-id": "20", "stat": "mc-share-buffer-count", "service-pool": 2}} + + {"timestamp": 1459361118000.0, "name": "broadview.bst.egress-service-pool", "value": 3240, "dimensions": {"asic-id": "20", "stat": "mc-share-queue-entries", "service-pool": 2}} + + +## egress-uc-queue + +* asic-id - the ASIC pertaining to the statistic +* queue - the queue associated with the statistic +* port - the port associated with the statistic +* stat - uc-queue-buffer-count + +###Example: + + {"timestamp": 1459361118000.0, "name": "broadview.bst.egress-uc-queue", "value": 1111, "dimensions": {"queue": 6, "asic-id": "20", "stat": "uc-queue-buffer-count", "port": "0"}} + +## egress-uc-queue-group + +* asic-id - the ASIC pertaining to the statistic +* queue-group - the queue group associated with the statistic +* stat - uc-buffer-count + +###Example: + + {"timestamp": 1459361118000.0, "name": "broadview.bst.egress-uc-queue-group", "value": 2222, "dimensions": {"queue-group": 6, "asic-id": "20", "stat": "uc-buffer-count"}} +