Explanation of Apdex calculation

[tdb-alcorn]

https://github.com/prometheus/docs/blob/main/content/docs/practices/histograms.md?plain=1#L93

The docs currently say:

Note that we divide the sum of both buckets. The reason is that the histogram buckets are cumulative. The le="0.3" bucket is also contained in the le="1.2" bucket; dividing it by 2 corrects for that.

This doesn't make sense - dividing by 2 has nothing to do with whether the histogram buckets are cumulative. Rather it looks like the 1/2 factor is meant as the weight of "tolerable" instances in the Apdex score. To correct for the fact that the le=1.2 bucket contains the le=0.3 bucket, you need to instead subtract the latter from the former.

[beorn7]

Since this question has come up several times before, I'll try to give a comprehensive explanation here.

The original formula for the Apdex score according to Wikipedia is:

        SatisfiedCount + (0.5 * ToleratingCount) + (0 * FrustratedCount)
Apdex = ----------------------------------------------------------------
                                  TotalSamples

FrustratedCount is multiplied away, so we don't need to query it in PromQL. Directly translating all the other components into PromQL yields the following, using the thresholds from the example (300ms target, 1.2s tolerated):

• SatisfiedCount → sum(rate(http_request_duration_seconds_bucket{le="0.3"}[5m])) by (job)
• ToleratingCount → sum(rate(http_request_duration_seconds_bucket{le="1.2"}[5m])) by (job) - sum(rate(http_request_duration_seconds_bucket{le="0.3"}[5m])) by (job)
• TotalSamples → sum(rate(http_request_duration_seconds_count[5m])) by (job)

As you can see, the translation of ToleratingCount follows your rationale of ”correct[ing] for the fact that the le=1.2 bucket contains the le=0.3 bucket, you need to instead subtract the latter from the former”.

Now we can construct the full humungus Apdex query, in canonical formatting:

  (
      sum by (job) (rate(http_request_duration_seconds_bucket{le="0.3"}[5m]))
    +
      (
          0.5
        *
          (
              sum by (job) (rate(http_request_duration_seconds_bucket{le="1.2"}[5m]))
            -
              sum by (job) (rate(http_request_duration_seconds_bucket{le="0.3"}[5m]))
          )
      )
  )
/
  sum by (job) (rate(http_request_duration_seconds_count[5m]))

Of course, we can use normal algebraic operations to simplify the query. First we can push the 0.5 * (...) factor into the subtraction:

  (
      sum by (job) (rate(http_request_duration_seconds_bucket{le="0.3"}[5m]))
    +
      (
          0.5 * sum by (job) (rate(http_request_duration_seconds_bucket{le="1.2"}[5m]))
        -
          0.5 * sum by (job) (rate(http_request_duration_seconds_bucket{le="0.3"}[5m]))
      )
  )
/
  sum by (job) (rate(http_request_duration_seconds_count[5m]))

Now it's easy to dissolve the + (...) parentheses:

  (
      sum by (job) (rate(http_request_duration_seconds_bucket{le="0.3"}[5m]))
    +
      0.5 * sum by (job) (rate(http_request_duration_seconds_bucket{le="1.2"}[5m]))
    -
      0.5 * sum by (job) (rate(http_request_duration_seconds_bucket{le="0.3"}[5m]))
  )
/
  sum by (job) (rate(http_request_duration_seconds_count[5m]))

Since sum by (job) (rate(http_request_duration_seconds_bucket{le="0.3"}[5m])) - 0.5 * sum by (job) (rate(http_request_duration_seconds_bucket{le="0.3"}[5m])) is nothing else but 0.5 * sum by (job) (rate(http_request_duration_seconds_bucket{le="0.3"}[5m])), we can also write:

  (
      0.5 * sum by (job) (rate(http_request_duration_seconds_bucket{le="1.2"}[5m]))
    +
      0.5 * sum by (job) (rate(http_request_duration_seconds_bucket{le="0.3"}[5m]))
  )
/
  sum by (job) (rate(http_request_duration_seconds_count[5m]))

Now we can pull the 0.5 * in front of the parentheses again:

    0.5
  *
    (
        sum by (job) (rate(http_request_duration_seconds_bucket{le="1.2"}[5m]))
      +
        sum by (job) (rate(http_request_duration_seconds_bucket{le="0.3"}[5m]))
    )
/
  sum by (job) (rate(http_request_duration_seconds_count[5m]))

Multiplying by 0.5 is the same as dividing by 2, so we can also write:

    (
        sum by (job) (rate(http_request_duration_seconds_bucket{le="1.2"}[5m]))
      +
        sum by (job) (rate(http_request_duration_seconds_bucket{le="0.3"}[5m]))
    )
  /
    2
/
  sum by (job) (rate(http_request_duration_seconds_count[5m]))

Which is precisely the query from the docs, just with different indentation and line breaks.
q.e.d.

[RichiH]

Thanks! I am wondering if we should add this to the docs, or make a footnote.

[beorn7]

I wouldn't put it into the "histograms & summaries" doc. It's too verbose and kind-of off topic. Not sure where it would fit. Perhaps here in the GH discussions is actually not too bad…

[tmcheung]

Would be great to have a link to this discussion in the docs so that you could read this if you are confused or curious about the details.

[beorn7]

If you search for "explanation of the apdex calculation in promql" with Google, you get this explanation. I would say that's good enough. Linking it creates noise for those that aren't interested or that are good enough in algebra to not even be confused. (Or to phrase it in a pointed way: I haven't linked math textbook above when I said "Now we can pull the 0.5 * in front of the parentheses again" etc.)