Contract: add heatmap format docs

[ryantxu]

This is a first attempt to write down more structured notes on heatmap format constraints.

[ryantxu]

@leeoniya is out this week... but will have more opinions for how to improve this :)

[kylebrandt]

For defining the "heatmap" kind, should we state that we exclude "geo spatial" map data from this kind? Seems like wikipedia calls this kind we are describing as "grid heap map". I think it is probably okay not to use "grid" and just call it heatmap and then in the geo case something like "spatial heap map" - but we should have a clear decision on if geo would be included in this kind (to which my guess is "no").

[ryantxu]

I think we can ignore geo for now -- we can either add a new kind more appropriate for geo, or perhaps allow the x values to be of type geo (that exists in the frontend, but not in the backend)

[kylebrandt]

"field display", metadata or field name?

[bohandley]

Is field display for the bucket label the same as the label object in a field?

For example, this field display would be
{__name__="go_gc_duration_seconds_sum", instance="localhost:9095", job="prometheus"}

{
          "name": "Value",
          "type": "number",
          "typeInfo": {
            "frame": "float64"
          },
          "labels": {
            "__name__": "go_gc_duration_seconds_sum",
            "instance": "localhost:9095",
            "job": "prometheus"
          },

but this one that has le could be described just by using the le label and doesn't need the whole field display?

"labels": {
            "__name__": "prometheus_http_request_duration_seconds_bucket",
            "handler": "/",
            "instance": "localhost:9095",
            "job": "prometheus",
            "le": "+Inf"
          },

Is this accurate @leeoniya?

[kylebrandt]

Is this case sensitive? I don't care if it is or not, just that we pick.

[bohandley]

In transformations, the case sensitivity is the same, I suggest with stick with lower case y and uppercase M, yMin, yMax

[kylebrandt]

I don't understand want this means...? Perhaps if expressed in terms of fields/rows?

[bohandley]

@ryantxu Perhaps, "This format requires uniform cell sizing. The size of the cell is defined by the columns in each row that are chosen as the xMax|xMin|x and the yMax|yMin|y. We can see that the Number column(yMax|yMin|y) increases by 100(each cell is roughly 100 higher than the previous cell on the y axis) for each row containing a similar Time value(these stacked cells all have roughly the same location along the x axis). This produces a uniform cell size."

[ryantxu]

@bohandley -- i just got everything in sync. Please work with @leeoniya to figure out what is accurate and feel free to push to this branch and update whatever we need to make it more clear

[kylebrandt]

trailing "when" ...

[bohandley]

Add a comparison from the uniformity of cells over time in scanlines to the variability of cells along the x axis(Time) for Heatmap sparse.

[kylebrandt]

All the examples have time - does there have to be Time, or can "X axis" be something else?

[CLAassistant]

All committers have signed the CLA.

[kylebrandt]

This was changed to numeric multi in recent PR https://github.com/grafana/grafana-plugin-sdk-go/pull/551/files

[bohandley]

LIke this?

     * [Multi](./timeseries.md#time-series-multi-format-timeseriesmulti)
* [Numeric](./numeric.md)
     * [Wide](./numeric.md#numeric-wide-format-numericwide)
     * [Multi](./numeric.md#numeric-many-format-numericmany)

[kylebrandt]

Suggested change

	* [Many](./numeric.md#numeric-many-format-numericmany)
	* [Multi](./numeric.md#numeric-multi-format-numericmulti)

[kylebrandt]

(Both Name and Link)

[bohandley]

Oh, got it, let me do that again