What does Prometheus summary.observe method do?

Question

I'm trying to play with summary metrics and not quiet understand where do I put summary.observe call? Here is prom-client example (you can find on npm):

    const client = require('prom-client');
    const summary = new client.Summary({
      name: 'metric_name',
      help: 'metric_help'
    });
    summary.observe(10);

but there is no enough info how to use it.

1. what does observe(10) mean?

2. where do I put that summary.observe(10) call? Just right after summary metric declaration or at the end of function/endpoint call like:

   const client = require('prom-client');
   
   const summary = new client.Summary({
     name: 'metric_name',
     help: 'metric_help'
   });
   summary.observe(10); // do I put it here?
   
   async myFunc(){
       await this.serviceCall();
       summary.observe(10); // or here?
   } 
   

Does anybody have a good example/explanation of summary observe?

Answer 1

First, let's clarify what an summary is: a summary metric captures individual observations from an event and summarizes them into a number of related metric:

1. a sum of values (aka observations)
2. observation count
3. quantiles

Taking an example: if you are measuring the response time of a service:

• first, you create a summary metrics providing

  • a name and labels (as usual to identify the metric) - ex: foobar_request_duration_seconds
  • usually some way to indicate the windows of measurements (number of observation or maximum age of events)
  • a list of quantiles to compute - ex: 0.1, 0.5 (median), 0.75, 0.9

• for each request, you will compute the response time of a request - this is an observation

• you then feed the computed request response time to the summary object

• when Prometheus scrapes you end-point, metrics are computed from the response time measures observed

  • foobar_request_duration_seconds_sum: total number of seconds consumed by requests
  • foobar_request_duration_seconds_count: number of requests (note you can compute average with sum)
  • foobar_request_duration_seconds_seconds{quantile="0.1"}: response time 10% (... same for all configured quantiles)

I hope this should help you understand the prom-client documentation:

The first example shows how to indicate the quantiles to compute

new client.Summary({
  name: 'metric_name',
  help: 'metric_help',
  percentiles: [0.01, 0.1, 0.9, 0.99]
});

The second how to limit the window of measurements; here, measure are computed over the last 10 minutes (using 5 buckets - this impacts smoothing of values):

new client.Summary({
  name: 'metric_name',
  help: 'metric_help',
  maxAgeSeconds: 600,
  ageBuckets: 5
});

Coming back to your question, the observe() method should be called on what you are observing.

If you want to measure some data returned by serviceCall(), you feed it to the summary

number_bytes_exchanged = await this.serviceCall();
summary.observe(number_bytes_exchanged);

If you want to measure the time taken by service call

const observe_response_time = summary.startTimer();
await this.serviceCall();
observe_response_time();