Skip to content

Commit 0de96f5

Browse files
tothmanotothmano
authored
Fix rate docs (#118)
1 parent 2c12471 commit 0de96f5

File tree

1 file changed

+57
-39
lines changed

1 file changed

+57
-39
lines changed

‎apl/aggregation-function/rate.mdx

Lines changed: 57 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -17,13 +17,13 @@ If you come from other query languages, this section explains how to adjust your
1717
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.
1818

1919
<CodeGroup>
20-
```splunk
21-
| timechart per_second count by status
20+
```splunk Splunk example
21+
| timechart per_second count by resp_body_size_bytes
2222
```
2323

24-
```kusto
24+
```kusto APL equivalent
2525
['sample-http-logs']
26-
| summarize rate=count() by status, bin(_time, 1s)
26+
| summarize rate(resp_body_size_bytes) by bin(_time, 1s)
2727
```
2828
</CodeGroup>
2929

@@ -33,15 +33,14 @@ In Splunk SPL, the equivalent of the `rate` function can be achieved using the `
3333
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.
3434

3535
<CodeGroup>
36-
```sql
37-
SELECT status, COUNT(*) / TIMESTAMPDIFF(SECOND, MIN(_time), MAX(_time)) AS rate
38-
FROM http_logs
39-
GROUP BY status;
36+
```sql SQL example
37+
SELECT resp_body_size_bytes, COUNT(*) / TIMESTAMPDIFF(SECOND, MIN(_time), MAX(_time)) AS rate
38+
FROM http_logs;
4039
```
4140

42-
```kusto
41+
```kusto APL equivalent
4342
['sample-http-logs']
44-
| summarize rate=count() by status, bin(_time, 1s)
43+
| summarize rate(resp_body_size_bytes) by bin(_time, 1s)
4544
```
4645
</CodeGroup>
4746

@@ -53,88 +52,107 @@ GROUP BY status;
5352
### Syntax
5453

5554
```kusto
56-
rate(field, timeInterval)
55+
rate(field)
5756
```
5857

5958
### Parameters
6059

61-
- `field`: The numeric field that you want to calculate the rate for.
62-
- `timeInterval`: The time interval (e.g., 1s, 1m, 1h) over which to calculate the rate.
60+
- `field`: The numeric field for which you want to calculate the rate.
6361

6462
### Returns
6563

66-
Returns the rate of change or occurrence of the specified `field` over the specified `timeInterval`.
64+
Returns the rate of change or occurrence of the specified `field` over the time interval specified in the query.
65+
66+
Specify the time interval in the query in the following way:
67+
68+
- `| summarize rate(field)` calculates the rate value of the field over the entire query window.
69+
- `| summarize rate(field) by bin(_time, 1h)` calculates the rate value of the field over a one-hour time window.
70+
- `| summarize rate(field) by bin_auto(_time)` calculates the rate value of the field bucketed by an automatic time window computed by `bin_auto()`.
71+
72+
<Tip>
73+
74+
Use two `summarize` statements to visualize the average rate over one minute per hour. For example:
75+
76+
```kusto
77+
['sample-http-logs']
78+
| summarize respBodyRate = rate(resp_body_size_bytes) by bin(_time, 1m)
79+
| summarize avg(respBodyRate) by bin(_time, 1h)
80+
```
81+
82+
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?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)
83+
84+
</Tip>
6785

6886
## Use case examples
6987

7088
<Tabs>
7189
<Tab title="Log analysis">
7290

73-
In this example, the `rate` aggregation calculates the rate of HTTP requests per second grouped by status.
91+
In this example, the `rate` aggregation calculates the rate of HTTP response sizes per second.
7492

7593
**Query**
7694

7795
```kusto
7896
['sample-http-logs']
79-
| summarize rate=count() by status, bin(_time, 1s)
97+
| summarize rate(resp_body_size_bytes) by bin(_time, 1s)
8098
```
8199

82-
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%20%7C%20summarize%20rate%3Dcount%28%29%20by%20status%2C%20bin%28_time%2C%201s%29%22%7D)
100+
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?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)
83101

84102
**Output**
85103

86-
| status | rate | _time |
87-
|--------|-------|--------------------|
88-
| 200 | 15 | 2024-01-01 12:00:00|
89-
| 404 | 3 | 2024-01-01 12:00:00|
104+
| rate | _time |
105+
|-------|--------------------|
106+
| 854 kB | 2024-01-01 12:00:00|
107+
| 635 kB | 2024-01-01 12:00:01|
90108

91-
This query counts the number of requests per status code and calculates the rate of requests per second.
109+
This query calculates the rate of HTTP response sizes per second.
92110

93111
</Tab>
94112
<Tab title="OpenTelemetry traces">
95113

96-
This example calculates the rate of traces received per second for different services.
114+
This example calculates the rate of span duration per second.
97115

98116
**Query**
99117

100118
```kusto
101119
['otel-demo-traces']
102-
| summarize rate=count() by ['service.name'], bin(_time, 1s)
120+
| summarize rate(toint(duration)) by bin(_time, 1s)
103121
```
104122

105-
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27otel-demo-traces%27%5D%20%7C%20summarize%20rate%3Dcount%28%29%20by%20%5B%27service.name%27%5D%2C%20bin%28_time%2C%201s%29%22%7D)
123+
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'otel-demo-traces'%5D%20%7C%20summarize%20rate(toint(duration))%20by%20bin(_time%2C%201s)%22%7D)
106124

107125
**Output**
108126

109-
| service.name | rate | _time |
110-
|----------------------|-------|--------------------|
111-
| frontend | 10 | 2024-01-01 12:00:00|
112-
| checkoutservice | 5 | 2024-01-01 12:00:00|
127+
| rate | _time |
128+
|-------|--------------------|
129+
| 26,393,768 | 2024-01-01 12:00:00|
130+
| 19,303,456 | 2024-01-01 12:00:01|
113131

114-
This query calculates the rate of traces per second for each service.
132+
This query calculates the rate of span duration per second.
115133

116134
</Tab>
117135
<Tab title="Security logs">
118136

119-
In this example, the `rate` aggregation calculates the rate of security events by HTTP status.
137+
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.
120138

121139
**Query**
122140

123141
```kusto
124142
['sample-http-logs']
125-
| summarize rate=count() by status, bin(_time, 1s)
143+
| summarize rate(req_duration_ms) by bin(_time, 1s)
126144
```
127145

128-
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%20%7C%20summarize%20rate%3Dcount%28%29%20by%20status%2C%20bin%28_time%2C%201s%29%22%7D)
146+
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?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)
129147

130148
**Output**
131149

132-
| status | rate | _time |
133-
|--------|-------|--------------------|
134-
| 401 | 8 | 2024-01-01 12:00:00|
135-
| 403 | 2 | 2024-01-01 12:00:00|
150+
| rate | _time |
151+
|-------|--------------------|
152+
| 240.668 ms | 2024-01-01 12:00:00|
153+
| 264.17 ms | 2024-01-01 12:00:01|
136154

137-
This query calculates the rate of different security-related status codes over time.
155+
This query calculates the rate of HTTP request duration per second.
138156

139157
</Tab>
140158
</Tabs>
@@ -145,4 +163,4 @@ This query calculates the rate of different security-related status codes over t
145163
- [**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.
146164
- [**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.
147165
- [**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.
148-
- [**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.
166+
- [**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.

0 commit comments

Comments
 (0)