cmd/bosun: add month func to get end of or start of month (#1740)

cmd/bosun/expr/funcs.go

@@ -17,6 +17,7 @@ import (
 	"bosun.org/slog"
 	"github.com/GaryBoone/GoStats/stats"
 	"github.com/MiniProfiler/go/miniprofiler"
+	"github.com/jinzhu/now"
 )
 
 func tagQuery(args []parse.Node) (parse.Tags, error) {
@@ -370,6 +371,11 @@ var builtins = map[string]parse.Func{
 		Tags:   tagFirst,
 		F:      Merge,
 	},
+	"month": {
+		Args:   []models.FuncType{models.TypeScalar, models.TypeString},
+		Return: models.TypeScalar,
+		F:      Month,
+	},
 }
 
 func SeriesFunc(e *State, T miniprofiler.Timer, tags string, pairs ...float64) (*Results, error) {
@@ -423,6 +429,26 @@ func Epoch(e *State, T miniprofiler.Timer) (*Results, error) {
 	}, nil
 }
 
+func Month(e *State, T miniprofiler.Timer, offset float64, startEnd string) (*Results, error) {
+	if startEnd != "start" && startEnd != "end" {
+		return nil, fmt.Errorf("last parameter for mtod must be 'start' or 'end'")
+	}
+	offsetInt := int(offset)
+	location := time.FixedZone(fmt.Sprintf("%v", offsetInt), offsetInt*60*60)
+	timeZoned := e.now.In(location)
+	var mtod float64
+	if startEnd == "start" {
+		mtod = float64(now.New(timeZoned).BeginningOfMonth().Unix())
+	} else {
+		mtod = float64(now.New(timeZoned).EndOfMonth().Unix())
+	}
+	return &Results{
+		Results: []*Result{
+			{Value: Scalar(float64(mtod))},
+		},
+	}, nil
+}
+
 func NV(e *State, T miniprofiler.Timer, series *Results, v float64) (results *Results, err error) {
 	// If there are no results in the set, promote it to a number with the empty group ({})
 	if len(series.Results) == 0 {

docs/expressions.md

@@ -514,6 +514,27 @@ Returns the first count (scalar) results of number.
 
 Returns the first key from the given lookup table with matching tags.
 
+## month(offset scalar, startEnd string) scalar
+
+Returns the epoch of either the start or end of the month. Offset is the timezone offset from UTC that the month starts/ends at (but the returned epoch is representitive of UTC). startEnd must be either `"start"` or `"end"`. Useful for things like monthly billing, for example:
+
+```
+$hostInt = host=ny-nexus01,iname=Ethernet1/46
+$inMetric = "sum:5m-avg:rate{counter,,1}:__ny-nexus01.os.net.bytes{$hostInt,direction=in}"
+$outMetric = "sum:5m-avg:rate{counter,,1}:__ny-nexus01.os.net.bytes{$hostInt,direction=in}"
+$commit = 100
+$monthStart = month(-4, "start")
+$monthEnd = month(-4, "end")
+$monthLength = $monthEnd - $monthStart
+$burstTime = ($monthLength)*.05
+$burstableObservations = $burstTime / d("5m")
+$in = q($inMetric, tod(epoch()-$monthStart), "") * 8 / 1e6
+$out = q($inMetric, tod(epoch()-$monthStart), "") * 8 / 1e6
+$inOverCount = sum($in > $commit)
+$outOverCount = sum($out > $commit)
+$inOverCount > $burstableObservations || $outOverCount > $burstableObservations
+```
+
 ## series(tagset string, epoch, value, ...) seriesSet
 
 Returns a seriesSet with one series. The series will have a group (a.k.a tagset). You can then optionally pass epoch value pairs (if non are provided, the series will be empty). This is can be used for testing or drawing arbitary lines. For example: