client

Documentation

Overview

Package prometheus provides bindings to the Prometheus HTTP API: http://prometheus.io/docs/querying/api/

Copyright 2017 The Kubernetes 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.

Copyright 2017 The Kubernetes 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 prometheus provides bindings to the Prometheus HTTP API: http://prometheus.io/docs/querying/api/

Index

• Constants
• func LabelEq(label string, value string) string
• func LabelMatches(label string, expr string) string
• func LabelNeq(label string, value string) string
• func LabelNotMatches(label string, expr string) string
• func NameMatches(expr string) string
• func NameNotMatches(expr string) string
• type APIResponse
• type Client
  • func NewClient(client *http.Client, baseURL *url.URL) Client
  • func NewClientForAPI(client GenericAPIClient) Client
• type Error
  • func (e *Error) Error() string
• type ErrorType
• type GenericAPIClient
  • func NewGenericAPIClient(client *http.Client, baseURL *url.URL) GenericAPIClient
• type QueryResult
  • func (qr *QueryResult) UnmarshalJSON(b []byte) error
• type Range
• type ResponseStatus
• type Selector
  • func MatchSeries(name string, labelExpressions ...string) Selector
• type Series
  • func (s *Series) String() string
  • func (s *Series) UnmarshalJSON(data []byte) error

Constants

const (
	ErrBadData     ErrorType = "bad_data"
	ErrTimeout               = "timeout"
	ErrCanceled              = "canceled"
	ErrExec                  = "execution"
	ErrBadResponse           = "bad_response"
)

Functions

func LabelEq

func LabelEq(label string, value string) string

LabelEq produces a equal label selector expression. Label is passed verbatim, and value is double-quote escaped using Go's escaping (as per the PromQL rules).

func LabelMatches

func LabelMatches(label string, expr string) string

LabelMatches produces a regexp-matching label selector expression. It has similar constraints to LabelNeq.

func LabelNeq

func LabelNeq(label string, value string) string

LabelNeq produces a not-equal label selector expression. Label is passed verbatim, and value is double-quote escaped using Go's escaping (as per the PromQL rules).

func LabelNotMatches

func LabelNotMatches(label string, expr string) string

LabelNotMatches produces a inverse regexp-matching label selector expression (the opposite of LabelMatches).

func NameMatches

func NameMatches(expr string) string

NameMatches produces a label selector expression that checks that the series name matches the given expression. It's a convinience wrapper around LabelMatches.

func NameNotMatches

func NameNotMatches(expr string) string

NameNotMatches produces a label selector expression that checks that the series name doesn't matches the given expression. It's a convenience wrapper around LabelNotMatches.

Types

type APIResponse

type APIResponse struct {
	// Status indicates whether this request was successful or whether it errored out.
	Status ResponseStatus `json:"status"`
	// Data contains the raw data response for this request.
	Data json.RawMessage `json:"data"`

	// ErrorType is the type of error, if this is an error response.
	ErrorType ErrorType `json:"errorType"`
	// Error is the error message, if this is an error response.
	Error string `json:"error"`
}

APIResponse represents the raw response returned by the API.

type Client

type Client interface {
	// Series lists the time series matching the given series selectors
	Series(ctx context.Context, interval model.Interval, selectors ...Selector) ([]Series, error)
	// Query runs a non-range query at the given time.
	Query(ctx context.Context, t model.Time, query Selector) (QueryResult, error)
	// QueryRange runs a range query at the given time.
	QueryRange(ctx context.Context, r Range, query Selector) (QueryResult, error)
}

Client is a Prometheus client for the Prometheus HTTP API. The "timeout" parameter for the HTTP API is set based on the context's deadline, when present and applicable.

func NewClient

func NewClient(client *http.Client, baseURL *url.URL) Client

NewClient creates a Client for the given HTTP client and base URL (the location of the Prometheus server).

func NewClientForAPI

func NewClientForAPI(client GenericAPIClient) Client

NewClientForAPI creates a Client for the given generic Prometheus API client.

type Error

type Error struct {
	Type ErrorType
	Msg  string
}

Error is an error returned by the API.

func (*Error) Error

func (e *Error) Error() string

type ErrorType

type ErrorType string

ErrorType is the type of the API error.

type GenericAPIClient

type GenericAPIClient interface {
	// Do makes a request to the Prometheus HTTP API against a particular endpoint.  Query
	// parameters should be in `query`, not `endpoint`.  An error will be returned on HTTP
	// status errors or errors making or unmarshalling the request, as well as when the
	// response has a Status of ResponseError.
	Do(ctx context.Context, verb, endpoint string, query url.Values) (APIResponse, error)
}

APIClient is a raw client to the Prometheus Query API. It knows how to appropriately deal with generic Prometheus API responses, but does not know the specifics of different endpoints. You can use this to call query endpoints not represented in Client.

func NewGenericAPIClient

func NewGenericAPIClient(client *http.Client, baseURL *url.URL) GenericAPIClient

NewGenericAPIClient builds a new generic Prometheus API client for the given base URL and HTTP Client.

type QueryResult

type QueryResult struct {
	Type model.ValueType

	Vector *model.Vector
	Scalar *model.Scalar
	Matrix *model.Matrix
}

QueryResult is the result of a query. Type will always be set, as well as one of the other fields, matching the type.

func (*QueryResult) UnmarshalJSON

func (qr *QueryResult) UnmarshalJSON(b []byte) error

type Range

type Range struct {
	// Start and End are the boundaries of the time range.
	Start, End model.Time
	// Step is the maximum time between two slices within the boundaries.
	Step time.Duration
}

Range represents a sliced time range with increments.

type ResponseStatus

type ResponseStatus string

ResponseStatus is the type of response from the API: succeeded or error.

const (
	ResponseSucceeded ResponseStatus = "succeeded"
	ResponseError                    = "error"
)

type Selector

type Selector string

Selector represents a series selector

func MatchSeries

func MatchSeries(name string, labelExpressions ...string) Selector

MatchSeries takes a series name, and optionally some label expressions, and returns a series selector. TODO: validate series name and expressions?

type Series

type Series struct {
	Name   string
	Labels model.LabelSet
}

Series represents a description of a series: a name and a set of labels. Series is roughly equivalent to model.Metrics, but has easy access to name and the set of non-name labels.

func (*Series) String

func (s *Series) String() string

func (*Series) UnmarshalJSON

func (s *Series) UnmarshalJSON(data []byte) error