event

package module
v0.0.0-...-8a7402a Latest Latest
Warning

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

Go to latest
Published: Jul 19, 2024 License: BSD-3-Clause Imports: 12 Imported by: 10

Documentation

Overview

Package event provides low-cost tracing, metrics and structured logging. These are often grouped under the term "observability".

This package is highly experimental and in a state of flux; it is public only to allow for collaboration on the design and implementation, and may be changed or removed at any time.

It uses a common event system to provide a way for libraries to produce observability information in a way that does not tie the libraries to a specific API or applications to a specific export format.

It is designed for minimal overhead when no exporter is used so that it is safe to leave calls in libraries.

Index

Examples

Constants

View Source
const (
	MetricKey      = interfaceKey("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)
Example
package main

import (
	"context"
	"os"

	"golang.org/x/exp/event"
	"golang.org/x/exp/event/adapter/logfmt"
	"golang.org/x/exp/event/eventtest"
)

func main() {
	ctx := event.WithExporter(context.Background(), event.NewExporter(logfmt.NewHandler(os.Stdout), eventtest.ExporterOptions()))
	event.Log(ctx, "my event", event.Int64("myInt", 6))
	event.Log(ctx, "error event", event.String("myString", "some string value"))
}
Output:

time="2020/03/05 14:27:48" myInt=6 msg="my event"
time="2020/03/05 14:27:49" myString="some string value" msg="error event"

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 information 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 {
	// contains filtered or unexported fields
}

A Counter is a metric that counts something cumulatively.

func NewCounter

func NewCounter(name string, opts *MetricOptions) *Counter

NewCounter creates a counter with the given name.

func (*Counter) Name

func (c *Counter) Name() string

func (*Counter) Options

func (c *Counter) Options() MetricOptions

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 {
	// contains filtered or unexported fields
}

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

func NewDuration

func NewDuration(name string, opts *MetricOptions) *DurationDistribution

NewDuration creates a new Duration with the given name.

func (*DurationDistribution) Name

func (d *DurationDistribution) Name() string

func (*DurationDistribution) Options

func (d *DurationDistribution) Options() MetricOptions

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.

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 {
	// contains filtered or unexported fields
}

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

func NewFloatGauge

func NewFloatGauge(name string, opts *MetricOptions) *FloatGauge

NewFloatGauge creates a new FloatGauge with the given name.

func (*FloatGauge) Name

func (g *FloatGauge) Name() string

func (*FloatGauge) Options

func (g *FloatGauge) Options() MetricOptions

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.

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 {
	// contains filtered or unexported fields
}

An IntDistribution records a distribution of int64s.

func NewIntDistribution

func NewIntDistribution(name string, opts *MetricOptions) *IntDistribution

NewIntDistribution creates a new IntDistribution with the given name.

func (*IntDistribution) Name

func (d *IntDistribution) Name() string

func (*IntDistribution) Options

func (d *IntDistribution) Options() MetricOptions

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.

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 {
	Name() string
	Options() MetricOptions
}

A Metric represents a kind of recorded measurement.

type MetricOptions

type MetricOptions struct {
	// A string that should be common for all metrics of an application or
	// service. Defaults to the import path of the package calling
	// the metric construction function (NewCounter, etc.).
	Namespace string

	// Optional description of the metric.
	Description string

	// Optional unit for the metric. Defaults to UnitDimensionless.
	Unit Unit
}

type Source

type Source struct {
	Space string
	Owner string
	Name  string
}

type Unit

type Unit string

A Unit is a unit of measurement for a metric.

const (
	UnitDimensionless Unit = "1"
	UnitBytes         Unit = "By"
	UnitMilliseconds  Unit = "ms"
)

Directories

Path Synopsis
adapter
gokit
Package gokit provides a go-kit logger for events.
Package gokit provides a go-kit logger for events.
logr
Package logr is a logr implementation that uses events.
Package logr is a logr implementation that uses events.
logrus
Package logrus provides a logrus Formatter for events.
Package logrus provides a logrus Formatter for events.
zap
zap provides an implementation of zapcore.Core for events.
zap provides an implementation of zapcore.Core for events.
Package eventtest supports logging events to a test.
Package eventtest supports logging events to a test.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL