=================
 Perf histograms
=================

The perf histograms build on perf counters infrastructure. Histograms are built for a number of counters and simplify gathering data on which groups of counter values occur most often over time. 
Perf histograms are currently unsigned 64-bit integer counters, so they're mostly useful for time and sizes. Data dumped by perf histogram can then be feed into other analysis tools/scripts.

Access
------

The perf histogram data are accessed via the admin socket.  For example::

   ceph daemon osd.0 perf histogram schema
   ceph daemon osd.0 perf histogram dump


Collections
-----------

The histograms are grouped into named collections, normally representing a subsystem or an instance of a subsystem.  For example, the internal ``throttle`` mechanism reports statistics on how it is throttling, and each instance is named something like::


    op_r_latency_out_bytes_histogram
    op_rw_latency_in_bytes_histogram
    op_rw_latency_out_bytes_histogram
    ...


Schema
------

The ``perf histogram schema`` command dumps a json description of which values are available, and what their type is.  Each named value as a ``type`` bitfield, with the 5-th bit always set and following bits defined.

+------+-------------------------------------+
| bit  | meaning                             |
+======+=====================================+
| 1    | floating point value                |
+------+-------------------------------------+
| 2    | unsigned 64-bit integer value       |
+------+-------------------------------------+
| 4    | average (sum + count pair)          |
+------+-------------------------------------+
| 8    | counter (vs gauge)                  |
+------+-------------------------------------+

In other words, histogram of type "18" is a histogram of unsigned 64-bit integer values (16 + 2).

Here is an example of the schema output::

{
    "AsyncMessenger::Worker-0": {},
    "AsyncMessenger::Worker-1": {},
    "AsyncMessenger::Worker-2": {},
    "mutex-WBThrottle::lock": {},
    "objecter": {},
    "osd": {
        "op_r_latency_out_bytes_histogram": {
            "type": 18,
            "description": "Histogram of operation latency (including queue time) + data read",
            "nick": ""
        },
        "op_w_latency_in_bytes_histogram": {
            "type": 18,
            "description": "Histogram of operation latency (including queue time) + data written",
            "nick": ""
        },
        "op_rw_latency_in_bytes_histogram": {
            "type": 18,
            "description": "Histogram of rw operation latency (including queue time) + data written",
            "nick": ""
        },
        "op_rw_latency_out_bytes_histogram": {
            "type": 18,
            "description": "Histogram of rw operation latency (including queue time) + data read",
            "nick": ""
        }
    }
}


Dump
----

The actual dump is similar to the schema, except that there are actual value groups.  For example::

    "osd": {
        "op_r_latency_out_bytes_histogram": {
            "axes": [
                {
                    "name": "Latency (usec)",
                    "min": 0,
                    "quant_size": 100000,
                    "buckets": 32,
                    "scale_type": "log2",
                    "ranges": [
                        {
                            "max": -1
                        },
                        {
                            "min": 0,
                            "max": 99999
                        },
                        {
                            "min": 100000,
                            "max": 199999
                        },
                        {
                            "min": 200000,
                            "max": 399999
                        },
                        {
                            "min": 400000,
                            "max": 799999
                        },
                        {
                            "min": 800000,
                            "max": 1599999
                        },
                        {
                            "min": 1600000,
                            "max": 3199999
                        },
                        {
                            "min": 3200000,
                            "max": 6399999
                        },
                        {
                            "min": 6400000,
                            "max": 12799999
                        },
                        {
                            "min": 12800000,
                            "max": 25599999
                        },
                        {
                            "min": 25600000,
                            "max": 51199999
                        },
                        {
                            "min": 51200000,
                            "max": 102399999
                        },
                        {
                            "min": 102400000,
                            "max": 204799999
                        },
                        {
                            "min": 204800000,
                            "max": 409599999
                        },
                        {
                            "min": 409600000,
                            "max": 819199999
                        },
                        {
                            "min": 819200000,
                            "max": 1638399999
                        },
                        {
                            "min": 1638400000,
                            "max": 3276799999
                        },
                        {
                            "min": 3276800000,
                            "max": 6553599999
                        },
                        {
                            "min": 6553600000,
                            "max": 13107199999
                        },
                        {
                            "min": 13107200000,
                            "max": 26214399999
                        },
                        {
                            "min": 26214400000,
                            "max": 52428799999
                        },
                        {
                            "min": 52428800000,
                            "max": 104857599999
                        },
                        {
                            "min": 104857600000,
                            "max": 209715199999
                        },
                        {
                            "min": 209715200000,
                            "max": 419430399999
                        },
                        {
                            "min": 419430400000,
                            "max": 838860799999
                        },
                        {
                            "min": 838860800000,
                            "max": 1677721599999
                        },
                        {
                            "min": 1677721600000,
                            "max": 3355443199999
                        },
                        {
                            "min": 3355443200000,
                            "max": 6710886399999
                        },
                        {
                            "min": 6710886400000,
                            "max": 13421772799999
                        },
                        {
                            "min": 13421772800000,
                            "max": 26843545599999
                        },
                        {
                            "min": 26843545600000,
                            "max": 53687091199999
                        },
                        },
                        {
                            "min": 53687091200000
                        }
                    ]
                },
                {
                    "name": "Request size (bytes)",
                    "min": 0,
                    "quant_size": 512,
                    "buckets": 32,
                    "scale_type": "log2",
                    "ranges": [
                        {
                            "max": -1
                        },
                        {
                            "min": 0,
                            "max": 511
                        },
                        {
                            "min": 512,
                            "max": 1023
                        },
                        {
                            "min": 1024,
                            "max": 2047
                        },
                        {
                            "min": 2048,
                            "max": 4095
                        },
                        {
                            "min": 4096,
                            "max": 8191
                        },
                        {
                            "min": 8192,
                            "max": 16383
                        },
                        {
                            "min": 16384,
                            "max": 32767
                        },
                        {
                            "min": 32768,
                            "max": 65535
                        },
                        {
                            "min": 65536,
                            "max": 131071
                        },
                        {
                            "min": 131072,
                            "max": 262143
                        },
                        {
                            "min": 262144,
                            "max": 524287
                        },
                        {
                            "min": 524288,
                            "max": 1048575
                        },
                        {
                            "min": 1048576,
                            "max": 2097151
                        },
                        {
                            "min": 2097152,
                            "max": 4194303
                        },
                        {
                            "min": 4194304,
                            "max": 8388607
                        },
                        {
                            "min": 8388608,
                            "max": 16777215
                        },
                        {
                            "min": 16777216,
                            "max": 33554431
                        },
                        {
                            "min": 33554432,
                            "max": 67108863
                        },
                        {
                            "min": 67108864,
                            "max": 134217727
                        },
                        {
                            "min": 134217728,
                            "max": 268435455
                        },
                        {
                            "min": 268435456,
                            "max": 536870911
                        },
                        {
                            "min": 536870912,
                            "max": 1073741823
                        },
                        {
                            "min": 1073741824,
                            "max": 2147483647
                        },
                        {
                            "min": 2147483648,
                            "max": 4294967295
                        },
                        {
                            "min": 4294967296,
                            "max": 8589934591
                        },
                        {
                            "min": 8589934592,
                            "max": 17179869183
                        },
                        {
                            "min": 17179869184,
                            "max": 34359738367
                        },
                        {
                            "min": 34359738368,
                            "max": 68719476735
                        },
                        {
                            "min": 68719476736,
                            "max": 137438953471
                        },
                        {
                            "min": 137438953472,
                            "max": 274877906943
                        },
                        {
                            "min": 274877906944
                        }
                    ]
                }
            ],
            "values": [
                [
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0
                ],
                [
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0
                ],
                [
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0
                ],
                [
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0
                ],
                [
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0
                ],
                [
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0
                ],
                [
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0
                ],
                [
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0
                ],
                [
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0
                ]
            ]
        }
    },

This represents the 2d histogram, consisting of 9 history entrires and 32 value groups per each history entry. 
"Ranges" element denote value bounds for each of value groups. "Buckets" denote amount of value groups ("buckets"), 
"Min" is a minimum accepted valaue, "quant_size" is quantization unit and "scale_type" is either "log2" (logarhitmic
scale) or "linear" (linear scale).
You can use histogram_dump.py tool (see src/tools/histogram_dump.py) for quick visualisation of existing histogram
data.