Understanding Spring Boot actuator `http.server.requests` metrics MAX attribute

Question

can someone explain what does the MAX statistic refers to in the below response. I don't see it documented anywhere.

localhost:8081/actuator/metrics/http.server.requests?tag=uri:/myControllerMethod

Response:

{  
   "name":"http.server.requests",
   "description":null,
   "baseUnit":"milliseconds",
   "measurements":[  
      {  
         "statistic":"COUNT",
         "value":13
      },
      {  
         "statistic":"TOTAL_TIME",
         "value":57.430899
      },
      {  
         "statistic":"MAX",
         "value":0
      }
   ],
   "availableTags":[  
      {  
         "tag":"exception",
         "values":[  
            "None"
         ]
      },
      {  
         "tag":"method",
         "values":[  
            "GET"
         ]
      },
      {  
         "tag":"outcome",
         "values":[  
            "SUCCESS"
         ]
      },
      {  
         "tag":"status",
         "values":[  
            "200"
         ]
      },
      {  
         "tag":"commonTag",
         "values":[  
            "somePrefix"
         ]
      }
   ]
}

buræquete · Accepted Answer · 2019-07-31T07:42:14.620

3

You can see the individual metrics by using ?tag=url:{endpoint_tag} as defined in the response of the root /actuator/metrics/http.server.requests call. The details of the measurements values are;

COUNT: Rate per second for calls.
TOTAL_TIME: The sum of the times recorded. Reported in the monitoring system's base unit of time

MAX: The maximum amount recorded. When this represents a time, it is reported in the monitoring system's base unit of time.

As given here, also here.

The discrepancies you are seeing is due to the presence of a timer. Meaning after some time currently defined MAX value for any tagged metric can be reset back to 0. Can you add some new calls to /myControllerMethod then immediately do a call to /actuator/metrics/http.server.requests to see a non-zero MAX value for given tag?

This is due to the idea behind getting MAX metric for each smaller period. When you are seeing these metrics, you will be able to get an array of MAX values rather than a single value for a long period of time.

You can get to see this in action within Micrometer source code. There is a rotate() method focused on resetting the MAX value to create above described behaviour.

You can see this is called for every poll() call, which is triggered every some period for metric gathering.

edited Jul 31 '19 at 07:42

answered Jul 29 '19 at 05:26

buræquete

14,226
4
44
89

2

in my case `MAX` is always equal to zero, irrespective of the number of times the endpoint is invoked. – Rahul Gupta Jul 31 '19 at 05:43
@RahulGupta how about how recent was it since you last called the endpoint? Can you check the `MAX` value just after calling the endpoint? Also confirm the change in `COUNT` when you call, maybe you a are calling `/metrics/http.server.requests` endpoint with wrong tag? – buræquete Jul 31 '19 at 05:44
yeah I tried that too... but that also doesn't change anything. – Rahul Gupta Jul 31 '19 at 05:48
@RahulGupta that is weird, I tested on my endpoints, the behaviour was like that, after some time from last call, the `MAX` goes to `0`... You are sure that `COUNT` gets incremented when you call but `MAX` stays `0` ? – buræquete Jul 31 '19 at 05:49
I got the issue, since I had customised `@Timed` on my controller methods. I have not been looking into `/metrics/http.server.requests` endpoint but at the custom metrics endpoint and there this problem of `MAX` occurs. When I disabled the custom endpoint, I see the `MAX` to be working as expected. Any idea on what needs to be done to make `MAX` work on customized `@Timed' annotations? – Rahul Gupta Jul 31 '19 at 06:24
@RahulGupta what name did you give in your `@Timed` ? Can you pass the name of that as `tag` in your `/metrics/http.server.requests` call? It is a `name` tag rather than `uri` tag. I think all that stats go to that tag, rather than the endpoint itself maybe? Can you confirm this? If not I will test on my local also! – buræquete Jul 31 '19 at 06:29
its quite weird but now `MAX` is working as expected without changing anything in the customized `@Timed`. Thanks a lot for your help... – Rahul Gupta Jul 31 '19 at 06:52

Romil Patel · Answer 2 · 2019-10-15T18:32:36.153

What does MAX represent

MAX represents the maximum time taken to execute endpoint.

Analysis for /user/asset/getAllAssets

COUNT  TOTAL_TIME  MAX
5      115         17
6      122         17  (Execution Time = 122 - 115 = 17)
7      131         17  (Execution Time = 131 - 122 = 17)
8      187         56  (Execution Time = 187 - 131 = 56)  
9      204         56  From Now MAX will be 56 (Execution Time = 204 - 187 = 17)

Will MAX be 0 if we have less number of request (or 1 request) to the particular endpoint?

No number of request for particular endPoint does not affect the MAX (see Image from Spring Boot Admin)

When MAX will be 0

There is Timer which set the value 0. When the endpoint is not being called or executed for sometime Timer sets MAX to 0. Here approximate timer value is 2 minutes (120 seconds)

DistributionStatisticConfig has .expiry(Duration.ofMinutes(2)). which sets some measurements to 0 if there is no request has been made in between expiry time or rotate time.

How I have determined the timer value?

For that, I have taken 6 samples (executed the same endpoint for 6 times). For that, I have determined the time difference between the time of calling the endpoint - time for when MAX set back to zero

More Details

UPDATE

Document has been updated.

NOTE:

Max for basic DistributionSummary implementations such as CumulativeDistributionSummary, StepDistributionSummary is a time window max (TimeWindowMax).

It means that its value is the maximum value during a time window.

If the time window ends, it'll be reset to 0 and a new time window starts again.

Time window size will be the step size of the meter registry unless expiry in DistributionStatisticConfig is set to other value explicitly.

If you are wondering what is this awesome `Spring Boot Admin`, it's from [codecentric](https://github.com/codecentric/spring-boot-admin) and an excellent presentation can be found [here](https://www.youtube.com/watch?v=Ql1Gnz4L_-c). — jumping_monkey, Aug 29 '22 at 09:29

Understanding Spring Boot actuator `http.server.requests` metrics MAX attribute

2 Answers2