event

package module
v0.0.0-...-b2144cd Latest Latest
Warning

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

 Go to latest Published: Dec 17, 2024 License: BSD-3-Clause Imports: 12 Imported by: 8

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"
)

Source Files

View all Source files

Directories

Path Synopsis
adapter
gokit
Package gokit provides a go-kit logger for events.
 Package gokit provides a go-kit logger for events.
logfmt
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
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.