feat: add a how section

Signed-off-by: Manik Rana <[email protected]>

proposals/2024-12-14_update-created-timestamps-for-openmetrics-text.md

@@ -51,6 +51,67 @@ As stated above, `_created`  lines can appear anywhere after its associated metr
 
 ## How
 
+We store the Created Timestamp inline with the metric it is attached to and we remove `_created` lines. This will allow the parser to immediately associate the CT with the metric without having to search for it. For counters its straightforward as we can just add the timestamp after the metric value like an exemplar. To separate it from a traditional timstamp we can prefix the created timestamp with something like `ct@`, although this portion of the syntax is not final and can be changed. Furthermore, we can order the created timestamp such that it is after the metric value + timestamp and before an exemplar.
+
+Lets look at some examples to illustrate the difference.
+
+### Counters
+
+```
+# HELP foo Counter with and without labels to certify CT is parsed for both cases
+# TYPE foo counter
+foo_total 17.0 1520879607.789 [email protected] # {id="counter-test"} 5
+foo_total{a="b"} 17.0 1520879607.789 [email protected] # {id="counter-test"} 5
+foo_total{le="c"} 21.0 ct1520872621.123
+foo_total{le="1"} 10.0
+```
+
+vs the current syntax:
+
+```
+# HELP foo Counter with and without labels to certify CT is parsed for both cases
+# TYPE foo counter
+foo_total 17.0 1520879607.789 # {id="counter-test"} 5
+foo_created 1520872607.123
+foo_total{a="b"} 17.0 1520879607.789 # {id="counter-test"} 5
+foo_created{a="b"} 1520872607.123
+foo_total{le="c"} 21.0
+foo_created{le="c"} 1520872621.123
+foo_total{le="1"} 10.0
+```
+
+### Summaries and Histograms
+
+Summaries and histograms are a bit more complex as they have quantiles and buckets respectively. Moreoever, there is no defacto line like in a counter where we can place the CT. Thus, we can opt to place the CT on the first line of the metric with the same label set. We can then cache this timestamp with a hash of the label set and use it for all subsequent lines with the same label set. This is something we somewhat do already with the current syntax.
+
+A diff example (for brevity) of a summary metric with current vs proposed syntax:
+
+```diff
+# HELP rpc_durations_seconds RPC latency distributions.
+# TYPE rpc_durations_seconds summary
++rpc_durations_seconds{service="exponential",quantile="0.5"} 7.689368882420941e-07 [email protected]+09
+-rpc_durations_seconds{service="exponential",quantile="0.5"} 7.689368882420941e-07
+rpc_durations_seconds{service="exponential",quantile="0.9"} 1.6537614174305048e-06
+rpc_durations_seconds{service="exponential",quantile="0.99"} 2.0965499063061924e-06
+rpc_durations_seconds_sum{service="exponential"} 2.0318666372575776e-05
+rpc_durations_seconds_count{service="exponential"} 22
+-rpc_durations_seconds_created{service="exponential"} 1.7268398130168908e+09
+```
+
+With the current syntax `_created` line can be anywhere after the `quantile` lines. A histogram would look similar to the summary but with `le` labels instead of `quantile` labels.
+
+Another option is to simply place the CT on every line of a summary or histogram metric. This would be more verbose but would be more explicit and easier to parse and avoids storing the CT completely:
+
+```
+# HELP rpc_durations_seconds RPC latency distributions.
+# TYPE rpc_durations_seconds summary
++rpc_durations_seconds{service="exponential",quantile="0.5"} 7.689368882420941e-07 [email protected]+09
+rpc_durations_seconds{service="exponential",quantile="0.9"} 1.6537614174305048e-06 [email protected]+09
+rpc_durations_seconds{service="exponential",quantile="0.99"} 2.0965499063061924e-06 [email protected]+09
+rpc_durations_seconds_sum{service="exponential"} 2.0318666372575776e-05 [email protected]+09
+rpc_durations_seconds_count{service="exponential"} 22 [email protected]+09
+```
+
 ## Alternatives
 
 ### Do nothing