tracing

Documentation

Overview

Package gtime provides time functionality for Go Genkit.

The tracing package provides support for execution traces.

Index

• Variables
• func RunInNewSpan[I, O any](ctx context.Context, tstate *State, name, spanType string, isRoot bool, ...) (O, error)
• func SetCustomMetadataAttr(ctx context.Context, key, value string)
• func SpanPath(ctx context.Context) string
• type Annotation
• type BoolValue
• type Data
• type FileStore
  • func NewFileStore(dir string) (*FileStore, error)
  • func (s *FileStore) List(ctx context.Context, q *Query) ([]*Data, string, error)
  • func (s *FileStore) Load(ctx context.Context, id string) (*Data, error)
  • func (s *FileStore) LoadAny(id string, p any) error
  • func (s *FileStore) Save(ctx context.Context, id string, td *Data) error
• type InstrumentationLibrary
• type Link
• type Milliseconds
  • func ToMilliseconds(t time.Time) Milliseconds
  • func (m Milliseconds) Time() time.Time
• type Query
• type SpanContext
• type SpanData
• type State
  • func NewState() *State
  • func (ts *State) AddTraceStoreBatch(tstore Store) (shutdown func(context.Context) error)
  • func (ts *State) AddTraceStoreImmediate(tstore Store)
  • func (ts *State) RegisterSpanProcessor(sp sdktrace.SpanProcessor)
• type Status
• type Store
• type TimeEvent
• type TimeEvents

Variables

var ErrBadQuery = errors.New("bad trace.Query")

Functions

func RunInNewSpan

func RunInNewSpan[I, O any](
	ctx context.Context,
	tstate *State,
	name, spanType string,
	isRoot bool,
	input I,
	f func(context.Context, I) (O, error),
) (O, error)

RunInNewSpan runs f on input in a new span with the given name. The attrs map provides the span's initial attributes.

func SetCustomMetadataAttr

func SetCustomMetadataAttr(ctx context.Context, key, value string)

SetCustomMetadataAttr records a key in the current span metadata.

func SpanPath

func SpanPath(ctx context.Context) string

SpanPath returns the path as recroding in the current span metadata.

Types

type Annotation

type Annotation struct {
	Attributes  map[string]any `json:"attributes,omitempty"`
	Description string         `json:"description,omitempty"`
}

type BoolValue

type BoolValue struct {
	Value bool `json:"value,omitempty"`
}

type Data

type Data struct {
	TraceID     string               `json:"traceId"`
	DisplayName string               `json:"displayName"`
	StartTime   Milliseconds         `json:"startTime"`
	EndTime     Milliseconds         `json:"endTime"`
	Spans       map[string]*SpanData `json:"spans"`
}

Data is information about a trace.

type FileStore

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

A FileStore is a Store that writes traces to files.

func NewFileStore

func NewFileStore(dir string) (*FileStore, error)

NewFileStore creates a FileStore that writes traces to the given directory. The directory is created if it does not exist.

func (*FileStore) List

func (s *FileStore) List(ctx context.Context, q *Query) ([]*Data, string, error)

List implements [Store.List]. The traces are returned in the order they were written, newest first. The default limit is 10.

func (*FileStore) Load

func (s *FileStore) Load(ctx context.Context, id string) (*Data, error)

Load implements [Store.Load].

func (*FileStore) LoadAny

func (s *FileStore) LoadAny(id string, p any) error

func (*FileStore) Save

func (s *FileStore) Save(ctx context.Context, id string, td *Data) error

Save implements [Store.Save]. It is not safe to call Save concurrently with the same ID.

type InstrumentationLibrary

type InstrumentationLibrary struct {
	Name      string `json:"name"`
	Version   string `json:"version"`
	SchemaURL string `json:"schemaUrl,omitempty"`
}

InstrumentationLibrary is a copy of go.opentelemetry.io/otel/sdk/instrumentation.Library, with added struct tags to match the javascript JSON field names.

type Link

type Link struct {
	SpanContext            SpanContext    `json:"spanContext,omitempty"`
	Attributes             map[string]any `json:"attributes,omitempty"`
	DroppedAttributesCount int            `json:"droppedAttributesCount"`
}

A Link describes the relationship between two Spans.

type Milliseconds

type Milliseconds float64

Milliseconds represents a time as the number of milliseconds since the Unix epoch.

func ToMilliseconds

func ToMilliseconds(t time.Time) Milliseconds

ToMilliseconds converts a time.Time to a Milliseconds.

func (Milliseconds) Time

func (m Milliseconds) Time() time.Time

Time converts a Milliseconds to a time.Time.

type Query

type Query struct {
	// Maximum number of traces to return. If zero, a default value may be used.
	// Callers should not assume they will get the entire list; they should always
	// check the returned continuation token.
	Limit int
	// Where to continue the listing from. Must be either empty to start from the
	// beginning, or the result of a recent, previous call to List.
	ContinuationToken string
}

A Query filters the result of [Store.List].

type SpanContext

type SpanContext struct {
	TraceID    string `json:"traceId,omitempty"`
	SpanID     string `json:"spanId"`
	IsRemote   bool   `json:"isRemote"`
	TraceFlags int    `json:"traceFlags"`
}

A SpanContext contains identifying trace information about a Span.

type SpanData

type SpanData struct {
	SpanID                 string                 `json:"spanId"`
	TraceID                string                 `json:"traceId,omitempty"`
	ParentSpanID           string                 `json:"parentSpanId,omitempty"`
	StartTime              Milliseconds           `json:"startTime"`
	EndTime                Milliseconds           `json:"endTime"`
	Attributes             map[string]any         `json:"attributes,omitempty"`
	DisplayName            string                 `json:"displayName"`
	Links                  []*Link                `json:"links,omitempty"`
	InstrumentationLibrary InstrumentationLibrary `json:"instrumentationLibrary,omitempty"`
	SpanKind               string                 `json:"spanKind"` // trace.SpanKind as a string
	// This bool is in a separate struct, to match the js (and presumably the OTel) formats.
	SameProcessAsParentSpan BoolValue  `json:"sameProcessAsParentSpan"`
	Status                  Status     `json:"status"`
	TimeEvents              TimeEvents `json:"timeEvents,omitempty"`
}

SpanData is information about a trace span. Most of this information comes from OpenTelemetry. See https://pkg.go.dev/go.opentelemetry.io/otel/sdk/trace#ReadOnlySpan. SpanData can be passed to json.Marshal, whereas most of the OpenTelemetry types make no claims about JSON serializability.

type State

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

State holds OpenTelemetry values for creating traces.

func NewState

func NewState() *State

func (*State) AddTraceStoreBatch

func (ts *State) AddTraceStoreBatch(tstore Store) (shutdown func(context.Context) error)

AddTraceStoreBatch adds ts to the tracingState. Traces are batched before being sent for processing. Use this for a gtrace.Store with a potentially expensive Save method, such as one that makes an RPC. Callers must invoke the returned function at the end of the program to flush the final batch and perform other cleanup.

func (*State) AddTraceStoreImmediate

func (ts *State) AddTraceStoreImmediate(tstore Store)

AddTraceStoreImmediate adds tstore to the tracingState. Traces are saved immediately as they are finshed. Use this for a gtrace.Store with a fast Save method, such as one that writes to a file.

func (*State) RegisterSpanProcessor

func (ts *State) RegisterSpanProcessor(sp sdktrace.SpanProcessor)

type Status

type Status struct {
	Code        uint32 `json:"code"` // avoid the MarshalJSON method on codes.Code
	Description string `json:"description,omitempty"`
}

Status is a copy of go.opentelemetry.io/otel/sdk/trace.Status, with added struct tags to match the javascript JSON field names.

type Store

type Store interface {
	// Save saves the Data to the store. If a Data with the id already exists,
	// the two are merged.
	Save(ctx context.Context, id string, td *Data) error
	// Load reads the Data with the given ID from the store.
	// It returns an error that is fs.ErrNotExist if there isn't one.
	Load(ctx context.Context, id string) (*Data, error)
	// List returns all the Datas in the store that satisfy q, in some deterministic
	// order.
	// It also returns a continuation token: an opaque string that can be passed
	// to the next call to List to resume the listing from where it left off. If
	// the listing reached the end, this is the empty string.
	// If the Query is malformed, List returns an error that is errBadQuery.
	List(ctx context.Context, q *Query) (tds []*Data, contToken string, err error)

	// LoadAny is like Load, but accepts a pointer to any type.
	// It is for testing (see conformance_test.go).
	// TODO: replace Load with this.
	LoadAny(id string, p any) error
}

A Store stores trace information. Every trace has a unique ID.

type TimeEvent

type TimeEvent struct {
	Time       Milliseconds `json:"time,omitempty"`
	Annotation Annotation   `json:"annotation,omitempty"`
}

type TimeEvents

type TimeEvents struct {
	TimeEvent []TimeEvent `json:"timeEvent,omitempty"`
}