monthofyear
This page explains how to use the monthofyear function in APL.
Use the monthofyear function in APL to extract the month number from a datetime value. The function returns an integer from 1 to 12, where 1 represents January and 12 represents December.
The monthofyear and getmonth functions return the same result. Use either interchangeably.
You can use monthofyear to group records by month when analyzing seasonal patterns, month-over-month comparisons, or periodic trends. This is useful for dashboards, monthly reporting, and cohort analysis.
Use it when you want to:
- Aggregate events by month for seasonal trend analysis.
- Compare metrics month over month to detect recurring patterns.
- Create monthly summaries across log, trace, or security datasets.
Usage
Syntax
monthofyear(datetime)Parameters
| Name | Type | Description |
|---|---|---|
| datetime | datetime | The input datetime value. |
Returns
An int from 1 to 12 representing the month number of the year.
Use case examples
Analyze average request duration by month to identify seasonal performance variations.
Query
['sample-http-logs']
| extend month = monthofyear(_time)
| summarize avg_duration = avg(req_duration_ms) by month
| sort by month ascOutput
| month | avg_duration |
|---|---|
| 1 | 243.8 |
| 2 | 238.5 |
| 3 | 251.2 |
This query calculates the average request duration per month, helping you spot months with degraded performance.
Compare monthly span counts per service to understand how trace volume fluctuates across months.
Query
['otel-demo-traces']
| extend month = monthofyear(_time)
| summarize span_count = count() by month, ['service.name']
| sort by month ascOutput
| month | service.name | span_count |
|---|---|---|
| 1 | frontend | 4520 |
| 1 | cart | 2150 |
| 2 | frontend | 4830 |
This query counts spans per service per month, showing monthly variations in trace activity for each service.
Identify seasonal patterns in server error rates by counting errors per month.
Query
['sample-http-logs']
| where toint(status) >= 500
| extend month = monthofyear(_time)
| summarize error_count = count() by month
| sort by month ascOutput
| month | error_count |
|---|---|
| 1 | 42 |
| 2 | 38 |
| 3 | 56 |
This query reveals the monthly distribution of server errors, helping you identify months with elevated failure rates.
List of related functions
- getmonth: Returns the month number from a datetime. Equivalent to
monthofyear. - getyear: Extracts the year part from a datetime as an integer.
- dayofmonth: Returns the day of the month from a datetime.
- startofmonth: Returns the start of the month for a datetime, useful for monthly binning.
- endofmonth: Returns the end of the month for a datetime value.