history

package
v2.7.3 Latest Latest
Warning

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

Go to latest
Published: Jun 26, 2026 License: MIT Imports: 21 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source
var ErrChannelFull = errors.New("channel is full")
View Source
var ErrNoTable = errors.New("no trace table configured")

Functions

func CreateTable

func CreateTable(ctx ql.TxContext, name string) error

CreateTable creates the history table with the given name together with the indexes used by Records and Cleanup, unless they already exist.

Types

type AthenaQuery

type AthenaQuery struct {
	GroupId GroupId

	// required athena configuration
	Database       string
	Table          string
	WorkGroup      string
	OutputLocation *url.URL

	// Optional region
	Region string

	// optional values to reduce the amount of data that
	// the query needs to scan. Either value can be left empty to
	MinTimestamp *time.Time
	MaxTimestamp *time.Time
}

func (AthenaQuery) Records

func (q AthenaQuery) Records(ctx context.Context) ([]Record, error)

type Cleanup

type Cleanup struct {
	Interval time.Duration
	Jitter   time.Duration
	MaxAge   time.Duration
}

func (Cleanup) Run

func (c Cleanup) Run(ctx context.Context, service *Service)

Run executes cleanup on the given service in a loop waiting for Cleanup.Interval + rand(Cleanup.Jitter) before each Service.Cleanup. It will delete all items that are older than Cleanup.MaxAge.

type EventCreator

type EventCreator func(serviceId, serviceVersion string, rec RecordToSend) events.Event

EventCreator builds the event that is sent out for a tracked record. It receives the ServiceId and ServiceVersion from the EventSending config.

type EventSender

type EventSender = events.EventSender

EventSender is re-exported from the events package for convenience.

type EventSending

type EventSending struct {
	// EventSender sends the events created by EventCreator.
	EventSender EventSender
	// EventCreator builds the event that is sent for a tracked record.
	EventCreator EventCreator

	// ServiceId and ServiceVersion identify the sender of the events. If left
	// empty, they are loaded from the SERVICE_ID and SERVICE_VERSION environment
	// variables in New.
	ServiceId      string
	ServiceVersion string

	// Write events to the kafka outbox first. If false, events are sent async.
	WriteToOutbox bool
}

EventSending groups options required for sending events to an EventSender.

type GroupId

type GroupId string

GroupId groups multiple history.Record instances into one history trace.

func (GroupId) LogValue

func (g GroupId) LogValue() slog.Value

func (GroupId) String

func (g GroupId) String() string

type Item

type Item interface {
	// HistoryString returns a human-readable description of this trace.Item.
	HistoryString() string
}

Item must be implemented by every event that is to be traced. Every Item should be json serializable.

type Record

type Record struct {
	Timestamp      time.Time       `db:"timestamp"`
	RequestTraceId RequestTraceId  `db:"request_trace_id"`
	Step           string          `db:"step"`
	Description    string          `db:"description"`
	Payload        json.RawMessage `db:"payload"`

	// Optional field that might indicate the sender of an event. This is useful if the
	// event comes from an external source, e.g. athena.
	// For local data, it is set to either the serviceId or to `local`, if no serviceId
	// is specified.
	EventSender        string `db:"-"`
	EventSenderVersion string `db:"-"`
}

Record describes one tracing record.

type RecordToSend

type RecordToSend struct {
	GroupId        GroupId
	Timestamp      time.Time
	Step           string
	Description    string
	Payload        json.RawMessage
	RequestTraceId RequestTraceId
}

RecordToSend is a single tracked record, ready to be written to the history table and/or converted into an event.

type RequestTraceId

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

func (RequestTraceId) IsValid

func (h RequestTraceId) IsValid() bool

func (*RequestTraceId) Scan

func (h *RequestTraceId) Scan(src any) error

func (RequestTraceId) String

func (h RequestTraceId) String() string

func (RequestTraceId) Value

func (h RequestTraceId) Value() (driver.Value, error)

type Service

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

Service traces events by writing them to a history table and/or sending them out as events. Create an instance with New.

func New

func New(txStarter ql.TxStarter, table pgx.Identifier, eventSending *EventSending) *Service

New creates a new history.Service instance to trace events. By default the service writes records to the history table given by table.

If you specify the optional eventSending parameter, every tracked record is also turned into an event. With EventSending.WriteToOutbox the event is written to the kafka outbox as part of the same transaction (via EventSender.SendInTx); otherwise it is sent asynchronously once the transaction commits (via EventSender.SendAsync).

If Service.SendAsync was called prior, trace events that are not tracked within a transaction are put into a channel (without blocking) and are sent later.

You can specify parameter table as nil to not write to the history table. If you specify an EventSending config, history entries are then only sent out as events.

func (*Service) Cleanup

func (h *Service) Cleanup(ctx context.Context, txStarter ql.TxStarter, before time.Time) error

Cleanup deletes all events that happened before the given timestamp.

func (*Service) Records

func (h *Service) Records(ctx ql.TxContext, groupId GroupId) ([]Record, error)

Records returns all local events for the given groupId. This method does not guarantee any ordering between the records returned.

func (*Service) SendAsync

func (h *Service) SendAsync(ctx context.Context)

SendAsync starts the async process. This will start a background task to send out records that are not traced within a transaction. You can stop the background task by canceling the Context ctx.

func (*Service) Track

func (h *Service) Track(ctx context.Context, groupId GroupId, item Item)

Track records the given item under groupId. Depending on the Service configuration the record is written to the history table and/or sent out as an event. Tracking never returns an error: any failure is only logged.

If the context carries a transaction, the record is written within it. Otherwise a new transaction is opened, unless async sending was enabled via Service.SendAsync, in which case the record is queued without blocking.

Jump to

Keyboard shortcuts

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