Documentation
¶
Overview ¶
Package timeline provides ID-based recording and queries for operation timelines. Manager owns recording and persistence; callers own business results and exports.
Example ¶
package main
import (
"context"
"fmt"
"github.com/compforge/go-stdx/timeline"
)
func main() {
m, err := timeline.NewManager(nil, timeline.Config{})
if err != nil {
panic(err)
}
previous := timeline.SetDefault(m)
defer timeline.SetDefault(previous)
defer m.Shutdown(context.Background())
// Stage recording needs neither Start nor Finish nor persistent storage.
if _, err := timeline.Begin("task-42", "prepare_files"); err != nil {
panic(err)
}
if err := timeline.End("task-42", "prepare_files", nil); err != nil {
panic(err)
}
snapshot, err := timeline.Read(context.Background(), "task-42", false)
if err != nil {
panic(err)
}
fmt.Println(snapshot.Status, snapshot.Stages[0].Status)
}
Output: unknown succeeded
Index ¶
- Constants
- Variables
- func AttributeValue[T any](attributes map[string]json.RawMessage, key string) (T, bool)
- func End(id, name string, err error, options ...EndOption) error
- func Finish(id string, err error) error
- func NewContext(ctx context.Context, t Timeline) context.Context
- func NewStageContext(ctx context.Context, ref StageRef) context.Context
- func Record(id string, stage Stage) error
- func Start(id, operation string, attributes ...Attribute) error
- type Actor
- type Attribute
- type Collection
- type Config
- type EndOption
- type Factory
- type Handle
- type Manager
- type Option
- type Registry
- type Snapshot
- type Stage
- type StageHandle
- type StageID
- type StageOption
- type StageRef
- type Stats
- type Status
- type Timeline
Examples ¶
Constants ¶
Variables ¶
var ErrActiveStages = manager.ErrActiveStages
var ErrAlreadyExists = errors.New("timeline: ID is already registered")
var ErrAmbiguousStage = manager.ErrAmbiguousStage
var ErrBufferFull = manager.ErrBufferFull
var ErrClosed = manager.ErrClosed
var ErrEmptyID = model.ErrEmptyID
var ErrInvalidAttribute = model.ErrInvalidAttribute
var ErrInvalidStage = model.ErrInvalidStage
var ErrNoDefault = manager.ErrNoDefault
var ErrNotStarted = manager.ErrNotStarted
var ErrStageNotFound = manager.ErrStageNotFound
Functions ¶
func AttributeValue ¶
AttributeValue decodes the most recent value for key using encoding/json. It returns false for a missing key or a JSON value incompatible with T.
func NewContext ¶
NewContext optionally carries t without changing ctx's lifetime.
Types ¶
type Attribute ¶
Attribute is recording input. Values must be JSON serializable and must not be mutated during the recording call.
type Collection ¶
type Collection = model.Collection
Collection reports local flush and store read success, not global completeness.
type EndOption ¶
EndOption supplies a source end time, final attributes or a code.
func WithCode ¶
WithCode records a caller-defined code independently of the stage result. An empty code is omitted from JSON.
func WithEndActor ¶ added in v0.3.0
func WithEndAttributes ¶
func WithEndTime ¶
type Factory ¶
type Factory func(ctx context.Context, id, operation string, attributes ...Attribute) (Timeline, error)
Factory creates a fresh Timeline with the supplied ID. It must not publish the instance elsewhere: the Registry owns registration and completion cleanup. On error it must release any resources it allocated.
type Handle ¶ added in v0.3.0
Handle groups the optional object-style API for one recording identity. The primary business API is Begin/End/Record/Read with optional Start/Finish.
func New ¶
New creates a standalone handle. Without WithStore, its cache is the only document owner and NoopStore accepts checkpoints without retaining data.
Example ¶
package main
import (
"context"
"fmt"
"github.com/compforge/go-stdx/timeline"
timelinestore "github.com/compforge/go-stdx/timeline/store"
)
func main() {
ctx := context.Background()
// A persistent Store can connect these handles across process boundaries.
store := timelinestore.NewMemoryStore()
owner, _ := timeline.New("sandbox-42", timeline.WithActor(timeline.Actor{Name: "test"}), timeline.WithStore(store))
if err := owner.Start(ctx, "sandbox_start"); err != nil {
panic(err)
}
worker, _ := timeline.New("sandbox-42", timeline.WithActor(timeline.Actor{Name: "test"}), timeline.WithStore(store),
timeline.WithActor(timeline.Actor{Name: "scheduler-pod"}))
_, stage := timeline.BeginWithContext(ctx, worker, "acquire_carrier")
stage.End(nil)
if err := worker.Flush(ctx); err != nil {
panic(err)
}
snapshot, err := owner.Finish(ctx, nil)
if err != nil {
panic(err)
}
fmt.Println(snapshot.ID, snapshot.Operation, snapshot.Status)
fmt.Println(snapshot.Stages[0].Name, snapshot.Stages[0].Actor.Name)
}
Output: sandbox-42 sandbox_start succeeded acquire_carrier scheduler-pod
type Manager ¶ added in v0.3.0
Manager coordinates recording and background persistence for multiple IDs.
func NewManager ¶ added in v0.3.0
NewManager starts a Manager. A nil backend selects NoopStore for cache-only recording.
func SetDefault ¶ added in v0.3.0
SetDefault installs the process Manager and returns the previous one. Install before producers start; replacement neither moves state nor shuts down either instance. Tests changing the default must run serially and restore it.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry indexes active timelines within one process. Share an instance across components; business code owns ID generation, propagation and completion. Construct it with NewRegistry. It must not be copied after first use.
Example ¶
package main
import (
"context"
"fmt"
"github.com/compforge/go-stdx/timeline"
gospantimeline "github.com/compforge/go-stdx/timeline/gospan"
)
func main() {
registry := timeline.NewRegistry(gospantimeline.New)
ctx := context.Background()
tl, err := registry.Create(ctx, "start-42", "sandbox_start")
if err != nil {
panic(err)
}
// Pass Timeline directly along a call chain.
prepare := func(ctx context.Context, tl timeline.Timeline) {
_, stage := timeline.BeginWithContext(ctx, tl, "prepare", timeline.WithStageActor(timeline.Actor{Name: "test"}))
stage.End(nil)
}
prepare(ctx, tl)
// An independent component needs only the shared registry and operation ID.
joined, ok := registry.Lookup("start-42")
if !ok {
panic("operation missing")
}
_, stage := timeline.BeginWithContext(ctx, joined, "provision", timeline.WithStageActor(timeline.Actor{Name: "test"}))
stage.End(nil)
// Context propagation is an optional caller choice.
bound, _ := timeline.FromContext(timeline.NewContext(ctx, tl))
fmt.Println(joined == tl, bound == tl)
result, err := tl.Finish(ctx, nil)
if err != nil {
panic(err)
}
_, active := registry.Lookup(tl.ID())
fmt.Println(result.ID, len(result.Stages), active)
}
Output: true true start-42 2 false
func NewRegistry ¶
NewRegistry uses factory to create timelines without binding them to context. The factory must be non-nil. A Registry does not store completed history or automatically finish operations when a request's context is canceled.
func (*Registry) Create ¶
func (r *Registry) Create(ctx context.Context, id, operation string, attributes ...Attribute) (Timeline, error)
Create reserves a non-empty ID and creates an operation. Concurrent creates for the same ID return ErrAlreadyExists, including while its factory is running. A failed creation releases the ID. The caller owns Finish on the returned Timeline; independent components should only end their own stages.
func (*Registry) Lookup ¶
Lookup returns the instance published by Create. It returns false while the factory is running and after Finish has returned without ErrActiveStages. It never creates an operation. A concurrent Finish may seal a returned instance before its next Begin; recording then follows Timeline's inert rules.
type Snapshot ¶
Snapshot is a detached, JSON-serializable view with read-time collection status. Duration, RunningStages, LatestFailedStage and Summary query its recorded facts.
type StageHandle ¶
type StageHandle = manager.StageHandle
StageHandle identifies a stage and supports ending it or updating its attributes.
func Begin ¶ added in v0.3.0
func Begin(id, name string, options ...StageOption) (StageHandle, error)
func BeginWithContext ¶
func BeginWithContext(ctx context.Context, t Timeline, name string, opts ...StageOption) (context.Context, StageHandle)
BeginWithContext preserves cancellation and binds the new stage identity. Only WithParent sets parentage; context binding never supplies a parent.
type StageOption ¶
type StageOption = manager.StageOption
StageOption sets the identity, source start time or initial attributes of a stage. Implementations apply options synchronously before returning a handle.
func WithAttributes ¶
func WithAttributes(attributes ...Attribute) StageOption
func WithParent ¶
func WithParent(id StageID) StageOption
WithParent records an association without looking up or requiring the parent. The ID is preserved even when the parent is absent or arrives later.
func WithStageActor ¶
func WithStageActor(actor Actor) StageOption
func WithStageID ¶
func WithStageID(id StageID) StageOption
func WithStartTime ¶
func WithStartTime(at time.Time) StageOption
type Timeline ¶
Timeline is the optional object-style recording contract for one operation.
func FromContext ¶
FromContext retrieves a Timeline explicitly attached with NewContext.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package gospantimeline implements timeline.Timeline with gospan spans and an in-memory projection.
|
Package gospantimeline implements timeline.Timeline with gospan spans and an in-memory projection. |
|
Package manager owns timeline recording, cache coordination and persistence lifecycles.
|
Package manager owns timeline recording, cache coordination and persistence lifecycles. |
|
Package model holds values shared by recording and storage, without either lifecycle.
|
Package model holds values shared by recording and storage, without either lifecycle. |
|
Package store defines the timeline persistence protocol and its in-memory implementation.
|
Package store defines the timeline persistence protocol and its in-memory implementation. |
|
sqlstore
Package sqlstore persists one document per timeline using an application-owned database/sql pool.
|
Package sqlstore persists one document per timeline using an application-owned database/sql pool. |