rkprom

package module
v1.1.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 9, 2021 License: Apache-2.0 Imports: 19 Imported by: 3

README

rk-prom

build codecov Go Report Card License

A simple prometheus initializer. What rk-prom trying to do is described as bellow:

  • Start prometheus client by calling StartProm()
  • Start prometheus client by providing yaml config
  • Start a daemon thread which will periodically push local prometheus metrics to PushGateway
  • Simple wrapper of Counter, Gauge, Summary, Histogram like POJO with GetXXX(), RegisterXXX(), UnRegisterXXX()
  • Go & Process collector variables which is originally implemented by prometheus client package.

Table of Contents generated with DocToc

Installation

go get -u github.com/rookie-ninja/rk-prom

Development Status: Active

In Prod version.

Quick start

Start with Bootstrap() with code

package main

import (
	"github.com/rookie-ninja/rk-prom"
	"github.com/rookie-ninja/rk-query"
	"time"
)

func main() {
	// create prom entry
	entry := rkprom.RegisterPromEntry()

	// start server
	entry.Bootstrap(context.TODO())

	// stop server
	entry.Interrupt(context.TODO())
}

Start with Bootstrap() with config file

---
prom:
  enabled: true
#  port: 1608
#  path: metrics
#  pusher:
#    enabled: false
#    intervalMS: 1
#    jobName: "rk-job"
#    remoteAddress: "localhost:9091"
#    basicAuth: "user:pass"

package main

import (
	"github.com/rookie-ninja/rk-prom"
	"github.com/rookie-ninja/rk-query"
	"time"
)

func main() {
	rkentry.RegisterInternalEntriesFromConfig("example/boot.yaml")

	maps := rkprom.RegisterPromEntriesWithConfig("example/boot.yaml")

	entry := maps[rkprom.PromEntryNameDefault]
	entry.Bootstrap(context.TODO())

	rkentry.GlobalAppCtx.WaitForShutdownSig()
    
	// stop server
	entry.Interrupt(context.TODO())
}
Name Description Option Default Value
prom.enabled Enable prometheus bool false
prom.port Prometheus port integer 1608
prom.path Prometheus path string metrics
prom.pusher.enabled Enable push gateway pusher bool false
prom.pusher.intervalMS Push interval to remote push gateway integer 0
prom.pusher.jobName Pusher job name string empty string
prom.pusher.remoteAddress Pusher url string empty string
prom.pusher.basicAuth basic auth as user:password string empty string

Example

  • Working with Counter (namespace and subsystem)
metricsSet := rkprom.NewMetricsSet("my_namespace", "my_service")

metricsSet.RegisterCounter("counter", "key_1")

metricsSet.GetCounterWithValues("counter", "value_1").Inc()
metricsSet.GetCounterWithLabels("counter", prometheus.Labels{"key_1":"value_1"}).Inc()
  • Working with Gauge (namespace and subsystem)
metricsSet := rkprom.NewMetricsSet("my_namespace", "my_service")
metricsSet.RegisterGauge("gauge", "key_1")

metricsSet.GetGaugeWithValues("gauge", "value_1").Inc()
metricsSet.GetGaugeWithLabels("gauge", prometheus.Labels{"key_1":"value_1"}).Inc()
  • Working with Summary (custom namespace and subsystem)
metricsSet := rkprom.NewMetricsSet("my_namespace", "my_service")
metricsSet.RegisterSummary("summary", rk_prom.SummaryObjectives, "key_1")

metricsSet.GetSummaryWithValues("summary", "value_1").Observe(1.0)
metricsSet.GetSummaryWithLabels("summary", prometheus.Labels{"key_1":"value_1"}).Observe(1.0)
  • Working with Histogram (custom namespace and subsystem)
metricsSet := rkprom.NewMetricsSet("new_namespace", "new_service")
metricsSet.RegisterHistogram("histogram", []float64{}, "key_1")

metricsSet.GetHistogramWithValues("histogram", "value_1").Observe(1.0)
metricsSet.GetHistogramWithLabels("histogram", prometheus.Labels{"key_1":"value_1"}).Observe(1.0)
  • Working with PushGateway publisher
pusher, _ := NewPushGatewayPusher(
	WithIntervalMSPusher(2 * time.Second),
	WithRemoteAddressPusher("localhost:8888"),
	WithJobNamePusher("test_job"))

pusher.Start()
defer pusher.Shutdown()

time.Sleep(2 * time.Second)

Contributing

We encourage and support an active, healthy community of contributors — including you! Details are in the contribution guide and the code of conduct. The pulse-line maintainers keep an eye on issues and pull requests. So don't hesitate to hold us to a high standard.

Documentation

Overview

Package rkprom has couple of utility functions to start prometheus and pushgateway client locally.

Index

Constants

View Source 
const (
	// PromEntryNameDefault default entry name
	PromEntryNameDefault = "PromDefault"
	// PromEntryType default entry type
	PromEntryType = "PromEntry"
	// PromEntryDescription default entry description
	PromEntryDescription = "Internal RK entry which implements prometheus client."
)

Variables

View Source 
var SummaryObjectives = map[float64]float64{0.5: 0.05, 0.9: 0.01, 0.99: 0.001, 0.999: 0.0001}

SummaryObjectives will track quantile of P50, P90, P99, P9999 by default.

Functions

func RegisterPromEntriesWithConfig added in v1.1.0 

func RegisterPromEntriesWithConfig(configFilePath string) map[string]rkentry.Entry

RegisterPromEntriesWithConfig creates a new prom entry from config. Although it returns a map of prom entries, only one prom entry would be assigned to map the reason is for compatibility with rk_ctx.RegisterEntryInitializer path could be either relative or absolute directory

Types

type BootConfigProm added in v1.1.0 

type BootConfigProm struct {
	Prom struct {
		Path    string `yaml:"path" json:"path"`
		Port    uint64 `yaml:"port" json:"port"`
		Enabled bool   `yaml:"enabled" json:"enabled"`
		Pusher  struct {
			Enabled       bool   `yaml:"enabled" json:"enabled"`
			IntervalMs    int64  `yaml:"intervalMs" json:"intervalMs"`
			JobName       string `yaml:"jobName" json:"jobName"`
			RemoteAddress string `yaml:"remoteAddress" json:"remoteAddress"`
			BasicAuth     string `yaml:"basicAuth" json:"basicAuth"`
			Cert          struct {
				Ref string `yaml:"ref" json:"ref"`
			} `yaml:"cert" json:"cert"`
		} `yaml:"pusher" json:"pusher"`
		Cert struct {
			Ref string `yaml:"ref" json:"ref"`
		} `yaml:"cert" json:"cert"`
		Logger struct {
			ZapLogger struct {
				Ref string `yaml:"ref" json:"ref"`
			} `yaml:"zapLogger" json:"zapLogger"`
			EventLogger struct {
				Ref string `yaml:"ref" json:"ref"`
			} `yaml:"eventLogger" json:"eventLogger"`
		} `yaml:"logger" json:"logger"`
	} `yaml:"prom" json:"prom"`
}

BootConfigProm which is for prom entry.

1: Path: PromEntry path, /metrics is default value. 2: Enabled: Enable prom entry. 3: Pusher.Enabled: Enable pushgateway pusher. 4: Pusher.IntervalMS: Interval of pushing metrics to remote pushgateway in milliseconds. 5: Pusher.JobName: Job name would be attached as label while pushing to remote pushgateway. 6: Pusher.RemoteAddress: Pushgateway address, could be form of http://x.x.x.x or x.x.x.x 7: Pusher.BasicAuth: Basic auth used to interact with remote pushgateway. 8: Pusher.Cert.Ref: Reference of rkentry.CertEntry. 9: Cert.Ref: Reference of rkentry.CertEntry.

type MetricsSet 

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

MetricsSet is a collections of counter, gauge, summary, histogram and link to certain registerer. User need to provide own prometheus.Registerer.

1: namespace: the namespace of prometheus metrics 2: sysSystem: the subSystem of prometheus metrics 3: keys: a map stores all keys 4: counters: map of counters 5: gauges: map of gauges 6: summaries: map of summaries 7: histograms: map of histograms 8: lock: lock for thread safety 9: registerer prometheus.Registerer

func NewMetricsSet 

func NewMetricsSet(namespace, subSystem string, registerer prometheus.Registerer) *MetricsSet

NewMetricsSet creates metrics set with namespace, subSystem and registerer.

If no registerer was provided, then prometheus.DefaultRegisterer would be used.

Important! namespace, subSystem, labels should match prometheus regex as bellow ^[a-zA-Z_:][a-zA-Z0-9_:]*$ If provided name is not valid, then default ones would be assigned

func (*MetricsSet) GetCounter added in v1.1.0 

func (set *MetricsSet) GetCounter(name string) *prometheus.CounterVec

GetCounter is thread safe

func (*MetricsSet) GetCounterWithLabels 

func (set *MetricsSet) GetCounterWithLabels(name string, labels prometheus.Labels) prometheus.Counter

GetCounterWithLabels is thread safe

Get counter with values matched with labels Users should always be sure about the number of labels.

func (*MetricsSet) GetCounterWithValues 

func (set *MetricsSet) GetCounterWithValues(name string, values ...string) prometheus.Counter

GetCounterWithValues is thread safe

Get counter with values matched with labels Users should always be sure about the number of labels.

func (*MetricsSet) GetGauge added in v1.1.0 

func (set *MetricsSet) GetGauge(name string) *prometheus.GaugeVec

GetGauge is thread safe

func (*MetricsSet) GetGaugeWithLabels 

func (set *MetricsSet) GetGaugeWithLabels(name string, labels prometheus.Labels) prometheus.Gauge

GetGaugeWithLabels is thread safe Get gauge with values matched with labels Users should always be sure about the number of labels.

func (*MetricsSet) GetGaugeWithValues 

func (set *MetricsSet) GetGaugeWithValues(name string, values ...string) prometheus.Gauge

GetGaugeWithValues is thread safe

Get gauge with values matched with labels Users should always be sure about the number of labels.

func (*MetricsSet) GetHistogram added in v1.1.0 

func (set *MetricsSet) GetHistogram(name string) *prometheus.HistogramVec

GetHistogram is thread safe

func (*MetricsSet) GetHistogramWithLabels 

func (set *MetricsSet) GetHistogramWithLabels(name string, labels prometheus.Labels) prometheus.Observer

GetHistogramWithLabels is thread safe

Get histogram with values matched with labels Users should always be sure about the number of labels.

func (*MetricsSet) GetHistogramWithValues 

func (set *MetricsSet) GetHistogramWithValues(name string, values ...string) prometheus.Observer

GetHistogramWithValues is thread safe

Get histogram with values matched with labels Users should always be sure about the number of labels.

func (*MetricsSet) GetNamespace 

func (set *MetricsSet) GetNamespace() string

GetNamespace returns namespace

func (*MetricsSet) GetRegisterer added in v1.1.0 

func (set *MetricsSet) GetRegisterer() prometheus.Registerer

GetRegisterer returns registerer

func (*MetricsSet) GetSubSystem 

func (set *MetricsSet) GetSubSystem() string

GetSubSystem returns subsystem

func (*MetricsSet) GetSummary added in v1.1.0 

func (set *MetricsSet) GetSummary(name string) *prometheus.SummaryVec

GetSummary is thread safe

func (*MetricsSet) GetSummaryWithLabels 

func (set *MetricsSet) GetSummaryWithLabels(name string, labels prometheus.Labels) prometheus.Observer

GetSummaryWithLabels is thread safe

Get summary with values matched with labels Users should always be sure about the number of labels.

func (*MetricsSet) GetSummaryWithValues 

func (set *MetricsSet) GetSummaryWithValues(name string, values ...string) prometheus.Observer

GetSummaryWithValues is thread safe

Get summary with values matched with labels Users should always be sure about the number of labels.

func (*MetricsSet) ListCounters 

func (set *MetricsSet) ListCounters() []*prometheus.CounterVec

ListCounters is thread safe

func (*MetricsSet) ListGauges added in v1.1.0 

func (set *MetricsSet) ListGauges() []*prometheus.GaugeVec

ListGauges is thread safe

func (*MetricsSet) ListHistograms added in v1.1.0 

func (set *MetricsSet) ListHistograms() []*prometheus.HistogramVec

ListHistograms is thread safe

func (*MetricsSet) ListSummaries added in v1.1.0 

func (set *MetricsSet) ListSummaries() []*prometheus.SummaryVec

ListSummaries is thread safe

func (*MetricsSet) RegisterCounter 

func (set *MetricsSet) RegisterCounter(name string, labelKeys ...string) error

RegisterCounter is thread safe Register a counter with namespace and subsystem in MetricsSet

func (*MetricsSet) RegisterGauge 

func (set *MetricsSet) RegisterGauge(name string, labelKeys ...string) error

RegisterGauge thread safe Register a gauge with namespace and subsystem in MetricsSet

func (*MetricsSet) RegisterHistogram 

func (set *MetricsSet) RegisterHistogram(name string, bucket []float64, labelKeys ...string) error

RegisterHistogram thread safe Register a histogram with namespace, subsystem and objectives in MetricsSet If bucket is nil, then empty bucket would be applied

func (*MetricsSet) RegisterSummary 

func (set *MetricsSet) RegisterSummary(name string, objectives map[float64]float64, labelKeys ...string) error

RegisterSummary thread safe Register a summary with namespace, subsystem and objectives in MetricsSet If objectives is nil, then default SummaryObjectives would be applied

func (*MetricsSet) UnRegisterCounter 

func (set *MetricsSet) UnRegisterCounter(name string)

UnRegisterCounter is thread safe Unregister metrics, error would be thrown only when invalid name was provided

func (*MetricsSet) UnRegisterGauge 

func (set *MetricsSet) UnRegisterGauge(name string)

UnRegisterGauge thread safe Unregister metrics, error would be thrown only when invalid name was provided

func (*MetricsSet) UnRegisterHistogram 

func (set *MetricsSet) UnRegisterHistogram(name string)

UnRegisterHistogram thread safe Unregister metrics, error would be thrown only when invalid name was provided

func (*MetricsSet) UnRegisterSummary 

func (set *MetricsSet) UnRegisterSummary(name string)

UnRegisterSummary thread safe Unregister metrics, error would be thrown only when invalid name was provided

type PromEntry added in v1.0.2 

type PromEntry struct {
	Pusher           *PushGatewayPusher        `json:"pushGatewayPusher" yaml:"pushGatewayPusher"`
	EntryName        string                    `json:"entryName" yaml:"entryName"`
	EntryType        string                    `json:"entryType" yaml:"entryType"`
	EntryDescription string                    `json:"entryDescription" yaml:"entryDescription"`
	ZapLoggerEntry   *rkentry.ZapLoggerEntry   `json:"zapLoggerEntry" yaml:"zapLoggerEntry"`
	EventLoggerEntry *rkentry.EventLoggerEntry `json:"eventLoggerEntry" yaml:"eventLoggerEntry"`
	CertEntry        *rkentry.CertEntry        `json:"certEntry" yaml:"certEntry"`
	Port             uint64                    `json:"port" yaml:"port"`
	Path             string                    `json:"path" yaml:"path"`
	Server           *http.Server              `json:"-" yaml:"-"`
	Registry         *prometheus.Registry      `json:"-" yaml:"-"`
	Registerer       prometheus.Registerer     `json:"-" yaml:"-"`
	Gatherer         prometheus.Gatherer       `json:"-" yaml:"-"`
}

PromEntry which implements rkentry.Entry.

1: Pusher Periodic pushGateway pusher 2: ZapLoggerEntry rkentry.ZapLoggerEntry 3: EventLoggerEntry rkentry.EventLoggerEntry 4: Port Exposed port by prom entry 5: Path Exposed path by prom entry 6: Registry Prometheus registry 7: Registerer Prometheus registerer 8: Gatherer Prometheus gatherer 9: CertEntry rkentry.CertEntry

func RegisterPromEntry added in v1.1.0 

func RegisterPromEntry(opts ...PromEntryOption) *PromEntry

RegisterPromEntry creates a prom entry with options and add prom entry to rk_ctx.GlobalAppCtx

func (*PromEntry) Bootstrap added in v1.0.2 

func (entry *PromEntry) Bootstrap(context.Context)

Bootstrap will start prometheus client

func (*PromEntry) GetDescription added in v1.1.0 

func (entry *PromEntry) GetDescription() string

GetDescription returns description of entry

func (*PromEntry) GetName added in v1.0.2 

func (entry *PromEntry) GetName() string

GetName return name of prom entry

func (*PromEntry) GetType added in v1.0.2 

func (entry *PromEntry) GetType() string

GetType return type of prom entry

func (*PromEntry) Interrupt added in v1.1.0 

func (entry *PromEntry) Interrupt(context.Context)

Interrupt will Shutdown prometheus client

func (*PromEntry) MarshalJSON added in v1.1.0 

func (entry *PromEntry) MarshalJSON() ([]byte, error)

MarshalJSON will marshal entry into JSON

func (*PromEntry) RegisterCollectors added in v1.1.0 

func (entry *PromEntry) RegisterCollectors(collectors ...prometheus.Collector) error

RegisterCollectors register collectors

func (*PromEntry) String added in v1.0.2 

func (entry *PromEntry) String() string

String returns prom entry as string

func (*PromEntry) UnmarshalJSON added in v1.1.0 

func (entry *PromEntry) UnmarshalJSON([]byte) error

UnmarshalJSON will unmarshal entry

type PromEntryOption added in v1.0.2 

type PromEntryOption func(*PromEntry)

PromEntryOption is used while initializing prom entry via code

func WithCertEntry added in v1.1.0 

func WithCertEntry(certEntry *rkentry.CertEntry) PromEntryOption

WithCertEntry provides cert entry

func WithDescription added in v1.1.3 

func WithDescription(description string) PromEntryOption

WithDescription provides entry description

func WithEventLoggerEntry added in v1.1.0 

func WithEventLoggerEntry(eventLoggerEntry *rkentry.EventLoggerEntry) PromEntryOption

WithEventLoggerEntry provides event factory of prom entry

func WithName added in v1.1.0 

func WithName(name string) PromEntryOption

WithName provides entry name

func WithPath added in v1.0.2 

func WithPath(path string) PromEntryOption

WithPath provides path of prom entry

func WithPort added in v1.0.2 

func WithPort(port uint64) PromEntryOption

WithPort provides port of prom entry

func WithPromRegistry added in v1.1.0 

func WithPromRegistry(registry *prometheus.Registry) PromEntryOption

WithPromRegistry provides a new prometheus registry

func WithPusher added in v1.1.0 

func WithPusher(pusher *PushGatewayPusher) PromEntryOption

WithPusher provides pushGateway of prom entry

func WithZapLoggerEntry added in v1.1.0 

func WithZapLoggerEntry(zapLoggerEntry *rkentry.ZapLoggerEntry) PromEntryOption

WithZapLoggerEntry provides logger of prom entry

type PushGatewayPusher added in v1.0.3 

type PushGatewayPusher struct {
	ZapLoggerEntry   *rkentry.ZapLoggerEntry   `json:"zapLoggerEntry" yaml:"zapLoggerEntry"`
	EventLoggerEntry *rkentry.EventLoggerEntry `json:"eventLoggerEntry" yaml:"eventLoggerEntry"`
	CertStore        *rkentry.CertStore        `json:"certStore" yaml:"certStore"`
	Pusher           *push.Pusher              `json:"-" yaml:"-"`
	IntervalMs       time.Duration             `json:"intervalMs" yaml:"intervalMs"`
	RemoteAddress    string                    `json:"remoteAddress" yaml:"remoteAddress"`
	JobName          string                    `json:"jobName" yaml:"jobName"`
	Running          *atomic.Bool              `json:"running" yaml:"running"`

	Credential string `json:"-" yaml:"-"`
	// contains filtered or unexported fields
}

PushGatewayPusher is a pusher which contains bellow instances thread safe

1: logger: zap logger for logging periodic job information 2: pusher: prometheus pusher which will push metrics to remote pushGateway 3: intervalMS: periodic job interval in milliseconds 4: remoteAddress: remote pushGateway URL. You can use just host:port or ip:port as url, 

in which case “http://” is added automatically. Alternatively, include the
schema in the URL. However, do not include the “/metrics/jobs/…” part.

5: jobName: job name of periodic job 6: isRunning: a boolean flag for validating status of periodic job 7: lock: a mutex lock for thread safety 8: credential: basic auth credential

func NewPushGatewayPusher added in v1.1.0 

func NewPushGatewayPusher(opts ...PushGatewayPusherOption) (*PushGatewayPusher, error)

NewPushGatewayPusher creates a new pushGateway periodic job instances with intervalMS, remote URL and job name 1: intervalMS: should be a positive integer 2: url: should be a non empty and valid url 3: jabName: should be a non empty string 4: cred: credential of basic auth format as user:pass 5: logger: a logger with stdout output would be assigned if nil

func (*PushGatewayPusher) GetPusher added in v1.1.0 

func (pub *PushGatewayPusher) GetPusher() *push.Pusher

GetPusher simply call pusher.Gatherer() We add prefix "Add" before the function name since the original one is a little bit confusing. Thread safe

func (*PushGatewayPusher) IsRunning added in v1.0.3 

func (pub *PushGatewayPusher) IsRunning() bool

IsRunning validate whether periodic job is running or not

func (*PushGatewayPusher) SetGatherer added in v1.1.0 

func (pub *PushGatewayPusher) SetGatherer(gatherer prometheus.Gatherer)

SetGatherer sets gatherer of prometheus

func (*PushGatewayPusher) Start added in v1.0.3 

func (pub *PushGatewayPusher) Start()

Start starts a periodic job

func (*PushGatewayPusher) Stop added in v1.1.0 

func (pub *PushGatewayPusher) Stop()

Stop stops periodic job

func (*PushGatewayPusher) String added in v1.1.0 

func (pub *PushGatewayPusher) String() string

String returns string value of PushGatewayPusher

type PushGatewayPusherOption added in v1.1.0 

type PushGatewayPusherOption func(*PushGatewayPusher)

PushGatewayPusherOption is used while initializing push gateway pusher via code

func WithBasicAuthPusher added in v1.1.0 

func WithBasicAuthPusher(cred string) PushGatewayPusherOption

WithBasicAuthPusher provides basic auth of pushgateway

func WithCertStorePusher added in v1.1.0 

func WithCertStorePusher(certStore *rkentry.CertStore) PushGatewayPusherOption

WithCertStorePusher provides EventLoggerEntry

func WithEventLoggerEntryPusher added in v1.1.0 

func WithEventLoggerEntryPusher(eventLoggerEntry *rkentry.EventLoggerEntry) PushGatewayPusherOption

WithEventLoggerEntryPusher provides EventLoggerEntry

func WithIntervalMSPusher added in v1.1.0 

func WithIntervalMSPusher(intervalMs time.Duration) PushGatewayPusherOption

WithIntervalMSPusher provides interval in milliseconds

func WithJobNamePusher added in v1.1.0 

func WithJobNamePusher(jobName string) PushGatewayPusherOption

WithJobNamePusher provides job name

func WithRemoteAddressPusher added in v1.1.0 

func WithRemoteAddressPusher(remoteAddress string) PushGatewayPusherOption

WithRemoteAddressPusher provides remote address of pushgateway

func WithZapLoggerEntryPusher added in v1.1.0 

func WithZapLoggerEntryPusher(zapLoggerEntry *rkentry.ZapLoggerEntry) PushGatewayPusherOption

WithZapLoggerEntryPusher provides ZapLoggerEntry

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.