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, metadata *SpanMetadata, input I, ...) (O, error)
• func SpanPath(ctx context.Context) string
• func Tracer() trace.Tracer
• func TracerProvider() *sdktrace.TracerProvider
• func WriteTelemetryBatch(client TelemetryClient) (shutdown func(context.Context) error)
• func WriteTelemetryImmediate(client TelemetryClient)
• type Annotation
• type BoolValue
• type Data
• type InstrumentationScope
• type Link
• type Milliseconds
  • func ToMilliseconds(t time.Time) Milliseconds
  • func (m Milliseconds) Time() time.Time
• type SpanContext
• type SpanData
• type SpanMetadata
• 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,
	metadata *SpanMetadata,
	input I,
	f func(context.Context, I) (O, error),
) (O, error)

RunInNewSpan runs f on input in a new span with the provided metadata. The metadata contains all span configuration including name, type, labels, etc.

func SpanPath

func SpanPath(ctx context.Context) string

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

func Tracer

func Tracer() trace.Tracer

Tracer returns a tracer from the global tracer provider.

func TracerProvider

func TracerProvider() *sdktrace.TracerProvider

TracerProvider returns the global tracer provider, creating it if needed.

func WriteTelemetryBatch

func WriteTelemetryBatch(client TelemetryClient) (shutdown func(context.Context) error)

WriteTelemetryBatch adds a telemetry server to the global tracer provider. 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 WriteTelemetryImmediate

func WriteTelemetryImmediate(client TelemetryClient)

WriteTelemetryImmediate adds a telemetry server to the global tracer provider. Traces are saved immediately as they are finished. Use this for a gtrace.Store with a fast Save method, such as one that writes to a file.

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

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 InstrumentationScope

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

InstrumentationScope 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:"context"`
	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"`
	DisplayName          string               `json:"displayName"`
	Links                []*Link              `json:"links,omitempty"`
	InstrumentationScope InstrumentationScope `json:"instrumentationLibrary"` // TODO: update json tag when JS runtime gets updated
	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"`
}

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 SpanMetadata

type SpanMetadata struct {
	// Name is the span name
	Name string
	// IsRoot indicates if this is a root span
	IsRoot bool
	// Type represents the kind of span (e.g., "action", "flowStep")
	Type string
	// Subtype provides more specific categorization (e.g., "tool", "flow", "model")
	Subtype string
	// TelemetryLabels are arbitrary key-value pairs set directly as span attributes
	TelemetryLabels map[string]string
	// Metadata are genkit-specific metadata with automatic "genkit:metadata:" prefix
	Metadata map[string]string
}

SpanMetadata contains metadata information for creating properly annotated spans

type Status

type Status struct {
	Code        uint32 `json:"code"` // avoid the MarshalJSON method on codes.Code
	Description string `json:"message,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"`
}

type TimeEvents

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