tracer

Documentation

Index

• type Collector
  • func NewCollector(socketPath string) *Collector
  • func (c *Collector) Listen(ctx context.Context) error
  • func (c *Collector) OnSpanComplete(fn func(traceID string, span Span))
  • func (c *Collector) Serve(ctx context.Context) error
  • func (c *Collector) SocketPath() string
  • func (c *Collector) Start(ctx context.Context) error
  • func (c *Collector) Traces() map[string][]Span
• type Event
  • func NewSpanEndEvent(spanID, traceID string, t time.Time, attrs map[string]string) Event
  • func NewSpanStartEvent(spanID, traceID, parentID, name string, kind SpanKind, t time.Time) Event
• type EventType
  • func (e EventType) String() string
• type Span
  • func NewSpan(id, traceID, name string, kind SpanKind, startTime, endTime time.Time) Span
  • func (s Span) Clone() Span
  • func (s Span) Duration() time.Duration
  • func (s Span) WithAttr(key, value string) Span
  • func (s Span) WithChild(child Span) Span
  • func (s Span) WithParentID(parentID string) Span
• type SpanKind
  • func (k SpanKind) String() string
• type ViewClient
  • func NewViewClient(socketPath string) *ViewClient
  • func (c *ViewClient) Run(ctx context.Context, onSpan func(traceID string, span Span)) error
• type ViewServer
  • func NewViewServer(socketPath string) *ViewServer
  • func (s *ViewServer) Broadcast(span Span)
  • func (s *ViewServer) Close() error
  • func (s *ViewServer) ConnCount() int
  • func (s *ViewServer) Listen(ctx context.Context) error
  • func (s *ViewServer) Serve(ctx context.Context) error
  • func (s *ViewServer) SocketPath() string
  • func (s *ViewServer) Start(ctx context.Context) error

Types

type Collector

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

Collector receives trace events over a Unix domain socket and assembles them into complete Span trees.

func NewCollector

func NewCollector(socketPath string) *Collector

NewCollector creates a collector that listens on the given Unix socket path.

func (*Collector) Listen

func (c *Collector) Listen(ctx context.Context) error

Listen creates the Unix domain socket. Call Serve afterwards to begin accepting connections.

func (*Collector) OnSpanComplete

func (c *Collector) OnSpanComplete(fn func(traceID string, span Span))

OnSpanComplete registers a callback invoked when a span is completed.

func (*Collector) Serve

func (c *Collector) Serve(ctx context.Context) error

Serve accepts connections on the already-bound listener. It blocks until the context is cancelled or the listener is closed.

func (*Collector) SocketPath

func (c *Collector) SocketPath() string

SocketPath returns the path of the Unix domain socket.

func (*Collector) Start

func (c *Collector) Start(ctx context.Context) error

Start binds the socket and begins accepting connections. It blocks until the context is cancelled.

func (*Collector) Traces

func (c *Collector) Traces() map[string][]Span

Traces returns a snapshot of all completed root spans grouped by trace ID.

type Event

type Event struct {
	Type     EventType         `json:"type"`
	SpanID   string            `json:"span_id"`
	TraceID  string            `json:"trace_id"`
	ParentID string            `json:"parent_id,omitzero"`
	Name     string            `json:"name"`
	Kind     SpanKind          `json:"kind"`
	Time     time.Time         `json:"time"`
	Attrs    map[string]string `json:"attrs,omitzero"`
}

Event is the unit of data sent from the instrumented application to the go-trace collector over a Unix domain socket.

func NewSpanEndEvent

func NewSpanEndEvent(spanID, traceID string, t time.Time, attrs map[string]string) Event

NewSpanEndEvent creates an event representing the end of a span.

func NewSpanStartEvent

func NewSpanStartEvent(spanID, traceID, parentID, name string, kind SpanKind, t time.Time) Event

NewSpanStartEvent creates an event representing the beginning of a span.

type EventType

type EventType int

EventType represents the kind of trace event.

const (
	EventSpanStart EventType = iota
	EventSpanEnd
)

func (EventType) String

func (e EventType) String() string

type Span

type Span struct {
	ID        string            `json:"id"`
	TraceID   string            `json:"trace_id"`
	ParentID  string            `json:"parent_id,omitzero"`
	Name      string            `json:"name"`
	Kind      SpanKind          `json:"kind"`
	StartTime time.Time         `json:"start_time"`
	EndTime   time.Time         `json:"end_time"`
	Attrs     map[string]string `json:"attrs,omitzero"`
	Children  []Span            `json:"children,omitzero"`
}

Span represents a single unit of work in a trace. Span is a value type; all mutation methods return a new copy.

func NewSpan

func NewSpan(id, traceID, name string, kind SpanKind, startTime, endTime time.Time) Span

NewSpan creates a span with the required fields.

func (Span) Clone

func (s Span) Clone() Span

Clone returns a deep copy of the span, including Attrs and Children.

func (Span) Duration

func (s Span) Duration() time.Duration

Duration returns the elapsed time of the span.

func (Span) WithAttr

func (s Span) WithAttr(key, value string) Span

WithAttr returns a new Span with the key-value pair added.

func (Span) WithChild

func (s Span) WithChild(child Span) Span

WithChild returns a new Span with the child appended.

func (Span) WithParentID

func (s Span) WithParentID(parentID string) Span

WithParentID returns a new Span with the given parent ID.

type SpanKind

type SpanKind int

SpanKind represents the type of operation a span tracks.

const (
	SpanKindFunction SpanKind = iota
	SpanKindHTTP
	SpanKindSQL
)

func (SpanKind) String

func (k SpanKind) String() string

type ViewClient

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

ViewClient connects to a ViewServer and receives completed spans.

func NewViewClient

func NewViewClient(socketPath string) *ViewClient

NewViewClient creates a client that connects to the given socket path.

func (*ViewClient) Run

func (c *ViewClient) Run(ctx context.Context, onSpan func(traceID string, span Span)) error

Run connects to the view server and calls onSpan for each received span. It blocks until the context is cancelled or the server closes the connection.

type ViewServer

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

ViewServer broadcasts completed spans to connected view clients over a Unix domain socket using JSON lines.

func NewViewServer

func NewViewServer(socketPath string) *ViewServer

NewViewServer creates a view server that listens on the given socket path.

func (*ViewServer) Broadcast

func (s *ViewServer) Broadcast(span Span)

Broadcast sends a completed span to all connected view clients. Connections that fail to receive are removed silently.

func (*ViewServer) Close

func (s *ViewServer) Close() error

Close shuts down the server, closes all connections, and removes the socket file.

func (*ViewServer) ConnCount

func (s *ViewServer) ConnCount() int

ConnCount returns the number of active client connections.

func (*ViewServer) Listen

func (s *ViewServer) Listen(ctx context.Context) error

Listen creates the Unix domain socket. Call Serve afterwards to begin accepting connections. This split allows callers to detect listen errors synchronously before launching Serve in a goroutine.

func (*ViewServer) Serve

func (s *ViewServer) Serve(ctx context.Context) error

Serve accepts connections on the already-bound listener. It blocks until the context is cancelled or the listener is closed.

func (*ViewServer) SocketPath

func (s *ViewServer) SocketPath() string

SocketPath returns the path of the Unix domain socket.

func (*ViewServer) Start

func (s *ViewServer) Start(ctx context.Context) error

Start binds the socket and begins accepting connections. It blocks until the context is cancelled.