ago
This page explains how to use the ago function in APL.
Use the ago function in APL to subtract a given timespan from the current UTC clock time. The function returns a datetime value equal to now() - timespan.
You can use ago to create relative time filters that adapt automatically to the current time. This is especially useful for dashboards, alerts, and ad-hoc investigations where you want to focus on recent activity without hardcoding timestamps.
Use it when you want to:
- Filter events that occurred within a recent time window.
- Create dynamic time-based thresholds for alerting or anomaly detection.
- Compare current activity against a rolling baseline period.
Usage
Syntax
ago(timespan)Parameters
| Name | Type | Description |
|---|---|---|
| timespan | timespan | The timespan to subtract from the current UTC time. |
Returns
A datetime value equal to now() - timespan.
Use case examples
Filter HTTP logs from the last 6 hours and count requests by status code.
Query
['sample-http-logs']
| where _time > ago(6h)
| summarize count() by statusOutput
| status | count_ |
|---|---|
| 200 | 1523 |
| 404 | 87 |
| 500 | 34 |
This query filters log entries to the last 6 hours and groups them by HTTP status code to give a quick overview of recent traffic health.
Find slow traces from the last day and count them by service name.
Query
['otel-demo-traces']
| where _time > ago(1d)
| where duration > 1s
| summarize count() by ['service.name']Output
| ['service.name'] | count_ |
|---|---|
| frontend | 42 |
| checkout | 15 |
| cart | 8 |
This query identifies services with slow spans (over 1 second) in the last 24 hours, helping you pinpoint performance bottlenecks.
Detect high error rates in the last 12 hours by counting client and server errors per hour.
Query
['sample-http-logs']
| where _time > ago(12h)
| where toint(status) >= 400
| summarize error_count = count() by bin(_time, 1h)Output
| _time | error_count |
|---|---|
| 2025-01-15T00:00:00Z | 12 |
| 2025-01-15T01:00:00Z | 45 |
| 2025-01-15T02:00:00Z | 9 |
This query bins error responses into hourly buckets over the last 12 hours, making it easy to spot sudden spikes in failures.
List of related functions
- now: Returns the current UTC time. Use
nowwhen you need the absolute current time rather than a relative offset. - datetime_add: Adds a specified number of date parts to a datetime. Use when you need to shift a datetime forward or backward by a specific calendar unit.
- datetime_diff: Calculates the difference between two datetime values. Use when you need to measure elapsed time between events.
- startofday: Returns the start of the day for a datetime, useful for day-level binning.
- endofday: Returns the end of the day for a datetime.