event

package
v0.0.0-...-384b27a Latest Latest
Warning

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

 Go to latest Published: Jul 17, 2021 License: BSD-3-Clause Imports: 12 Imported by: 1

Documentation

Overview

Package event provides the core functionality for observability that allows libraries using it to interact well. It enforces the middle layer interchange format, but allows both frontend wrappers and back end exporters to customize the usage.

Index

Constants

View Source 
const (
	MetricKey      = "metric"
	MetricVal      = "metricValue"
	DurationMetric = interfaceKey("durationMetric")
)
View Source 
const (
	LogKind
	MetricKind
	StartKind
	EndKind
)

Variables

This section is empty.

Functions

func Annotate 

func Annotate(ctx context.Context, labels ...Label)

func End 

func End(ctx context.Context, labels ...Label)

func Error 

func Error(ctx context.Context, msg string, err error, labels ...Label)

func Log 

func Log(ctx context.Context, msg string, labels ...Label)

func Logf 

func Logf(ctx context.Context, msg string, args ...interface{})

func RegisterHelper 

func RegisterHelper(v interface{})

RegisterHelper records a function as being an event helper that should not be used when capturing the source infomation on events. v should be either a string or a function pointer. If v is a string it is of the form 

Space.Owner.Name

where Owner and Name cannot contain '/' and Name also cannot contain '.'

func SetDefaultExporter 

func SetDefaultExporter(e *Exporter)

SetDefaultExporter sets an exporter that is used if no exporter can be found on the context.

func Start 

func Start(ctx context.Context, name string, labels ...Label) context.Context

func WithExporter 

func WithExporter(ctx context.Context, e *Exporter) context.Context

WithExporter returns a context with the exporter attached. The exporter is called synchronously from the event call site, so it should return quickly so as not to hold up user code.

Types

type Counter 

type Counter struct {
	*MetricDescriptor
}

A Counter is a metric that counts something cumulatively.

func NewCounter 

func NewCounter(name, description string) *Counter

NewCounter creates a counter with the given name.

func (*Counter) Descriptor 

func (c *Counter) Descriptor() *MetricDescriptor

Descriptor returns the receiver's MetricDescriptor.

func (*Counter) Record 

func (c *Counter) Record(ctx context.Context, v int64, labels ...Label)

Record delivers a metric event with the given metric, value and labels to the exporter in the context.

type DurationDistribution 

type DurationDistribution struct {
	*MetricDescriptor
}

A DurationDistribution records a distribution of durations. TODO(generics): Distribution[T]

func NewDuration 

func NewDuration(name, description string) *DurationDistribution

NewDuration creates a new Duration with the given name.

func (*DurationDistribution) Descriptor 

func (d *DurationDistribution) Descriptor() *MetricDescriptor

Descriptor returns the receiver's MetricDescriptor.

func (*DurationDistribution) Record 

func (d *DurationDistribution) Record(ctx context.Context, v time.Duration, labels ...Label)

Record converts its argument into a Value and returns a MetricValue with the receiver and the value. It is intended to be used as an argument to Builder.Metric.

type Event 

type Event struct {
	ID     uint64
	Parent uint64    // id of the parent event for this event
	Source Source    // source of event; if empty, set by exporter to import path
	At     time.Time // time at which the event is delivered to the exporter.
	Kind   Kind
	Labels []Label
	// contains filtered or unexported fields
}

Event holds the information about an event that occurred. It combines the event metadata with the user supplied labels.

func New 

func New(ctx context.Context, kind Kind) *Event

New prepares a new event. This is intended to avoid allocations in the steady state case, to do this it uses a pool of events. Events are returned to the pool when Deliver is called. Failure to call Deliver will exhaust the pool and cause allocations. It returns nil if there is no active exporter for this kind of event.

func (*Event) Clone 

func (ev *Event) Clone() *Event

Clone makes a deep copy of the Event. Deliver can be called on both Events independently.

func (*Event) Deliver 

func (ev *Event) Deliver() context.Context

Deliver the event to the exporter that was found in New. This also returns the event to the pool, it is an error to do anything with the event after it is delivered.

func (*Event) Find 

func (ev *Event) Find(name string) Label

func (*Event) Trace 

func (ev *Event) Trace()

type Exporter 

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

Exporter synchronizes the delivery of events to handlers.

func NewExporter 

func NewExporter(handler Handler, opts *ExporterOptions) *Exporter

NewExporter creates an Exporter using the supplied handler and options. Event delivery is serialized to enable safe atomic handling.

type ExporterOptions 

type ExporterOptions struct {
	// If non-nil, sets zero Event.At on delivery.
	Now func() time.Time

	// Disable some event types, for better performance.
	DisableLogging     bool
	DisableTracing     bool
	DisableAnnotations bool
	DisableMetrics     bool

	// Enable automatically setting the event Namespace to the calling package's
	// import path.
	EnableNamespaces bool
}

type FloatGauge 

type FloatGauge struct {
	*MetricDescriptor
}

A FloatGauge records a single floating-point value that may go up or down. TODO(generics): Gauge[T]

func NewFloatGauge 

func NewFloatGauge(name, description string) *FloatGauge

NewFloatGauge creates a new FloatGauge with the given name.

func (*FloatGauge) Descriptor 

func (g *FloatGauge) Descriptor() *MetricDescriptor

Descriptor returns the receiver's MetricDescriptor.

func (*FloatGauge) Record 

func (g *FloatGauge) Record(ctx context.Context, v float64, labels ...Label)

Record converts its argument into a Value and returns a MetricValue with the receiver and the value. It is intended to be used as an argument to Builder.Metric.

type Handler 

type Handler interface {
	// Event is called with each event.
	Event(context.Context, *Event) context.Context
}

Handler is a the type for something that handles events as they occur.

type IntDistribution 

type IntDistribution struct {
	*MetricDescriptor
}

An IntDistribution records a distribution of int64s.

func NewIntDistribution 

func NewIntDistribution(name, description string) *IntDistribution

NewIntDistribution creates a new IntDistribution with the given name.

func (*IntDistribution) Descriptor 

func (d *IntDistribution) Descriptor() *MetricDescriptor

Descriptor returns the receiver's MetricDescriptor.

func (*IntDistribution) Record 

func (d *IntDistribution) Record(ctx context.Context, v int64, labels ...Label)

Record converts its argument into a Value and returns a MetricValue with the receiver and the value. It is intended to be used as an argument to Builder.Metric.

type Kind 

type Kind int

func NewKind 

func NewKind(name string) Kind

func (Kind) String 

func (k Kind) String() string

type Label 

type Label struct {
	Name string
	// contains filtered or unexported fields
}

Label is a named value.

func Bool 

func Bool(name string, b bool) Label

Bool returns a new Value for a bool.

func Bytes 

func Bytes(name string, data []byte) Label

Bytes returns a new Value for a string.

func Duration 

func Duration(name string, d time.Duration) Label

func Float64 

func Float64(name string, f float64) Label

Float64 returns a new Value for a floating point number.

func Int64 

func Int64(name string, u int64) Label

Int64 returns a new Value for a signed integer.

func String 

func String(name string, s string) Label

String returns a new Value for a string.

func Uint64 

func Uint64(name string, u uint64) Label

Uint64 returns a new Value for an unsigned integer.

func Value 

func Value(name string, value interface{}) Label

Value returns a Label for the supplied value.

func (Label) Bool 

func (v Label) Bool() bool

Bool returns the bool from a value that was set with SetBool. It will panic for any value for which IsBool is not true.

func (Label) Bytes 

func (v Label) Bytes() []byte

Bytes returns the value as a bytes array.

func (Label) Duration 

func (v Label) Duration() time.Duration

func (Label) Equal 

func (l Label) Equal(l2 Label) bool

Equal reports whether two labels are equal.

func (Label) Float64 

func (v Label) Float64() float64

Float64 returns the float64 from a value that was set with SetFloat64. It will panic for any value for which IsFloat64 is not true.

func (Label) HasValue 

func (l Label) HasValue() bool

HasValue returns true if the value is set to any type.

func (Label) Int64 

func (v Label) Int64() int64

Int64 returns the int64 from a value that was set with SetInt64. It will panic for any value for which IsInt64 is not true.

func (Label) Interface 

func (v Label) Interface() interface{}

Interface returns the value. This will never panic, things that were not set using SetInterface will be unpacked and returned anyway.

func (Label) IsBool 

func (v Label) IsBool() bool

IsBool returns true if the value was built with SetBool.

func (Label) IsBytes 

func (v Label) IsBytes() bool

IsBytes returns true if the value was built with BytesOf.

func (Label) IsDuration 

func (v Label) IsDuration() bool

func (Label) IsFloat64 

func (v Label) IsFloat64() bool

IsFloat64 returns true if the value was built with SetFloat64.

func (Label) IsInt64 

func (v Label) IsInt64() bool

IsInt64 returns true if the value was built with SetInt64.

func (Label) IsString 

func (v Label) IsString() bool

IsString returns true if the value was built with StringOf.

func (Label) IsUint64 

func (v Label) IsUint64() bool

IsUint64 returns true if the value was built with SetUint64.

func (Label) String 

func (v Label) String() string

String returns the value as a string. This does not panic if v's Kind is not String, instead, it returns a string representation of the value in all cases.

func (Label) Uint64 

func (v Label) Uint64() uint64

Uint64 returns the uint64 from a value that was set with SetUint64. It will panic for any value for which IsUint64 is not true.

type Metric 

type Metric interface {
	Descriptor() *MetricDescriptor
}

A Metric represents a kind of recorded measurement.

type MetricDescriptor 

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

A MetricDescriptor describes a metric.

func NewMetricDescriptor 

func NewMetricDescriptor(name, description string) *MetricDescriptor

NewMetricDescriptor creates a MetricDescriptor with the given name. The namespace defaults to the import path of the caller of NewMetricDescriptor. Use SetNamespace to provide a different one. Neither the name nor the namespace can be empty.

func (*MetricDescriptor) Description 

func (m *MetricDescriptor) Description() string

func (*MetricDescriptor) Name 

func (m *MetricDescriptor) Name() string

func (*MetricDescriptor) Namespace 

func (m *MetricDescriptor) Namespace() string

func (*MetricDescriptor) SetNamespace 

func (m *MetricDescriptor) SetNamespace(ns string)

SetNamespace sets the namespace of m to a non-empty string.

func (*MetricDescriptor) String 

func (m *MetricDescriptor) String() string

type Source 

type Source struct {
	Space string
	Owner string
	Name  string
}

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.