// Copyright 2017 The Prometheus Authors // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // Package v1 provides bindings to the Prometheus HTTP API v1: // http://prometheus.io/docs/querying/api/ package v1 import ( "context" "encoding/json" "errors" "fmt" "net/http" "strconv" "strings" "time" "github.com/prometheus/client_golang/api" "github.com/prometheus/common/model" ) const ( statusAPIError = 422 apiPrefix = "/api/v1" epAlerts = apiPrefix + "/alerts" epAlertManagers = apiPrefix + "/alertmanagers" epQuery = apiPrefix + "/query" epQueryRange = apiPrefix + "/query_range" epLabelValues = apiPrefix + "/label/:name/values" epSeries = apiPrefix + "/series" epTargets = apiPrefix + "/targets" epRules = apiPrefix + "/rules" epSnapshot = apiPrefix + "/admin/tsdb/snapshot" epDeleteSeries = apiPrefix + "/admin/tsdb/delete_series" epCleanTombstones = apiPrefix + "/admin/tsdb/clean_tombstones" epConfig = apiPrefix + "/status/config" epFlags = apiPrefix + "/status/flags" ) // AlertState models the state of an alert. type AlertState string // ErrorType models the different API error types. type ErrorType string // HealthStatus models the health status of a scrape target. type HealthStatus string // RuleType models the type of a rule. type RuleType string // RuleHealth models the health status of a rule. type RuleHealth string const ( // Possible values for AlertState. AlertStateFiring AlertState = "firing" AlertStateInactive AlertState = "inactive" AlertStatePending AlertState = "pending" // Possible values for ErrorType. ErrBadData ErrorType = "bad_data" ErrTimeout ErrorType = "timeout" ErrCanceled ErrorType = "canceled" ErrExec ErrorType = "execution" ErrBadResponse ErrorType = "bad_response" ErrServer ErrorType = "server_error" ErrClient ErrorType = "client_error" // Possible values for HealthStatus. HealthGood HealthStatus = "up" HealthUnknown HealthStatus = "unknown" HealthBad HealthStatus = "down" // Possible values for RuleType. RuleTypeRecording RuleType = "recording" RuleTypeAlerting RuleType = "alerting" // Possible values for RuleHealth. RuleHealthGood = "ok" RuleHealthUnknown = "unknown" RuleHealthBad = "err" ) // Error is an error returned by the API. type Error struct { Type ErrorType Msg string Detail string warnings []string } func (e *Error) Error() string { if e.Type != "" || e.Msg != "" { return fmt.Sprintf("%s: %s", e.Type, e.Msg) } return "Warnings: " + strings.Join(e.warnings, " , ") } func (w *Error) Err() error { return w } func (w *Error) Warnings() []string { return w.warnings } // Range represents a sliced time range. type Range struct { // The boundaries of the time range. Start, End time.Time // The maximum time between two slices within the boundaries. Step time.Duration } // API provides bindings for Prometheus's v1 API. type API interface { // Alerts returns a list of all active alerts. Alerts(ctx context.Context) (AlertsResult, api.Error) // AlertManagers returns an overview of the current state of the Prometheus alert manager discovery. AlertManagers(ctx context.Context) (AlertManagersResult, api.Error) // CleanTombstones removes the deleted data from disk and cleans up the existing tombstones. CleanTombstones(ctx context.Context) api.Error // Config returns the current Prometheus configuration. Config(ctx context.Context) (ConfigResult, api.Error) // DeleteSeries deletes data for a selection of series in a time range. DeleteSeries(ctx context.Context, matches []string, startTime time.Time, endTime time.Time) api.Error // Flags returns the flag values that Prometheus was launched with. Flags(ctx context.Context) (FlagsResult, api.Error) // LabelValues performs a query for the values of the given label. LabelValues(ctx context.Context, label string) (model.LabelValues, api.Error) // Query performs a query for the given time. Query(ctx context.Context, query string, ts time.Time) (model.Value, api.Error) // QueryRange performs a query for the given range. QueryRange(ctx context.Context, query string, r Range) (model.Value, api.Error) // Series finds series by label matchers. Series(ctx context.Context, matches []string, startTime time.Time, endTime time.Time) ([]model.LabelSet, api.Error) // Snapshot creates a snapshot of all current data into snapshots/- // under the TSDB's data directory and returns the directory as response. Snapshot(ctx context.Context, skipHead bool) (SnapshotResult, api.Error) // Rules returns a list of alerting and recording rules that are currently loaded. Rules(ctx context.Context) (RulesResult, api.Error) // Targets returns an overview of the current state of the Prometheus target discovery. Targets(ctx context.Context) (TargetsResult, api.Error) } // AlertsResult contains the result from querying the alerts endpoint. type AlertsResult struct { Alerts []Alert `json:"alerts"` } // AlertManagersResult contains the result from querying the alertmanagers endpoint. type AlertManagersResult struct { Active []AlertManager `json:"activeAlertManagers"` Dropped []AlertManager `json:"droppedAlertManagers"` } // AlertManager models a configured Alert Manager. type AlertManager struct { URL string `json:"url"` } // ConfigResult contains the result from querying the config endpoint. type ConfigResult struct { YAML string `json:"yaml"` } // FlagsResult contains the result from querying the flag endpoint. type FlagsResult map[string]string // SnapshotResult contains the result from querying the snapshot endpoint. type SnapshotResult struct { Name string `json:"name"` } // RulesResult contains the result from querying the rules endpoint. type RulesResult struct { Groups []RuleGroup `json:"groups"` } // RuleGroup models a rule group that contains a set of recording and alerting rules. type RuleGroup struct { Name string `json:"name"` File string `json:"file"` Interval float64 `json:"interval"` Rules Rules `json:"rules"` } // Recording and alerting rules are stored in the same slice to preserve the order // that rules are returned in by the API. // // Rule types can be determined using a type switch: // switch v := rule.(type) { // case RecordingRule: // fmt.Print("got a recording rule") // case AlertingRule: // fmt.Print("got a alerting rule") // default: // fmt.Printf("unknown rule type %s", v) // } type Rules []interface{} // AlertingRule models a alerting rule. type AlertingRule struct { Name string `json:"name"` Query string `json:"query"` Duration float64 `json:"duration"` Labels model.LabelSet `json:"labels"` Annotations model.LabelSet `json:"annotations"` Alerts []*Alert `json:"alerts"` Health RuleHealth `json:"health"` LastError string `json:"lastError,omitempty"` } // RecordingRule models a recording rule. type RecordingRule struct { Name string `json:"name"` Query string `json:"query"` Labels model.LabelSet `json:"labels,omitempty"` Health RuleHealth `json:"health"` LastError string `json:"lastError,omitempty"` } // Alert models an active alert. type Alert struct { ActiveAt time.Time `json:"activeAt"` Annotations model.LabelSet Labels model.LabelSet State AlertState Value float64 } // TargetsResult contains the result from querying the targets endpoint. type TargetsResult struct { Active []ActiveTarget `json:"activeTargets"` Dropped []DroppedTarget `json:"droppedTargets"` } // ActiveTarget models an active Prometheus scrape target. type ActiveTarget struct { DiscoveredLabels map[string]string `json:"discoveredLabels"` Labels model.LabelSet `json:"labels"` ScrapeURL string `json:"scrapeUrl"` LastError string `json:"lastError"` LastScrape time.Time `json:"lastScrape"` Health HealthStatus `json:"health"` } // DroppedTarget models a dropped Prometheus scrape target. type DroppedTarget struct { DiscoveredLabels map[string]string `json:"discoveredLabels"` } // queryResult contains result data for a query. type queryResult struct { Type model.ValueType `json:"resultType"` Result interface{} `json:"result"` // The decoded value. v model.Value } func (rg *RuleGroup) UnmarshalJSON(b []byte) error { v := struct { Name string `json:"name"` File string `json:"file"` Interval float64 `json:"interval"` Rules []json.RawMessage `json:"rules"` }{} if err := json.Unmarshal(b, &v); err != nil { return err } rg.Name = v.Name rg.File = v.File rg.Interval = v.Interval for _, rule := range v.Rules { alertingRule := AlertingRule{} if err := json.Unmarshal(rule, &alertingRule); err == nil { rg.Rules = append(rg.Rules, alertingRule) continue } recordingRule := RecordingRule{} if err := json.Unmarshal(rule, &recordingRule); err == nil { rg.Rules = append(rg.Rules, recordingRule) continue } return errors.New("failed to decode JSON into an alerting or recording rule") } return nil } func (r *AlertingRule) UnmarshalJSON(b []byte) error { v := struct { Type string `json:"type"` }{} if err := json.Unmarshal(b, &v); err != nil { return err } if v.Type == "" { return errors.New("type field not present in rule") } if v.Type != string(RuleTypeAlerting) { return fmt.Errorf("expected rule of type %s but got %s", string(RuleTypeAlerting), v.Type) } rule := struct { Name string `json:"name"` Query string `json:"query"` Duration float64 `json:"duration"` Labels model.LabelSet `json:"labels"` Annotations model.LabelSet `json:"annotations"` Alerts []*Alert `json:"alerts"` Health RuleHealth `json:"health"` LastError string `json:"lastError,omitempty"` }{} if err := json.Unmarshal(b, &rule); err != nil { return err } r.Health = rule.Health r.Annotations = rule.Annotations r.Name = rule.Name r.Query = rule.Query r.Alerts = rule.Alerts r.Duration = rule.Duration r.Labels = rule.Labels r.LastError = rule.LastError return nil } func (r *RecordingRule) UnmarshalJSON(b []byte) error { v := struct { Type string `json:"type"` }{} if err := json.Unmarshal(b, &v); err != nil { return err } if v.Type == "" { return errors.New("type field not present in rule") } if v.Type != string(RuleTypeRecording) { return fmt.Errorf("expected rule of type %s but got %s", string(RuleTypeRecording), v.Type) } rule := struct { Name string `json:"name"` Query string `json:"query"` Labels model.LabelSet `json:"labels,omitempty"` Health RuleHealth `json:"health"` LastError string `json:"lastError,omitempty"` }{} if err := json.Unmarshal(b, &rule); err != nil { return err } r.Health = rule.Health r.Labels = rule.Labels r.Name = rule.Name r.LastError = rule.LastError r.Query = rule.Query return nil } func (qr *queryResult) UnmarshalJSON(b []byte) error { v := struct { Type model.ValueType `json:"resultType"` Result json.RawMessage `json:"result"` }{} err := json.Unmarshal(b, &v) if err != nil { return err } switch v.Type { case model.ValScalar: var sv model.Scalar err = json.Unmarshal(v.Result, &sv) qr.v = &sv case model.ValVector: var vv model.Vector err = json.Unmarshal(v.Result, &vv) qr.v = vv case model.ValMatrix: var mv model.Matrix err = json.Unmarshal(v.Result, &mv) qr.v = mv default: err = fmt.Errorf("unexpected value type %q", v.Type) } return err } // NewAPI returns a new API for the client. // // It is safe to use the returned API from multiple goroutines. func NewAPI(c api.Client) API { return &httpAPI{client: apiClient{c}} } type httpAPI struct { client api.Client } func (h *httpAPI) Alerts(ctx context.Context) (AlertsResult, api.Error) { u := h.client.URL(epAlerts, nil) req, err := http.NewRequest(http.MethodGet, u.String(), nil) if err != nil { return AlertsResult{}, api.NewErrorAPI(err, nil) } _, body, apiErr := h.client.Do(ctx, req) if apiErr != nil { return AlertsResult{}, apiErr } var res AlertsResult err = json.Unmarshal(body, &res) return res, api.NewErrorAPI(err, nil) } func (h *httpAPI) AlertManagers(ctx context.Context) (AlertManagersResult, api.Error) { u := h.client.URL(epAlertManagers, nil) req, err := http.NewRequest(http.MethodGet, u.String(), nil) if err != nil { return AlertManagersResult{}, api.NewErrorAPI(err, nil) } _, body, apiErr := h.client.Do(ctx, req) if apiErr != nil { return AlertManagersResult{}, apiErr } var res AlertManagersResult err = json.Unmarshal(body, &res) return res, api.NewErrorAPI(err, nil) } func (h *httpAPI) CleanTombstones(ctx context.Context) api.Error { u := h.client.URL(epCleanTombstones, nil) req, err := http.NewRequest(http.MethodPost, u.String(), nil) if err != nil { return api.NewErrorAPI(err, nil) } _, _, apiErr := h.client.Do(ctx, req) return apiErr } func (h *httpAPI) Config(ctx context.Context) (ConfigResult, api.Error) { u := h.client.URL(epConfig, nil) req, err := http.NewRequest(http.MethodGet, u.String(), nil) if err != nil { return ConfigResult{}, api.NewErrorAPI(err, nil) } _, body, apiErr := h.client.Do(ctx, req) if apiErr != nil { return ConfigResult{}, apiErr } var res ConfigResult err = json.Unmarshal(body, &res) return res, api.NewErrorAPI(err, nil) } func (h *httpAPI) DeleteSeries(ctx context.Context, matches []string, startTime time.Time, endTime time.Time) api.Error { u := h.client.URL(epDeleteSeries, nil) q := u.Query() for _, m := range matches { q.Add("match[]", m) } q.Set("start", startTime.Format(time.RFC3339Nano)) q.Set("end", endTime.Format(time.RFC3339Nano)) u.RawQuery = q.Encode() req, err := http.NewRequest(http.MethodPost, u.String(), nil) if err != nil { return api.NewErrorAPI(err, nil) } _, _, apiErr := h.client.Do(ctx, req) return apiErr } func (h *httpAPI) Flags(ctx context.Context) (FlagsResult, api.Error) { u := h.client.URL(epFlags, nil) req, err := http.NewRequest(http.MethodGet, u.String(), nil) if err != nil { return FlagsResult{}, api.NewErrorAPI(err, nil) } _, body, apiErr := h.client.Do(ctx, req) if apiErr != nil { return FlagsResult{}, apiErr } var res FlagsResult err = json.Unmarshal(body, &res) return res, api.NewErrorAPI(err, nil) } func (h *httpAPI) LabelValues(ctx context.Context, label string) (model.LabelValues, api.Error) { u := h.client.URL(epLabelValues, map[string]string{"name": label}) req, err := http.NewRequest(http.MethodGet, u.String(), nil) if err != nil { return nil, api.NewErrorAPI(err, nil) } _, body, apiErr := h.client.Do(ctx, req) if apiErr != nil { return nil, apiErr } var labelValues model.LabelValues err = json.Unmarshal(body, &labelValues) return labelValues, api.NewErrorAPI(err, nil) } func (h *httpAPI) Query(ctx context.Context, query string, ts time.Time) (model.Value, api.Error) { u := h.client.URL(epQuery, nil) q := u.Query() q.Set("query", query) if !ts.IsZero() { q.Set("time", ts.Format(time.RFC3339Nano)) } _, body, apiErr := api.DoGetFallback(h.client, ctx, u, q) if apiErr != nil { return nil, apiErr } var qres queryResult return model.Value(qres.v), api.NewErrorAPI(json.Unmarshal(body, &qres), nil) } func (h *httpAPI) QueryRange(ctx context.Context, query string, r Range) (model.Value, api.Error) { u := h.client.URL(epQueryRange, nil) q := u.Query() var ( start = r.Start.Format(time.RFC3339Nano) end = r.End.Format(time.RFC3339Nano) step = strconv.FormatFloat(r.Step.Seconds(), 'f', 3, 64) ) q.Set("query", query) q.Set("start", start) q.Set("end", end) q.Set("step", step) _, body, apiErr := api.DoGetFallback(h.client, ctx, u, q) if apiErr != nil { return nil, apiErr } var qres queryResult return model.Value(qres.v), api.NewErrorAPI(json.Unmarshal(body, &qres), nil) } func (h *httpAPI) Series(ctx context.Context, matches []string, startTime time.Time, endTime time.Time) ([]model.LabelSet, api.Error) { u := h.client.URL(epSeries, nil) q := u.Query() for _, m := range matches { q.Add("match[]", m) } q.Set("start", startTime.Format(time.RFC3339Nano)) q.Set("end", endTime.Format(time.RFC3339Nano)) u.RawQuery = q.Encode() req, err := http.NewRequest(http.MethodGet, u.String(), nil) if err != nil { return nil, api.NewErrorAPI(err, nil) } _, body, apiErr := h.client.Do(ctx, req) if apiErr != nil { return nil, apiErr } var mset []model.LabelSet err = json.Unmarshal(body, &mset) return mset, api.NewErrorAPI(err, nil) } func (h *httpAPI) Snapshot(ctx context.Context, skipHead bool) (SnapshotResult, api.Error) { u := h.client.URL(epSnapshot, nil) q := u.Query() q.Set("skip_head", strconv.FormatBool(skipHead)) u.RawQuery = q.Encode() req, err := http.NewRequest(http.MethodPost, u.String(), nil) if err != nil { return SnapshotResult{}, api.NewErrorAPI(err, nil) } _, body, apiErr := h.client.Do(ctx, req) if apiErr != nil { return SnapshotResult{}, apiErr } var res SnapshotResult err = json.Unmarshal(body, &res) return res, api.NewErrorAPI(err, nil) } func (h *httpAPI) Rules(ctx context.Context) (RulesResult, api.Error) { u := h.client.URL(epRules, nil) req, err := http.NewRequest(http.MethodGet, u.String(), nil) if err != nil { return RulesResult{}, api.NewErrorAPI(err, nil) } _, body, apiErr := h.client.Do(ctx, req) if apiErr != nil { return RulesResult{}, apiErr } var res RulesResult err = json.Unmarshal(body, &res) return res, api.NewErrorAPI(err, nil) } func (h *httpAPI) Targets(ctx context.Context) (TargetsResult, api.Error) { u := h.client.URL(epTargets, nil) req, err := http.NewRequest(http.MethodGet, u.String(), nil) if err != nil { return TargetsResult{}, api.NewErrorAPI(err, nil) } _, body, apiErr := h.client.Do(ctx, req) if apiErr != nil { return TargetsResult{}, apiErr } var res TargetsResult err = json.Unmarshal(body, &res) return res, api.NewErrorAPI(err, nil) } // apiClient wraps a regular client and processes successful API responses. // Successful also includes responses that errored at the API level. type apiClient struct { api.Client } type apiResponse struct { Status string `json:"status"` Data json.RawMessage `json:"data"` ErrorType ErrorType `json:"errorType"` Error string `json:"error"` Warnings []string `json:"warnings,omitempty"` } func apiError(code int) bool { // These are the codes that Prometheus sends when it returns an error. return code == statusAPIError || code == http.StatusBadRequest } func errorTypeAndMsgFor(resp *http.Response) (ErrorType, string) { switch resp.StatusCode / 100 { case 4: return ErrClient, fmt.Sprintf("client error: %d", resp.StatusCode) case 5: return ErrServer, fmt.Sprintf("server error: %d", resp.StatusCode) } return ErrBadResponse, fmt.Sprintf("bad response code %d", resp.StatusCode) } func (c apiClient) Do(ctx context.Context, req *http.Request) (*http.Response, []byte, api.Error) { resp, body, apiErr := c.Client.Do(ctx, req) if apiErr != nil { return resp, body, apiErr } code := resp.StatusCode var err api.Error if code/100 != 2 && !apiError(code) { errorType, errorMsg := errorTypeAndMsgFor(resp) return resp, body, &Error{ Type: errorType, Msg: errorMsg, Detail: string(body), } } var result apiResponse if http.StatusNoContent != code { if jsonErr := json.Unmarshal(body, &result); jsonErr != nil { return resp, body, &Error{ Type: ErrBadResponse, Msg: jsonErr.Error(), } } } if apiError(code) != (result.Status == "error") { err = &Error{ Type: ErrBadResponse, Msg: "inconsistent body for response code", warnings: result.Warnings, } } if apiError(code) && result.Status == "error" { err = &Error{ Type: result.ErrorType, Msg: result.Error, warnings: result.Warnings, } } return resp, []byte(result.Data), err }