tracing

Documentation

Overview

Package gtime provides time functionality for Go Genkit.

The tracing package provides support for execution traces.

Index

• func NewHTTPTelemetryClient(url string) *httpTelemetryClient
• 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 InstrumentationLibrary
• type Link
• type Milliseconds
  • func ToMilliseconds(t time.Time) Milliseconds
  • func (m Milliseconds) Time() time.Time
• type SpanContext
• type SpanData
• type State
  • func NewState() *State
  • func (ts *State) RegisterSpanProcessor(sp sdktrace.SpanProcessor)
  • func (ts *State) WriteTelemetryBatch(client TelemetryClient) (shutdown func(context.Context) error)
  • func (ts *State) WriteTelemetryImmediate(client TelemetryClient)
• type Status
• type TelemetryClient
• type TestOnlyTelemetryClient
  • func NewTestOnlyTelemetryClient() *TestOnlyTelemetryClient
  • func (c *TestOnlyTelemetryClient) Save(ctx context.Context, trace *Data) error
• type TimeEvent
• type TimeEvents

Functions

func NewHTTPTelemetryClient

func NewHTTPTelemetryClient(url string) *httpTelemetryClient

NewHTTPTelemetryClient creates a new telemetry client that sends traces to a telemetry server at the given URL.

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

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

func (*State) WriteTelemetryBatch

func (ts *State) WriteTelemetryBatch(client TelemetryClient) (shutdown func(context.Context) error)

WriteTelemetryBatch adds a telemetry server 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) WriteTelemetryImmediate

func (ts *State) WriteTelemetryImmediate(client TelemetryClient)

WriteTelemetryImmediate adds a telemetry server 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.

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 TelemetryClient

type TelemetryClient interface {
	Save(ctx context.Context, trace *Data) error
}

type TestOnlyTelemetryClient

type TestOnlyTelemetryClient struct {
	Traces map[string]*Data
}

TestOnlyTelemetryClient is a test-only implementation of TelemetryClient that stores traces in memory.

func NewTestOnlyTelemetryClient

func NewTestOnlyTelemetryClient() *TestOnlyTelemetryClient

NewTestOnlyTelemetryClient creates a new in-memory telemetry client for testing.

func (*TestOnlyTelemetryClient) Save

func (c *TestOnlyTelemetryClient) Save(ctx context.Context, trace *Data) error

Save saves the data to an in-memory store.

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"`
}