Clarify distribution summary docs #182
Conversation
…ist-max's inability to aggregate
|
|
||
| @@@ atlas-stacklang | ||
| /api/v1/graph?q=nf.cluster,foo,:eq,name,http.req.payload.size,:eq,:and,:dist-max,(,nf.asg,),:by | ||
| @@@ | ||
|
|
||
| !!! Note | ||
| Distribution summaries do not aggregate well over dimensions. Each measurement is recorded with a mapping of tags. |
There was a problem hiding this comment.
This doesn't really have anything to do with :dist-max specifically, it should probably be moved to the initial section or possibly just as a warning in the IPC spec for the inflight stuff. Distribution summaries aggregate just fine is used as intended, i.e. summarizing recorded samples such as payload sizes for requests. The :dist-max will be the maximum recorded sample that matches the query criteria. The :dist-avg will be the average of the recorded samples that match the query criteria. Possible rewording:
Distribution summaries are intended for use-cases tracking the size of recorded samples. For example, request payload sizes to understand the average or maximum recorded payload size for a given scope. It should not be used for use-cases trying to perform hierarchical accumulation such as number of inflight requests across different levels.
There was a problem hiding this comment.
I moved this to the IPC spec for inflight metrics, and modified the wording to include some of your rewording. I don't want to make it sound like we shouldn't use distribution summary at all for inflight metrics, since we aren't deprecating it (for now). I still think it can be useful for customers to see the dist-max on certain filters, but we've added new dashboards for queueing approximation.
| @@ -38,12 +38,17 @@ To compute the average latency across an arbitrary group, use the [:dist-avg] fu | |||
|
|
|||
| ### Maximum Measurement (:dist-max) | |||
|
|
|||
| To compute the maximum latency across a group, use [:dist-max]: | |||
| To compute the maximum size across a group, use [:dist-max]: | |||
…stribution summary spec
docs/spectator/specs/ipc.md
Outdated
| Distribution summaries are not suitable for use-cases trying to perform hierarchical accumulation across dimensions. | ||
| Each measurement is recorded with a certain set of dimensions, as illustrated below with the inflight metric. | ||
| Therefore, when using the [:dist-max] operator to query over a set of filters, the response will represent the | ||
| maximum inflight count for a given set of tag values within the group, **not** the accumulate value of measurements |
There was a problem hiding this comment.
s/accumulate/accumulated/
dist-maxfor the inflight metric