Update monasca serializer documentation

Change-Id: I777bc8d3f64f8e686adc01557fd8c1e10a4c0b36

doc/bst_to_monasca_serializer.md

@@ -38,20 +38,26 @@ BST statistic names consist of the following:
 * egress-uc-queue
 * egress-uc-queue-group
 
-###Example: "name": "broadview.bst.egress-port-service-pool"
+###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
+###Example
+
+    "timestamp": 1459361118000.0
 
 # value
 
 The value field represents that reported value for the statistic.
 
-###Example: "value": 366
+###Example
+
+    "value": 366
 
 # dimensions
 
@@ -92,7 +98,7 @@ via the "dimension" field).
 
 * asic-id - the ASIC pertaining to the statistic
 
-###Example:
+###Example
 
     {"timestamp": 1459361118000.0, "name": "broadview.bst.device", "value": 46, "dimensions": {"asic-id": "20"}}
 
@@ -103,7 +109,7 @@ via the "dimension" field).
 * port - the port impacted by the statistic
 * stat - either um-share-buffer-count or um-headroom-buffer-count
 
-###Example:
+###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"}}
 
@@ -116,7 +122,7 @@ via the "dimension" field).
 * port - the port impacted by the statistic
 * stat - um-share-buffer-count
 
-###Example:
+###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"}}
 
@@ -126,7 +132,7 @@ via the "dimension" field).
 * service-pool - the service pool associated with the stat
 * stat - um-share-buffer-count
 
-###Example:
+###Example
 
     {"timestamp": 1459361118000.0, "name": "broadview.bst.ingress-service-pool", "value": 3240, "dimensions": {"asic-id": "20", "stat": "um-share-buffer-count", "service-pool": 1}}
 
@@ -136,7 +142,7 @@ via the "dimension" field).
 * queue - the queue associated with the statistic
 * stat - either cpu-buffer-count or cpu-queue-entries 
 
-###Example:
+###Example
 
     {"timestamp": 1459361118000.0, "name": "broadview.bst.egress-cpu-queue", "value": 4566, "dimensions": {"queue": 3, "asic-id": "20", "stat": "cpu-buffer-count"}}
 
@@ -149,7 +155,7 @@ via the "dimension" field).
 * port - the port associated with the statistic
 * stat - either mc-buffer-count or mc-queue-entries 
 
-###Example:
+###Example
 
     {"timestamp": 1459361118000.0, "name": "broadview.bst.egress-mc-queue", "value": 34, "dimensions": {"queue": 1, "asic-id": "20", "stat": "mc-buffer-count", "port": "1"}}
 
@@ -163,7 +169,7 @@ via the "dimension" field).
 * port - the port associated with the statistic
 * stat - either um-share-buffer-count, mc-share-buffer-count or mc-share-queue-entries
 
-###Example:
+###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"}}
 
@@ -175,7 +181,7 @@ via the "dimension" field).
 
 * asic-id - the ASIC pertaining to the statistic
 
-###Example:
+###Example
 
     {"timestamp": 1459361118000.0, "name": "broadview.bst.egress-rqe-queue", "value": 3333, "dimensions": {"queue": 2, "asic-id": "20", "stat": "rqe-buffer-count"}}
 
@@ -188,7 +194,7 @@ via the "dimension" field).
 * 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:
+###Example
 
     {"timestamp": 1459361118000.0, "name": "broadview.bst.egress-service-pool", "value": 0, "dimensions": {"asic-id": "20", "stat": "um-share-buffer-count", "service-pool": 2}}
 
@@ -204,7 +210,7 @@ via the "dimension" field).
 * port - the port associated with the statistic
 * stat - uc-queue-buffer-count
 
-###Example:
+###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"}}
 
@@ -214,7 +220,7 @@ via the "dimension" field).
 * queue-group - the queue group associated with the statistic
 * stat - uc-buffer-count
 
-###Example:
+###Example
 
     {"timestamp": 1459361118000.0, "name": "broadview.bst.egress-uc-queue-group", "value": 2222, "dimensions": {"queue-group": 6, "asic-id": "20", "stat": "uc-buffer-count"}}
 

doc/pt_to_monasca_serializer.md

@@ -0,0 +1,291 @@
+Monasca PT 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 (however, meta-data the dimensions field determines
+if the value is valid or not, for some reports, there is no associated 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
+Packet Trace to Monasca serializer (serializers/pt_to_monasca.py)
+
+PT Fields
+---------
+
+# name 
+
+The name field consists of the suffix "broadview.pt." to which is added
+the name of the PT report.
+
+PT report names consist of the following:
+
+* packet-trace-profile
+* packet-trace-lag-resolution
+* packet-trace-ecmp-resolution
+* packet-trace-drop-reason
+* packet-trace-drop-counter-report
+
+###Example: 
+
+    "name": "broadview.pt.packet-trace-ecmp-resolution"
+
+# timestamp
+
+The timestamp field is a floating point value which represents that time in 
+microseconds of the report (as provided by the agent or as added by the 
+collector when no such timestamp is provided by the agent).
+
+###Example
+
+    "timestamp": 1459361118000.0
+
+# value
+
+The value field represents that reported value for the statistic.
+
+###Example
+
+    "value": 366
+
+Note: the dimension field "ignore-value" is set to 1 when the value is 
+valid for the specific report type. If 0, value must be ignored.
+
+# dimensions
+
+Dimensions contains (meta)data associated with the report. 
+
+All reports will include the following dimensions.
+
+# asic-id 
+
+The ID of the ASIC to which the report corresponds
+
+# bv-agent
+
+The IPV4 address of the agent that generated the report
+
+# ignore-value
+
+If 1, the value field is not valid (and will be set to 0)
+If 0, the value field is valid (and can be any value)
+
+When ignore-value is 0, generally the data of the report will be contained
+as a dimension.
+
+packet-trace-profile 
+--------------------
+
+This report can be invoked to report lag-link-resolution or ecmp-resolution
+data, as specified by the realm dimension (see below). 
+
+# value - ignored for this report
+
+# dimensions 
+
+## realm
+
+Either "lag-link-resolution" or "ecmp-link-resolution"
+
+## ignore-value
+
+Always 1 for this report
+
+The following dimensions are for lag-link-resolution only.
+
+## lag-id
+
+The lag ID 
+
+## lag-members
+
+An array of lag member strings
+
+## dst-lag-member
+
+Destination lag member, as a string
+
+## port
+
+Associated port
+
+### Example
+
+    {"timestamp": 1416298504000.0, "name": "broadview.pt.packet-trace-profile", "value": 0, "dimensions": {"lag-id": "2", "asic-id": "1", "realm": "lag-link-resolution", "ignore-value": 1, "bv-agent": "10.14.244.199", "lag-members": ["1", "2", "3", "4"], "dst-lag-member": "4", "port": "1"}}
+
+The following dimensions are for ecmp-link-resolution realm only.
+
+## ecmp-next-hop-ip
+
+The IPV4 address of the ecmp next hop
+
+## ecmp-group-id
+
+ecmp group ID, as a string
+
+## ecmp-dst-port
+
+Destination port, as a string
+
+## ecmp-dst-member
+
+Destination ecmp member, as a string
+
+## port
+
+Associated port
+
+## ecmp-members
+
+An array of ecmp members. Each member is an object that contains an "ip", 
+"id", and "port" field.
+
+### Example
+
+    {"timestamp": 1416298504000.0, "name": "broadview.pt.packet-trace-profile", "value": 0, "dimensions": {"asic-id": "1", "realm": "ecmp-link-resolution", "ecmp-dst-member": "100005", "ignore-value": 1, "bv-agent": "10.14.244.199", "ecmp-dst-port": "41", "port": "1", "ecmp-members": [{"ip": "2.2.2.2", "id": "100004", "port": "28"}, {"ip": "6.6.6.1", "id": "100005", "port": "41"}], "ecmp-group-id": "200256", "ecmp-next-hop-ip": "6.6.6.2"}}
+
+
+packet-trace-lag-resolution 
+---------------------------
+
+This report can be invoked to report lag-link-resolution.
+
+# value - ignored for this report
+
+# dimensions 
+
+## ignore-value
+
+Always 1 for this report
+
+The following dimensions are for lag-link-resolution only.
+
+## lag-id
+
+The lag ID 
+
+## lag-members
+
+An array of lag member strings
+
+## dst-lag-member
+
+Destination lag member, as a string
+
+## port
+
+Associated port
+
+### Example
+
+    {"timestamp": 1468367668000.0, "name": "broadview.pt.packet-trace-lag-resolution", "value": 0, "dimensions": {"lag-id": "1", "asic-id": "1", "ignore-value": 1, "bv-agent": "10.14.244.199", "lag-members": ["1", "2", "3", "4"], "dst-lag-member": "4", "port": "1"}}
+
+packet-trace-ecmp-resolution
+----------------------------
+
+This report can be invoked to report ecmp-resolution
+
+# value - ignored for this report
+
+# dimensions 
+
+## ignore-value
+
+Always 1 for this report
+
+## ecmp-next-hop-ip
+
+The IPV4 address of the ecmp next hop
+
+## ecmp-group-id
+
+ecmp group ID, as a string
+
+## ecmp-dst-port
+
+Destination port, as a string
+
+## ecmp-dst-member
+
+Destination ecmp member, as a string
+
+## port
+
+Associated port
+
+## ecmp-members
+
+An array of ecmp members. Each member is an object that contains an "ip",
+"id", and "port" field.
+
+### Example
+
+    {"timestamp": 1468367675000.0, "name": "broadview.pt.packet-trace-ecmp-resolution", "value": 0, "dimensions": {"asic-id": "1", "ecmp-dst-member": "100005", "ignore-value": 1, "bv-agent": "10.14.244.199", "ecmp-dst-port": "41", "port": "1", "ecmp-members": [{"ip": "2.2.2.2", "id": "100004", "port": "28"}, {"ip": "6.6.6.1", "id": "100005", "port": "41"}], "ecmp-group-id": "200256", "ecmp-next-hop-ip": "6.6.6.2"}}
+
+packet-trace-drop-reason 
+------------------------
+
+This report contains the following data
+
+# value - the number of packets dropped
+
+# dimensions 
+
+## ignore-value
+
+Always 0 for this report
+
+## reason
+
+A string providing the reason for the packet drop
+
+## trace-profile
+
+The associated trace profile flag for the report, true or false
+
+## send-dropped-packet
+
+The associated send dropped packet flag for the report, true or false
+
+## packet-threshold
+
+The associated packet threshold
+
+## port-list
+
+An array of associated ports, each member a string
+
+### Example
+
+    {"timestamp": 1468392886000000, "name": "broadview.pt.packet-trace-drop-reason", "value": 3, "dimensions": {"asic-id": "1", "port-list": ["1", "5", "6", "10-15"], "send-dropped-packet": true, "ignore-value": 0, "bv-agent": "10.14.244.199", "trace-profile": false, "reason": "l2-lookup-failure", "packet-threshold": 0}}
+
+packet-trace-drop-counter-report 
+--------------------------------
+
+This report profiles a packet drop counter report for a specific drop
+realm
+
+# value - the drop count
+
+# dimensions 
+
+## ignore-value
+
+Always 0 for this report
+
+## realm
+
+The type of the drop, as a text string
+
+## port
+
+Associated port
+
+### Example
+
+    {"timestamp": 1468392895000000, "name": "broadview.pt.packet-trace-drop-counter-report", "value": 10, "dimensions": {"asic-id": "1", "ignore-value": 0, "realm": "vlan-xlate-miss-drop", "port": "1", "bv-agent": "10.14.244.199"}}
+