Add documentation for the bst to monasca serializer

Change-Id: Ia7b857ada73139c0c819970a931ea2092b5948f9
This commit is contained in:
Vitaliy Kharechko 2016-03-31 11:10:43 +03:00
parent addcc9af82
commit 7aca56e931
2 changed files with 226 additions and 0 deletions

View File

@ -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

View File

@ -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"}}