HISTOGRAM_BUCKETS

This element specifies bucket ranges for Prometheus histogram metrics.

Syntax

<HISTOGRAM_BUCKETS Name="histogram_label">value</HISTOGRAM_BUCKETS>

The Name attribute specifies the name of the histogram metric. Typically, this is a histogram Prometheus metric used by the GAS (see Histogram metrics).
The value is set by a resource in the GAS, for example $(res.prometheus.rq_application_duration.buckets).

Child elements

There are no child elements.

Usage

Use the HISTOGRAM_BUCKETS element to define bucket ranges for Prometheus histogram metrics. These buckets group response times into intervals, making it easier to analyze performance trends and visualize request durations. This helps you identify bottlenecks, optimize system behavior, and configure alerts when response times exceed expected thresholds.

When creating custom metrics, a histogram’s buckets must be set in the code. For an example, go to Example: create custom histogram for response size (kilobytes)

Tip:

When defining bucket values, it is advised to base them on the expected response time required by the GAS and to define them as log (not linear).

Usage example in the as.xcf

The GAS uses separate histogram bucket sets for applications, web services, and static-file requests to reflect their differing response-time characteristics. Services typically respond faster and require tighter, more precise buckets, while applications and static files benefit from wider buckets to capture longer and more variable durations.

Named bucket sets are defined using RESOURCE elements. The HISTOGRAM_BUCKETS element assigns a bucket set to a Prometheus metric. (Line breaks have been added to improve readability.)


<RESOURCE Id="res.prometheus.rq_application_duration.buckets" 
   Source="INTERNAL">0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0</RESOURCE>
#...
 <PROMETHEUS Enabled="$(res.prometheus.enabled)">
    <COLLECTOR Address="$(res.prometheus.address)" Port="$(res.prometheus.port)" />
     <HISTOGRAM_BUCKETS Name="fourjs_gas_application_request_duration_seconds">
        $(res.prometheus.rq_application_duration.buckets)</HISTOGRAM_BUCKETS>
     <HISTOGRAM_BUCKETS Name="fourjs_gas_service_request_duration_seconds">
        $(res.prometheus.rq_service_duration.buckets)</HISTOGRAM_BUCKETS>
     <HISTOGRAM_BUCKETS Name="fourjs_gas_static_request_duration_seconds">
        $(res.prometheus.rq_static_duration.buckets)</HISTOGRAM_BUCKETS>
 </PROMETHEUS>

Explanation:

Name: fourjs_gas_application_request_duration_seconds — the built-in GAS histogram metric for application request duration (see Histogram metrics).
Value: $(res.prometheus.rq_application_duration.buckets) — references a resource in the GAS configuration file that supplies the bucket ranges.
res.prometheus.rq_application_duration.buckets measures application response times (in seconds) using the following buckets:
```
0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0
```
Interpretation:
- 0.005s (5 ms) to 0.1s (100 ms): very fast to good response times.
- 0.25s (250 ms) to 0.5s (500 ms): noticeable delays that are acceptable but could be improved.
- 1.0s (1000 ms) and above: long delays likely to negatively impact user experience.
The other bucket sets (res.prometheus.rq_service_duration.buckets and res.prometheus.rq_static_duration.buckets) follow the same structure and are tailored to the expected response times of services and static-file requests.

Example: create custom histogram for response size (kilobytes)

Code (myApp.4gl):

IMPORT prometheus
-- Import the Prometheus API

MAIN
    DEFINE histogram prometheus.Histogram
    LET histogram = prometheus.Histogram.create(
        "my_app_response_size_kilobytes",
        "histogram response size (kilobytes)",
        [1,4,16,64,256,512,1024],
        []
    )

    # ... program code
    CALL histogram.observe(17, [])  -- Observe a value (KB)
    # ... program code
END MAIN

Explanation:

my_app_response_size_kilobytes — metric recording response sizes (kilobytes).
Buckets (KB): 1, 4, 16, 64, 256, 512, 1024 — show how many responses fall under each size (for example, under 16 KB, under 256 KB).
Use histogram.observe(value_kb, labels) to record a single observation (value in KB); labels is an empty array [] here. Refer to the The prometheus package section of the Genero Business Development Language User Guide for full API details.
This metric shows whether responses are typically small (1–16 KB), medium (64–256 KB), or large (512 KB+).
Large or growing response sizes often point to backend issues, such as database queries returning many rows, extra columns (large text/BLOBs), missing filters or LIMIT, and similar problems.
Add more buckets where most responses fall (for example, 8 and 32 KB if many responses are between 4 and 64 KB).

Parent elements

This element is a child of PROMETHEUS.