> ## Documentation Index
> Fetch the complete documentation index at: https://axiom.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# rate

> This page explains how to use the rate aggregation function in APL.

The `rate` aggregation function in APL (Axiom Processing Language) helps you calculate the rate of change over a specific time interval. This is especially useful for scenarios where you need to monitor how frequently an event occurs or how a value changes over time. For example, you can use the `rate` function to track request rates in web logs or changes in metrics like CPU usage or memory consumption.

The `rate` function is useful for analyzing trends in time series data and identifying unusual spikes or drops in activity. It can help you understand patterns in logs, metrics, and traces over specific intervals, such as per minute, per second, or per hour.

## For users of other query languages

If you come from other query languages, this section explains how to adjust your existing queries to achieve the same results in APL.

<AccordionGroup>
  <Accordion title="Splunk SPL users">
    In Splunk SPL, the equivalent of the `rate` function can be achieved using the `timechart` command with a `per_second` option or by calculating the difference between successive values over time. In APL, the `rate` function simplifies this process by directly calculating the rate over a specified time interval.

    <CodeGroup>
      ```splunk Splunk example theme={null}
      | timechart per_second count by resp_body_size_bytes
      ```

      ```kusto APL equivalent theme={null}
      ['sample-http-logs']
      | summarize rate(resp_body_size_bytes) by bin(_time, 1s)
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="ANSI SQL users">
    In ANSI SQL, calculating rates typically involves using window functions like `LAG` or `LEAD` to calculate the difference between successive rows in a time series. In APL, the `rate` function abstracts this complexity by allowing you to directly compute the rate over time without needing window functions.

    <CodeGroup>
      ```sql SQL example theme={null}
      SELECT resp_body_size_bytes, COUNT(*) / TIMESTAMPDIFF(SECOND, MIN(_time), MAX(_time)) AS rate
      FROM http_logs;
      ```

      ```kusto APL equivalent theme={null}
      ['sample-http-logs']
      | summarize rate(resp_body_size_bytes) by bin(_time, 1s)
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

## Usage

### Syntax

```kusto theme={null}
rate(field)
```

### Parameters

* `field`: The numeric field for which you want to calculate the rate.

### Returns

Returns the rate of change or occurrence of the specified `field` over the time interval specified in the query.

Specify the time interval in the query in the following way:

* `| summarize rate(field)` calculates the rate value of the field over the entire query window.
* `| summarize rate(field) by bin(_time, 1h)` calculates the rate value of the field over a one-hour time window.
* `| summarize rate(field) by bin_auto(_time)` calculates the rate value of the field bucketed by an automatic time window computed by `bin_auto()`.

<Tip>
  Use two `summarize` statements to visualize the average rate over one minute per hour. For example:

  ```kusto theme={null}
  ['sample-http-logs']
  | summarize respBodyRate = rate(resp_body_size_bytes) by bin(_time, 1m)
  | summarize avg(respBodyRate) by bin(_time, 1h)
  ```

  [Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B'sample-http-logs'%5D%20%7C%20summarize%20respBodyRate%20%3D%20rate\(resp_body_size_bytes\)%20by%20bin\(_time%2C%201m\)%20%7C%20summarize%20avg\(respBodyRate\)%20by%20bin\(_time%2C%201h\)%22%2C%20%22queryOptions%22%3A%7B%22quickRange%22%3A%226h%22%7D%7D)
</Tip>

## Use case examples

<Tabs>
  <Tab title="Log analysis">
    In this example, the `rate` aggregation calculates the rate of HTTP response sizes per second.

    **Query**

    ```kusto theme={null}
    ['sample-http-logs']
    | summarize rate(resp_body_size_bytes) by bin(_time, 1s)
    ```

    [Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B'sample-http-logs'%5D%20%7C%20summarize%20rate\(resp_body_size_bytes\)%20by%20bin\(_time%2C%201s\)%22%7D)

    **Output**

    | rate   | \_time              |
    | ------ | ------------------- |
    | 854 kB | 2024-01-01 12:00:00 |
    | 635 kB | 2024-01-01 12:00:01 |

    This query calculates the rate of HTTP response sizes per second.
  </Tab>

  <Tab title="OpenTelemetry traces">
    This example calculates the rate of span duration per second.

    **Query**

    ```kusto theme={null}
    ['otel-demo-traces']
    | summarize rate(toint(duration)) by bin(_time, 1s)
    ```

    [Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B'otel-demo-traces'%5D%20%7C%20summarize%20rate\(toint\(duration\)\)%20by%20bin\(_time%2C%201s\)%22%7D)

    **Output**

    | rate       | \_time              |
    | ---------- | ------------------- |
    | 26,393,768 | 2024-01-01 12:00:00 |
    | 19,303,456 | 2024-01-01 12:00:01 |

    This query calculates the rate of span duration per second.
  </Tab>

  <Tab title="Security logs">
    In this example, the `rate` aggregation calculates the rate of HTTP request duration per second which can be useful to detect an increate in malicious requests.

    **Query**

    ```kusto theme={null}
    ['sample-http-logs']
    | summarize rate(req_duration_ms) by bin(_time, 1s)
    ```

    [Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B'sample-http-logs'%5D%20%7C%20summarize%20rate\(req_duration_ms\)%20by%20bin\(_time%2C%201s\)%22%7D)

    **Output**

    | rate       | \_time              |
    | ---------- | ------------------- |
    | 240.668 ms | 2024-01-01 12:00:00 |
    | 264.17 ms  | 2024-01-01 12:00:01 |

    This query calculates the rate of HTTP request duration per second.
  </Tab>
</Tabs>

## List of related aggregations

* [**count**](/apl/aggregation-function/count): Returns the total number of records. Use `count` when you want an absolute total instead of a rate over time.
* [**sum**](/apl/aggregation-function/sum): Returns the sum of values in a field. Use `sum` when you want to aggregate the total value, not its rate of change.
* [**avg**](/apl/aggregation-function/avg): Returns the average value of a field. Use `avg` when you want to know the mean value rather than how it changes over time.
* [**max**](/apl/aggregation-function/max): Returns the maximum value of a field. Use `max` when you need to find the peak value instead of how often or quickly something occurs.
* [**min**](/apl/aggregation-function/min): Returns the minimum value of a field. Use `min` when you’re looking for the lowest value rather than a rate.