minitrace

README

Minitrace-Go

A high-performance, ergonomic timeline tracing library for Golang.

Basic Usage

package main

import (
    "context"
    "fmt"
    "strconv"

    "github.com/tikv/minitrace-go"
)

func tracedFunc(ctx context.Context, event string) {
    span := minitrace.StartSpan(ctx, event)
    // code snippet...
    span.Finish()
}

func iterTracedFunc(ctx context.Context) {
    // extend tracing context from parent context
    ctx, span := minitrace.StartSpanWithContext(ctx, "1")

    span.AddProperty("k2", "v2")

    for i := 2; i < 10; i++ {
        tracedFunc(ctx, strconv.Itoa(i))
    }
    
    span.Finish()
}

func main() {
    ctx := context.Background()

    // enable tracing
    ctx, root := minitrace.StartRootSpan(ctx, "root", 0, nil)

    root.AddProperty("k1", "v1")

    // pass the context to traced functions
    iterTracedFunc(ctx)

    // collect tracing results into `spans`
    spans, _ := root.Collect()

    // do something with `spans`
    fmt.Printf("%+v", spans)
}

Documentation

Index

• func AccessAttachment(ctx context.Context, fn func(attachment interface{})) (ok bool)
• func CurrentID(ctx context.Context) (spanID uint64, traceID uint64, ok bool)
• type Property
• type Span
• type SpanHandle
  • func StartSpan(ctx context.Context, event string) (handle SpanHandle)
  • func StartSpanWithContext(ctx context.Context, event string) (context.Context, SpanHandle)
  • func (sh *SpanHandle) AccessAttachment(fn func(attachment interface{}))
  • func (sh *SpanHandle) AddProperty(key, value string)
  • func (sh *SpanHandle) Finish()
  • func (sh *SpanHandle) TraceID() uint64
• type Trace
• type TraceHandle
  • func StartRootSpan(ctx context.Context, event string, traceID uint64, parentSpanID uint64, ...) (context.Context, TraceHandle)
  • func (th *TraceHandle) Collect() (trace Trace, attachment interface{})

Functions

func AccessAttachment

func AccessAttachment(ctx context.Context, fn func(attachment interface{})) (ok bool)

func CurrentID

func CurrentID(ctx context.Context) (spanID uint64, traceID uint64, ok bool)

Types

type Property

type Property struct {
	Key   string
	Value string
}

type Span

type Span struct {
	ID              uint64
	ParentID        uint64 // 0 means Root
	BeginUnixTimeNs uint64
	DurationNs      uint64
	Event           string
	Properties      []Property
}

type SpanHandle

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

func StartSpan

func StartSpan(ctx context.Context, event string) (handle SpanHandle)

func StartSpanWithContext

func StartSpanWithContext(ctx context.Context, event string) (context.Context, SpanHandle)

func (*SpanHandle) AccessAttachment

func (sh *SpanHandle) AccessAttachment(fn func(attachment interface{}))

func (*SpanHandle) AddProperty

func (sh *SpanHandle) AddProperty(key, value string)

func (*SpanHandle) Finish

func (sh *SpanHandle) Finish()

func (*SpanHandle) TraceID

func (sh *SpanHandle) TraceID() uint64

type Trace

type Trace struct {
	TraceID uint64
	Spans   []Span
}

type TraceHandle

type TraceHandle struct {
	SpanHandle
}

func StartRootSpan

func StartRootSpan(ctx context.Context, event string, traceID uint64, parentSpanID uint64, attachment interface{}) (context.Context, TraceHandle)

func (*TraceHandle) Collect

func (th *TraceHandle) Collect() (trace Trace, attachment interface{})