metrics

Documentation

Overview

Package metrics provides backend-agnostic service instrumentation.

New code should create clients from explicit registries and pass the resulting Recorder or *Client through application composition:

import "github.com/InsideGallery/core/metrics"

registry := metrics.NewRegistry()
client, err := metrics.NewFromOptions(metrics.Options{Service: "api", Registry: registry})

Prefer Recorder, Metric, RecordResult, NewRegistry, NewWithRegistry, and InstallDefault when a scoped compatibility default is still needed.

Compatibility: Register, RegisteredProcessors, SetDefault, Default, and New remain available for existing package-level wiring. New code should avoid hidden process state and pass clients explicitly.

Index

• func NormalizeTags(tags []string) []string
• func Register(kind string, factory Factory)
• func RegisteredProcessors() []string
• func SetDefault(c *Client)
• func TagSet(tags []string) string
• type Client
  • func Default() *Client
  • func New(cfg Config, service string) (*Client, error)
  • func NewFromOptions(options Options) (*Client, error)
  • func NewWithRegistry(registry *Registry, cfg Config, service string) (*Client, error)
  • func (c *Client) Close() error
  • func (c *Client) Count(name string, value int64, tags []string) error
  • func (c *Client) CountMetric(ctx context.Context, metric Metric) (RecordResult, error)
  • func (c *Client) Distribution(name string, value float64, tags []string) error
  • func (c *Client) DistributionMetric(ctx context.Context, metric Metric) (RecordResult, error)
  • func (c *Client) Gauge(name string, value float64, tags []string) error
  • func (c *Client) GaugeMetric(ctx context.Context, metric Metric) (RecordResult, error)
  • func (c *Client) HealthCheck() error
• type Config
  • func GetEnvConfig(prefix ...string) (Config, error)
  • func (c Config) Enabled() bool
  • func (c Config) EnabledProcessors() []string
• type DefaultHandle
  • func InstallDefault(c *Client) *DefaultHandle
  • func (h *DefaultHandle) Client() *Client
  • func (h *DefaultHandle) Close() error
• type DefaultRegistryHandle
  • func InstallDefaultRegistry(registry *Registry) *DefaultRegistryHandle
  • func (h *DefaultRegistryHandle) Close() error
• type Factory
• type HealthChecker
• type Metric
• type Options
• type Processor
• type RecordResult
• type Recorder
• type Registry
  • func DefaultRegistry() *Registry
  • func NewRegistry() *Registry
  • func (r *Registry) New(cfg Config, service string) (*Client, error)
  • func (r *Registry) Register(kind string, factory Factory)
  • func (r *Registry) RegisteredProcessors() []string

Functions

func NormalizeTags

func NormalizeTags(tags []string) []string

NormalizeTags returns a stable copy of tags suitable for processors.

func Register

func Register(kind string, factory Factory)

Register makes a metrics processor available by kind.

Deprecated: use NewRegistry and register processors on the explicit registry.

func RegisteredProcessors

func RegisteredProcessors() []string

RegisteredProcessors returns all registered processor names.

Deprecated: use Registry.RegisteredProcessors on an explicit registry.

func SetDefault

func SetDefault(c *Client)

SetDefault stores the process-wide metrics client for service-specific instrumentation.

Deprecated: pass *Client explicitly or use InstallDefault for a scoped compatibility default.

func TagSet

func TagSet(tags []string) string

TagSet returns a stable tag-set string for processors that cannot model arbitrary labels.

Types

type Client

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

Client fans metric calls out to configured processors.

func Default

func Default() *Client

Default returns the process-wide metrics client, or nil when metrics are disabled.

Deprecated: pass *Client explicitly instead of reading package-level state.

func New

func New(cfg Config, service string) (*Client, error)

New creates a metrics client from configured processors. Returns nil if cfg is not enabled.

Deprecated: use NewWithRegistry or Registry.New with an explicit registry.

func NewFromOptions

func NewFromOptions(options Options) (*Client, error)

NewFromOptions creates a metrics client from core-owned options.

func NewWithRegistry

func NewWithRegistry(registry *Registry, cfg Config, service string) (*Client, error)

NewWithRegistry creates a metrics client from an explicit processor registry.

func (*Client) Close

func (c *Client) Close() error

Close flushes pending metrics and closes all processors.

func (*Client) Count

func (c *Client) Count(name string, value int64, tags []string) error

Count records a count metric.

func (*Client) CountMetric

func (c *Client) CountMetric(ctx context.Context, metric Metric) (RecordResult, error)

CountMetric records a count metric through the core-owned Recorder contract.

func (*Client) Distribution

func (c *Client) Distribution(name string, value float64, tags []string) error

Distribution records a distribution metric.

func (*Client) DistributionMetric

func (c *Client) DistributionMetric(ctx context.Context, metric Metric) (RecordResult, error)

Distribution records a distribution metric through the core-owned Recorder contract.

func (*Client) Gauge

func (c *Client) Gauge(name string, value float64, tags []string) error

Gauge records a gauge metric.

func (*Client) GaugeMetric

func (c *Client) GaugeMetric(ctx context.Context, metric Metric) (RecordResult, error)

GaugeMetric records a gauge metric through the core-owned Recorder contract.

func (*Client) HealthCheck

func (c *Client) HealthCheck() error

HealthCheck verifies all processors that expose a health check.

type Config

type Config struct {
	Processors []string `env:"_PROCESSORS" envDefault:"prometheus"`
}

Config holds backend-agnostic metrics configuration.

func GetEnvConfig

func GetEnvConfig(prefix ...string) (Config, error)

GetEnvConfig reads metrics configuration from environment variables. Default prefix is METRICS. Processor-specific packages own their own env config.

func (Config) Enabled

func (c Config) Enabled() bool

Enabled reports whether any processor is configured.

func (Config) EnabledProcessors

func (c Config) EnabledProcessors() []string

EnabledProcessors returns the configured processors.

type DefaultHandle

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

DefaultHandle restores a package-level metrics default and closes its client.

func InstallDefault

func InstallDefault(c *Client) *DefaultHandle

InstallDefault installs a process-wide metrics default with an explicit close path.

func (*DefaultHandle) Client

func (h *DefaultHandle) Client() *Client

Client returns the installed default client.

func (*DefaultHandle) Close

func (h *DefaultHandle) Close() error

Close restores the previous default client and closes the installed client.

type DefaultRegistryHandle

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

DefaultRegistryHandle restores a previous package-level processor registry.

func InstallDefaultRegistry

func InstallDefaultRegistry(registry *Registry) *DefaultRegistryHandle

InstallDefaultRegistry installs a scoped package-level processor registry.

func (*DefaultRegistryHandle) Close

func (h *DefaultRegistryHandle) Close() error

Close restores the previous package-level processor registry.

type Factory

type Factory func(Config, string) (Processor, error)

Factory creates a concrete metrics processor for a service.

type HealthChecker

type HealthChecker interface {
	HealthCheck() error
}

HealthChecker is implemented by processors that can verify exporter health.

type Metric

type Metric struct {
	Name  string
	Tags  []string
	Int   int64
	Float float64
}

Metric is the core-owned input for recording a metric value.

type Options

type Options struct {
	Service    string
	Processors []string
	Registry   *Registry
}

Options is the core-owned configuration for constructing a metrics client.

type Processor

type Processor interface {
	Close() error
	Count(name string, value int64, tags []string) error
	Gauge(name string, value float64, tags []string) error
	Distribution(name string, value float64, tags []string) error
}

Processor records metrics for one concrete backend.

type RecordResult

type RecordResult struct {
	Kind           string
	Name           string
	ProcessorCount int
}

RecordResult describes a completed metric recording operation.

type Recorder

type Recorder interface {
	CountMetric(ctx context.Context, metric Metric) (RecordResult, error)
	GaugeMetric(ctx context.Context, metric Metric) (RecordResult, error)
	DistributionMetric(ctx context.Context, metric Metric) (RecordResult, error)
	Close() error
	HealthCheck() error
}

Recorder is the core-owned metrics boundary for application code.

type Registry

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

Registry owns metrics processor factories for explicit application composition.

func DefaultRegistry

func DefaultRegistry() *Registry

DefaultRegistry returns the package-level compatibility processor registry.

func NewRegistry

func NewRegistry() *Registry

NewRegistry creates an isolated metrics processor registry.

func (*Registry) New

func (r *Registry) New(cfg Config, service string) (*Client, error)

New creates a metrics client from this registry and configured processors. Returns nil if cfg is not enabled.

func (*Registry) Register

func (r *Registry) Register(kind string, factory Factory)

Register makes a metrics processor available by kind on this registry.

func (*Registry) RegisteredProcessors

func (r *Registry) RegisteredProcessors() []string

RegisteredProcessors returns all processor names registered on this registry.