vmclient

README

vmclient

Simple HTTP client for Victoria Metrics.

Pushing data

package main

import (
	"context"
	"log"

	"github.com/VictoriaMetrics/metrics"
	"github.com/vodolaz095/vmclient"
)

func main() {
	ctx := context.TODO()
	
	client, err := vmclient.New(ctx, vmclient.Config{
		Address:     vmclient.DefaultEndpoint,
		ExtraLabels: `unit="test"`,
	})
	if err != nil {
		log.Fatalf("error creating client: %s", err)
	}
	
	err = client.PushGauge(context.TODO(), `something{job="vmclient_example"}`, 10)
	if err != nil {
		log.Fatalf("error pushing gauge: %s", err)
	}
	
	err = client.PushCounter(context.TODO(), `something_cnt{job="vmclient_example"}`, 10)
	if err != nil {
		log.Fatalf("error pushing counter: %s", err)
	}
	
	err = client.Push(context.TODO(), metrics.GetDefaultSet())
	if err != nil {
		log.Fatalf("error pushing set: %s", err)
	}
	
	err = client.Close(ctx)
	if err != nil {
		log.Fatalf("error closing client: %s", err)
	}
	log.Printf("all data pushed, check %s for details", vmclient.DefaultEndpoint+"/vmui/?#/?g0.range_input=30m&g0.end_input=2026-01-08T17%3A46%3A23&g0.relative_time=last_30_minutes&g0.tab=0&g0.expr=something&g1.expr=something_cnt&g1.range_input=30m&g1.relative_time=last_30_minutes&g1.tab=0")
}

Instant query

Endpoint https://docs.victoriametrics.com/victoriametrics/keyconcepts/#instant-query is used

package main

import (
	"context"
	"log"
	"time"

	"github.com/vodolaz095/vmclient"
)

func main() {
	ctx := context.TODO()
	
	client, err := vmclient.New(ctx, vmclient.Config{
		Address:     vmclient.DefaultEndpoint,
		ExtraLabels: `unit="test"`,
	})
	if err != nil {
		log.Fatalf("error creating client: %s", err)
	}
	
	metrics, err := client.Instant(context.TODO(), "something", time.Now(), 5*time.Minute)
	if err != nil {
		log.Fatalf("error pushing set: %s", err)
	}
	for i := range metrics {
		log.Printf("Metric %s had value %v on %s",
			metrics[i].String(), metrics[i].Value, metrics[i].Timestamp.Format(time.DateTime))
	}

	err = client.Close(ctx)
	if err != nil {
		log.Fatalf("error closing client: %s", err)
	}
}

Range query

Endpoint https://docs.victoriametrics.com/victoriametrics/keyconcepts/#range-query is used

package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"github.com/vodolaz095/vmclient"
)

func main() {
	ctx := context.TODO()

	client, err := vmclient.New(ctx, vmclient.Config{
		Address:     vmclient.DefaultEndpoint,
		ExtraLabels: `unit="test"`,
	})
	if err != nil {
		log.Fatalf("error creating client: %s", err)
	}

	lines, err := client.Range(context.TODO(), "something", time.Now().Add(-time.Hour), time.Now(), 5*time.Minute)
	if err != nil {
		log.Fatalf("error pushing set: %s", err)
	}
	for i := range lines {
		fmt.Printf("Found line for metric %s...\n", lines[i].String())
		for j := range lines[i].Values {
			fmt.Printf("%v) value %v on %s\n",
				j, lines[i].Values[j].Value, lines[i].Values[j].Timestamp.Format(time.DateTime))
		}
	}

	err = client.Close(ctx)
	if err != nil {
		log.Fatalf("error closing client: %s", err)
	}
}

Documentation

Index

• Constants
• Variables
• type Client
  • func New(ctx context.Context, cfg Config) (vmc *Client, err error)
  • func (c *Client) Close(context.Context) (err error)
  • func (c *Client) Instant(initialCtx context.Context, query string, when time.Time, step time.Duration) (data []Instant, err error)
  • func (c *Client) Ping(initialCtx context.Context) (err error)
  • func (c *Client) Push(initialCtx context.Context, set *metrics.Set) error
  • func (c *Client) PushCounter(ctx context.Context, name string, value uint64) error
  • func (c *Client) PushGauge(ctx context.Context, name string, value float64) error
  • func (c *Client) Range(initialCtx context.Context, query string, start, end time.Time, ...) (data []Range, err error)
• type Config
• type Err
  • func (ei Err) As(target any) bool
  • func (ei Err) Error() string
  • func (ei Err) Is(target error) bool
  • func (ei Err) Unwrap() error
• type Instant
  • func (i *Instant) Name() string
  • func (i *Instant) String() string
• type Range
  • func (r *Range) Name() string
  • func (r *Range) String() string
• type Result

Constants

const DefaultEndpoint = "http://127.0.0.1:8428"

const DefaultPushEndpoint = "/api/v1/import/prometheus"

const DefaultStep = 5 * time.Minute

const LabelForName = "__name__"

Variables

var (
	// ErrUnexpectedResponse happens, when Victoria Metrics gives unexpected response
	ErrUnexpectedResponse = errors.New("unexpected response")
	// ErrQueryError happens, when Victoria Metrics cannot process query
	ErrQueryError = errors.New("query error")
)

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

func New

func New(ctx context.Context, cfg Config) (vmc *Client, err error)

func (*Client) Close

func (c *Client) Close(context.Context) (err error)

func (*Client) Instant

func (c *Client) Instant(initialCtx context.Context, query string, when time.Time, step time.Duration) (data []Instant, err error)

Instant makes instant query described here https://docs.victoriametrics.com/victoriametrics/keyconcepts/#instant-query

func (*Client) Ping

func (c *Client) Ping(initialCtx context.Context) (err error)

Ping checks if database accepts connections

func (*Client) Push

func (c *Client) Push(initialCtx context.Context, set *metrics.Set) error

Push sends metrics set

func (*Client) PushCounter

func (c *Client) PushCounter(ctx context.Context, name string, value uint64) error

PushCounter pushes counter

func (*Client) PushGauge

func (c *Client) PushGauge(ctx context.Context, name string, value float64) error

PushGauge pushes metrics gauge

func (*Client) Range

func (c *Client) Range(initialCtx context.Context, query string, start, end time.Time, step time.Duration) (data []Range, err error)

Range makes range query as described here https://docs.victoriametrics.com/victoriametrics/keyconcepts/#range-query

type Config

type Config struct {
	Address     string
	Headers     map[string]string
	ExtraLabels string
	HttpClient  *http.Client
	Insecure    bool
}

Config defines connection parameters

type Err

type Err struct {
	Code     int
	Message  string
	Response string
	Err      error
}

Err is custom error

func (Err) As

func (ei Err) As(target any) bool

func (Err) Error

func (ei Err) Error() string

func (Err) Is

func (ei Err) Is(target error) bool

func (Err) Unwrap

func (ei Err) Unwrap() error

type Instant

type Instant struct {
	Result
	Labels map[string]string
}

func (*Instant) Name

func (i *Instant) Name() string

func (*Instant) String

func (i *Instant) String() string

type Range

type Range struct {
	Labels map[string]string
	Values []Result
}

func (*Range) Name

func (r *Range) Name() string

func (*Range) String

func (r *Range) String() string

type Result

type Result struct {
	Value     float64
	Timestamp time.Time
}