client_golang: github.com/prometheus/client_golang/api/prometheus/v1 Index | Examples | Files

package v1

import "github.com/prometheus/client_golang/api/prometheus/v1"

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

Index

Examples

Package Files

api.go

Constants

❖
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"

    // Possible values for MetricType
    MetricTypeCounter        MetricType = "counter"
    MetricTypeGauge          MetricType = "gauge"
    MetricTypeHistogram      MetricType = "histogram"
    MetricTypeGaugeHistogram MetricType = "gaugehistogram"
    MetricTypeSummary        MetricType = "summary"
    MetricTypeInfo           MetricType = "info"
    MetricTypeStateset       MetricType = "stateset"
    MetricTypeUnknown        MetricType = "unknown"
)

type API Uses

❖
type API interface {
    // Alerts returns a list of all active alerts.
    Alerts(ctx context.Context) (AlertsResult, error)
    // AlertManagers returns an overview of the current state of the Prometheus alert manager discovery.
    AlertManagers(ctx context.Context) (AlertManagersResult, error)
    // CleanTombstones removes the deleted data from disk and cleans up the existing tombstones.
    CleanTombstones(ctx context.Context) error
    // Config returns the current Prometheus configuration.
    Config(ctx context.Context) (ConfigResult, 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) error
    // Flags returns the flag values that Prometheus was launched with.
    Flags(ctx context.Context) (FlagsResult, error)
    // LabelNames returns all the unique label names present in the block in sorted order.
    LabelNames(ctx context.Context, startTime time.Time, endTime time.Time) ([]string, Warnings, error)
    // LabelValues performs a query for the values of the given label.
    LabelValues(ctx context.Context, label string, startTime time.Time, endTime time.Time) (model.LabelValues, Warnings, error)
    // Query performs a query for the given time.
    Query(ctx context.Context, query string, ts time.Time) (model.Value, Warnings, error)
    // QueryRange performs a query for the given range.
    QueryRange(ctx context.Context, query string, r Range) (model.Value, Warnings, error)
    // Runtimeinfo returns the various runtime information properties about the Prometheus server.
    Runtimeinfo(ctx context.Context) (RuntimeinfoResult, error)
    // Series finds series by label matchers.
    Series(ctx context.Context, matches []string, startTime time.Time, endTime time.Time) ([]model.LabelSet, Warnings, error)
    // Snapshot creates a snapshot of all current data into snapshots/<datetime>-<rand>
    // under the TSDB's data directory and returns the directory as response.
    Snapshot(ctx context.Context, skipHead bool) (SnapshotResult, error)
    // Rules returns a list of alerting and recording rules that are currently loaded.
    Rules(ctx context.Context) (RulesResult, error)
    // Targets returns an overview of the current state of the Prometheus target discovery.
    Targets(ctx context.Context) (TargetsResult, error)
    // TargetsMetadata returns metadata about metrics currently scraped by the target.
    TargetsMetadata(ctx context.Context, matchTarget string, metric string, limit string) ([]MetricMetadata, error)
    // Metadata returns metadata about metrics currently scraped by the metric name.
    Metadata(ctx context.Context, metric string, limit string) (map[string][]Metadata, error)
    // TSDB returns the cardinality statistics.
    TSDB(ctx context.Context) (TSDBResult, error)
}

API provides bindings for Prometheus's v1 API.

Example (Query)

Code: 

client, err := api.NewClient(api.Config{
    Address: "http://demo.robustperception.io:9090",
})
if err != nil {
    fmt.Printf("Error creating client: %v\n", err)
    os.Exit(1)
}

v1api := v1.NewAPI(client)
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
result, warnings, err := v1api.Query(ctx, "up", time.Now())
if err != nil {
    fmt.Printf("Error querying Prometheus: %v\n", err)
    os.Exit(1)
}
if len(warnings) > 0 {
    fmt.Printf("Warnings: %v\n", warnings)
}
fmt.Printf("Result:\n%v\n", result)
Example (QueryRange)

Code: 

client, err := api.NewClient(api.Config{
    Address: "http://demo.robustperception.io:9090",
})
if err != nil {
    fmt.Printf("Error creating client: %v\n", err)
    os.Exit(1)
}

v1api := v1.NewAPI(client)
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
r := v1.Range{
    Start: time.Now().Add(-time.Hour),
    End:   time.Now(),
    Step:  time.Minute,
}
result, warnings, err := v1api.QueryRange(ctx, "rate(prometheus_tsdb_head_samples_appended_total[5m])", r)
if err != nil {
    fmt.Printf("Error querying Prometheus: %v\n", err)
    os.Exit(1)
}
if len(warnings) > 0 {
    fmt.Printf("Warnings: %v\n", warnings)
}
fmt.Printf("Result:\n%v\n", result)
Example (QueryRangeWithAuthBearerToken)

Code: 

client, err := api.NewClient(api.Config{
    Address: "http://demo.robustperception.io:9090",
    // We can use amazing github.com/prometheus/common/config helper!
    RoundTripper: config.NewBearerAuthRoundTripper("secret_token", api.DefaultRoundTripper),
})
if err != nil {
    fmt.Printf("Error creating client: %v\n", err)
    os.Exit(1)
}

v1api := v1.NewAPI(client)
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
r := v1.Range{
    Start: time.Now().Add(-time.Hour),
    End:   time.Now(),
    Step:  time.Minute,
}
result, warnings, err := v1api.QueryRange(ctx, "rate(prometheus_tsdb_head_samples_appended_total[5m])", r)
if err != nil {
    fmt.Printf("Error querying Prometheus: %v\n", err)
    os.Exit(1)
}
if len(warnings) > 0 {
    fmt.Printf("Warnings: %v\n", warnings)
}
fmt.Printf("Result:\n%v\n", result)
Example (QueryRangeWithBasicAuth)

Code: 

client, err := api.NewClient(api.Config{
    Address: "http://demo.robustperception.io:9090",
    // We can use amazing github.com/prometheus/common/config helper!
    RoundTripper: config.NewBasicAuthRoundTripper("me", "defintely_me", "", api.DefaultRoundTripper),
})
if err != nil {
    fmt.Printf("Error creating client: %v\n", err)
    os.Exit(1)
}

v1api := v1.NewAPI(client)
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
r := v1.Range{
    Start: time.Now().Add(-time.Hour),
    End:   time.Now(),
    Step:  time.Minute,
}
result, warnings, err := v1api.QueryRange(ctx, "rate(prometheus_tsdb_head_samples_appended_total[5m])", r)
if err != nil {
    fmt.Printf("Error querying Prometheus: %v\n", err)
    os.Exit(1)
}
if len(warnings) > 0 {
    fmt.Printf("Warnings: %v\n", warnings)
}
fmt.Printf("Result:\n%v\n", result)
Example (QueryRangeWithUserAgent)

Code: 

client, err := api.NewClient(api.Config{
    Address:      "http://demo.robustperception.io:9090",
    RoundTripper: userAgentRoundTripper{name: "Client-Golang", rt: api.DefaultRoundTripper},
})
if err != nil {
    fmt.Printf("Error creating client: %v\n", err)
    os.Exit(1)
}

v1api := v1.NewAPI(client)
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
r := v1.Range{
    Start: time.Now().Add(-time.Hour),
    End:   time.Now(),
    Step:  time.Minute,
}
result, warnings, err := v1api.QueryRange(ctx, "rate(prometheus_tsdb_head_samples_appended_total[5m])", r)
if err != nil {
    fmt.Printf("Error querying Prometheus: %v\n", err)
    os.Exit(1)
}
if len(warnings) > 0 {
    fmt.Printf("Warnings: %v\n", warnings)
}
fmt.Printf("Result:\n%v\n", result)
Example (Series)

Code: 

client, err := api.NewClient(api.Config{
    Address: "http://demo.robustperception.io:9090",
})
if err != nil {
    fmt.Printf("Error creating client: %v\n", err)
    os.Exit(1)
}

v1api := v1.NewAPI(client)
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
lbls, warnings, err := v1api.Series(ctx, []string{
    "{__name__=~\"scrape_.+\",job=\"node\"}",
    "{__name__=~\"scrape_.+\",job=\"prometheus\"}",
}, time.Now().Add(-time.Hour), time.Now())
if err != nil {
    fmt.Printf("Error querying Prometheus: %v\n", err)
    os.Exit(1)
}
if len(warnings) > 0 {
    fmt.Printf("Warnings: %v\n", warnings)
}
fmt.Println("Result:")
for _, lbl := range lbls {
    fmt.Println(lbl)
}

func NewAPI Uses

❖
func NewAPI(c api.Client) API

NewAPI returns a new API for the client.

It is safe to use the returned API from multiple goroutines.

type ActiveTarget Uses

❖
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"`
}

ActiveTarget models an active Prometheus scrape target.

type Alert Uses

❖
type Alert struct {
    ActiveAt    time.Time `json:"activeAt"`
    Annotations model.LabelSet
    Labels      model.LabelSet
    State       AlertState
    Value       string
}

Alert models an active alert.

type AlertManager Uses

❖
type AlertManager struct {
    URL string `json:"url"`
}

AlertManager models a configured Alert Manager.

type AlertManagersResult Uses

❖
type AlertManagersResult struct {
    Active  []AlertManager `json:"activeAlertManagers"`
    Dropped []AlertManager `json:"droppedAlertManagers"`
}

AlertManagersResult contains the result from querying the alertmanagers endpoint.

type AlertState Uses

❖
type AlertState string

AlertState models the state of an alert.

type AlertingRule Uses

❖
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"`
}

AlertingRule models a alerting rule.

func (*AlertingRule) UnmarshalJSON Uses

❖
func (r *AlertingRule) UnmarshalJSON(b []byte) error

type AlertsResult Uses

❖
type AlertsResult struct {
    Alerts []Alert `json:"alerts"`
}

AlertsResult contains the result from querying the alerts endpoint.

type ConfigResult Uses

❖
type ConfigResult struct {
    YAML string `json:"yaml"`
}

ConfigResult contains the result from querying the config endpoint.

type DroppedTarget Uses

❖
type DroppedTarget struct {
    DiscoveredLabels map[string]string `json:"discoveredLabels"`
}

DroppedTarget models a dropped Prometheus scrape target.

type Error Uses

❖
type Error struct {
    Type   ErrorType
    Msg    string
    Detail string
}

Error is an error returned by the API.

func (*Error) Error Uses

❖
func (e *Error) Error() string

type ErrorType Uses

❖
type ErrorType string

ErrorType models the different API error types.

type FlagsResult Uses

❖
type FlagsResult map[string]string

FlagsResult contains the result from querying the flag endpoint.

type HealthStatus Uses

❖
type HealthStatus string

HealthStatus models the health status of a scrape target.

type Metadata Uses

❖
type Metadata struct {
    Type MetricType `json:"type"`
    Help string     `json:"help"`
    Unit string     `json:"unit"`
}

Metadata models the metadata of a metric.

type MetricMetadata Uses

❖
type MetricMetadata struct {
    Target map[string]string `json:"target"`
    Metric string            `json:"metric,omitempty"`
    Type   MetricType        `json:"type"`
    Help   string            `json:"help"`
    Unit   string            `json:"unit"`
}

MetricMetadata models the metadata of a metric with its scrape target and name.

type MetricType Uses

❖
type MetricType string

MetricType models the type of a metric.

type Range Uses

❖
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
}

Range represents a sliced time range.

type RecordingRule Uses

❖
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"`
}

RecordingRule models a recording rule.

func (*RecordingRule) UnmarshalJSON Uses

❖
func (r *RecordingRule) UnmarshalJSON(b []byte) error

type RuleGroup Uses

❖
type RuleGroup struct {
    Name     string  `json:"name"`
    File     string  `json:"file"`
    Interval float64 `json:"interval"`
    Rules    Rules   `json:"rules"`
}

RuleGroup models a rule group that contains a set of recording and alerting rules.

func (*RuleGroup) UnmarshalJSON Uses

❖
func (rg *RuleGroup) UnmarshalJSON(b []byte) error

type RuleHealth Uses

❖
type RuleHealth string

RuleHealth models the health status of a rule.

type RuleType Uses

❖
type RuleType string

RuleType models the type of a rule.

type Rules Uses

❖
type Rules []interface{}

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 RulesResult Uses

❖
type RulesResult struct {
    Groups []RuleGroup `json:"groups"`
}

RulesResult contains the result from querying the rules endpoint.

type RuntimeinfoResult Uses

❖
type RuntimeinfoResult struct {
    StartTime           time.Time `json:"startTime"`
    CWD                 string    `json:"CWD"`
    ReloadConfigSuccess bool      `json:"reloadConfigSuccess"`
    LastConfigTime      time.Time `json:"lastConfigTime"`
    ChunkCount          int       `json:"chunkCount"`
    TimeSeriesCount     int       `json:"timeSeriesCount"`
    CorruptionCount     int       `json:"corruptionCount"`
    GoroutineCount      int       `json:"goroutineCount"`
    GOMAXPROCS          int       `json:"GOMAXPROCS"`
    GOGC                string    `json:"GOGC"`
    GODEBUG             string    `json:"GODEBUG"`
    StorageRetention    string    `json:"storageRetention"`
}

RuntimeinfoResult contains the result from querying the runtimeinfo endpoint.

type SnapshotResult Uses

❖
type SnapshotResult struct {
    Name string `json:"name"`
}

SnapshotResult contains the result from querying the snapshot endpoint.

type Stat Uses

❖
type Stat struct {
    Name  string `json:"name"`
    Value uint64 `json:"value"`
}

Stat models information about statistic value.

type TSDBResult Uses

❖
type TSDBResult struct {
    SeriesCountByMetricName     []Stat `json:"seriesCountByMetricName"`
    LabelValueCountByLabelName  []Stat `json:"labelValueCountByLabelName"`
    MemoryInBytesByLabelName    []Stat `json:"memoryInBytesByLabelName"`
    SeriesCountByLabelValuePair []Stat `json:"seriesCountByLabelValuePair"`
}

TSDBResult contains the result from querying the tsdb endpoint.

type TargetsResult Uses

❖
type TargetsResult struct {
    Active  []ActiveTarget  `json:"activeTargets"`
    Dropped []DroppedTarget `json:"droppedTargets"`
}

TargetsResult contains the result from querying the targets endpoint.

type Warnings Uses

❖
type Warnings []string

Warnings is an array of non critical errors

Package v1 imports 13 packages (graph) and is imported by 154 packages. Updated 2020-11-20. Refresh now. Tools for package owners.