eventkit

README

eventkit

Fire-and-forget event telemetry for Go CLIs. Buffers events in-process, spills to a durable disk queue, and ships them out-of-band via a detached flusher subprocess so the user-facing command never blocks on the network.

Event → Collector → FileEmitter → .evtq on disk → FileFlusher → transport (GA4)

Install

go get github.com/dolthub/eventkit

Requires Go 1.26+.

Usage

See examples/mycli for the worked pattern: construct a FileEmitter, wrap it in a Collector, emit events with NewEvent + AddMetric + CloseEventAndAdd, then on exit spawn a detached subcommand that runs FileFlusher.Flush against transport/ga4.

Durability

Each batch is a single .evtq file named by the first 22 chars of base64-URL MD5 of its contents (corruption check). A cross-process eventkit.lock ensures only one flusher runs at a time. If Send returns an error, the file stays on disk for the next run; on success it is deleted.

Transports

• transport/ga4 — ships via the GA4 Measurement Protocol over plain HTTP.
• Roll your own by implementing Emitter.

Documentation

Index

• Constants
• Variables
• func CheckFilenameMD5(data []byte, path, ext string) bool
• func Filename(data []byte, ext string) string
• func MachineID(appName string) string
• func NewContextForEvent(ctx context.Context, evt *Event) context.Context
• func SetGlobal(c *Collector)
• type Attribute
• type Codec
• type Collector
  • func Global() *Collector
  • func NewCollector(emitter Emitter, opts ...CollectorOption) *Collector
  • func (c *Collector) Close(ctx context.Context) error
  • func (c *Collector) CloseEventAndAdd(evt *Event)
• type CollectorOption
  • func WithAppName(name string) CollectorOption
  • func WithAppVersion(version string) CollectorOption
  • func WithBackoff(initial, max time.Duration) CollectorOption
  • func WithDisabled(f func() bool) CollectorOption
  • func WithDistinctID(id string) CollectorOption
  • func WithMaxBatch(n int) CollectorOption
  • func WithPlatform(platform string) CollectorOption
• type Counter
  • func NewCounter(key string) *Counter
  • func (c *Counter) Add(n int64)
  • func (c *Counter) Dec()
  • func (c *Counter) Inc()
  • func (c *Counter) Serialize() Metric
• type Emitter
• type Event
  • func GetEventFromContext(ctx context.Context) *Event
  • func NewEvent(name string) *Event
  • func (e *Event) AddMetric(m EventMetric)
  • func (e *Event) SetAttribute(key, value string)
• type EventMetric
• type EventRecord
• type FileEmitter
  • func NewFileEmitter(dir string, opts ...FileEmitterOption) (*FileEmitter, error)
  • func (f *FileEmitter) Send(_ context.Context, req *LogEventsRequest) error
• type FileEmitterOption
  • func WithFileCodec(c Codec) FileEmitterOption
  • func WithFileExtension(ext string) FileEmitterOption
• type FileFlusher
  • func NewFileFlusher(dir string, target Emitter, opts ...FileFlusherOption) *FileFlusher
  • func (f *FileFlusher) Flush(ctx context.Context) error
• type FileFlusherOption
  • func WithFlusherFileCodec(c Codec) FileFlusherOption
  • func WithFlusherFileExtension(ext string) FileFlusherOption
  • func WithFlusherLockFilename(name string) FileFlusherOption
• type JSONCodec
  • func (JSONCodec) Marshal(req *LogEventsRequest) ([]byte, error)
  • func (JSONCodec) Unmarshal(data []byte, req *LogEventsRequest) error
• type LogEventsRequest
• type Metric
• type NullEmitter
  • func (NullEmitter) Send(context.Context, *LogEventsRequest) error
• type Timer
  • func NewTimer(key string) *Timer
  • func (t *Timer) Serialize() Metric
  • func (t *Timer) Stop() *Timer

Constants

const DefaultFileExt = ".evtq"

const DefaultLockFilename = "eventkit.lock"

Variables

var NowFunc = time.Now

Functions

func CheckFilenameMD5

func CheckFilenameMD5(data []byte, path, ext string) bool

func Filename

func Filename(data []byte, ext string) string

func MachineID

func MachineID(appName string) string

func NewContextForEvent

func NewContextForEvent(ctx context.Context, evt *Event) context.Context

func SetGlobal

func SetGlobal(c *Collector)

Types

type Attribute

type Attribute struct {
	Key   string `json:"key"`
	Value string `json:"value"`
}

type Codec

type Codec interface {
	Marshal(*LogEventsRequest) ([]byte, error)
	Unmarshal([]byte, *LogEventsRequest) error
}

var DefaultCodec Codec = JSONCodec{}

type Collector

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

func Global

func Global() *Collector

func NewCollector

func NewCollector(emitter Emitter, opts ...CollectorOption) *Collector

func (*Collector) Close

func (c *Collector) Close(ctx context.Context) error

func (*Collector) CloseEventAndAdd

func (c *Collector) CloseEventAndAdd(evt *Event)

type CollectorOption

type CollectorOption func(*collectorConfig)

func WithAppName

func WithAppName(name string) CollectorOption

func WithAppVersion

func WithAppVersion(version string) CollectorOption

func WithBackoff

func WithBackoff(initial, max time.Duration) CollectorOption

func WithDisabled

func WithDisabled(f func() bool) CollectorOption

func WithDistinctID

func WithDistinctID(id string) CollectorOption

func WithMaxBatch

func WithMaxBatch(n int) CollectorOption

func WithPlatform

func WithPlatform(platform string) CollectorOption

type Counter

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

func NewCounter

func NewCounter(key string) *Counter

func (*Counter) Add

func (c *Counter) Add(n int64)

func (*Counter) Dec

func (c *Counter) Dec()

func (*Counter) Inc

func (c *Counter) Inc()

func (*Counter) Serialize

func (c *Counter) Serialize() Metric

type Emitter

type Emitter interface {
	Send(ctx context.Context, req *LogEventsRequest) error
}

type Event

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

func GetEventFromContext

func GetEventFromContext(ctx context.Context) *Event

func NewEvent

func NewEvent(name string) *Event

func (*Event) AddMetric

func (e *Event) AddMetric(m EventMetric)

func (*Event) SetAttribute

func (e *Event) SetAttribute(key, value string)

type EventMetric

type EventMetric interface {
	Serialize() Metric
}

type EventRecord

type EventRecord struct {
	ID         string      `json:"id"`
	Name       string      `json:"name"`
	StartTime  time.Time   `json:"start_time"`
	EndTime    time.Time   `json:"end_time"`
	Attributes []Attribute `json:"attributes,omitempty"`
	Metrics    []Metric    `json:"metrics,omitempty"`
}

type FileEmitter

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

func NewFileEmitter

func NewFileEmitter(dir string, opts ...FileEmitterOption) (*FileEmitter, error)

func (*FileEmitter) Send

func (f *FileEmitter) Send(_ context.Context, req *LogEventsRequest) error

type FileEmitterOption

type FileEmitterOption func(*FileEmitter)

func WithFileCodec

func WithFileCodec(c Codec) FileEmitterOption

func WithFileExtension

func WithFileExtension(ext string) FileEmitterOption

type FileFlusher

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

func NewFileFlusher

func NewFileFlusher(dir string, target Emitter, opts ...FileFlusherOption) *FileFlusher

func (*FileFlusher) Flush

func (f *FileFlusher) Flush(ctx context.Context) error

type FileFlusherOption

type FileFlusherOption func(*FileFlusher)

func WithFlusherFileCodec

func WithFlusherFileCodec(c Codec) FileFlusherOption

func WithFlusherFileExtension

func WithFlusherFileExtension(ext string) FileFlusherOption

func WithFlusherLockFilename

func WithFlusherLockFilename(name string) FileFlusherOption

type JSONCodec

type JSONCodec struct{}

func (JSONCodec) Marshal

func (JSONCodec) Marshal(req *LogEventsRequest) ([]byte, error)

func (JSONCodec) Unmarshal

func (JSONCodec) Unmarshal(data []byte, req *LogEventsRequest) error

type LogEventsRequest

type LogEventsRequest struct {
	DistinctID string        `json:"distinct_id"`
	AppName    string        `json:"app_name"`
	AppVersion string        `json:"app_version"`
	Platform   string        `json:"platform"`
	Events     []EventRecord `json:"events"`
}

type Metric

type Metric struct {
	Key      string         `json:"key"`
	Count    *int64         `json:"count,omitempty"`
	Duration *time.Duration `json:"duration_ns,omitempty"`
}

type NullEmitter

type NullEmitter struct{}

func (NullEmitter) Send

func (NullEmitter) Send(context.Context, *LogEventsRequest) error

type Timer

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

func NewTimer

func NewTimer(key string) *Timer

func (*Timer) Serialize

func (t *Timer) Serialize() Metric

func (*Timer) Stop

func (t *Timer) Stop() *Timer