diff --git a/core/trace/carrier.go b/core/trace/carrier.go index 004ace7f..4308b8a9 100644 --- a/core/trace/carrier.go +++ b/core/trace/carrier.go @@ -6,9 +6,11 @@ import ( "strings" ) +// ErrInvalidCarrier indicates an error that the carrier is invalid. var ErrInvalidCarrier = errors.New("invalid carrier") type ( + // Carrier interface wraps the Get and Set method. Carrier interface { Get(key string) string Set(key, value string) diff --git a/core/trace/propagator.go b/core/trace/propagator.go index 32ebf727..9d18979d 100644 --- a/core/trace/propagator.go +++ b/core/trace/propagator.go @@ -7,7 +7,9 @@ import ( ) const ( + // HttpFormat means http carrier format. HttpFormat = iota + // GrpcFormat means grpc carrier format. GrpcFormat ) @@ -17,6 +19,7 @@ var ( ) type ( + // Propagator interface wraps the Extract and Inject methods. Propagator interface { Extract(carrier interface{}) (Carrier, error) Inject(carrier interface{}) (Carrier, error) @@ -58,6 +61,7 @@ func (g grpcPropagator) Inject(carrier interface{}) (Carrier, error) { return nil, ErrInvalidCarrier } +// Extract extracts tracing information from carrier with given format. func Extract(format, carrier interface{}) (Carrier, error) { switch v := format.(type) { case int: @@ -71,6 +75,7 @@ func Extract(format, carrier interface{}) (Carrier, error) { return nil, ErrInvalidCarrier } +// Inject injects tracing information into carrier with given format. func Inject(format, carrier interface{}) (Carrier, error) { switch v := format.(type) { case int: diff --git a/core/trace/span.go b/core/trace/span.go index 7c73f39c..bdbf0af0 100644 --- a/core/trace/span.go +++ b/core/trace/span.go @@ -21,6 +21,7 @@ const ( var spanSep = string([]byte{spanSepRune}) +// A Span is a calling span that connects caller and callee. type Span struct { ctx spanContext serviceName string @@ -58,9 +59,11 @@ func newServerSpan(carrier Carrier, serviceName, operationName string) tracespec } } +// Finish finishes the calling span. func (s *Span) Finish() { } +// Follow follows the tracing service and operation names in context. func (s *Span) Follow(ctx context.Context, serviceName, operationName string) (context.Context, tracespec.Trace) { span := &Span{ ctx: spanContext{ @@ -75,6 +78,7 @@ func (s *Span) Follow(ctx context.Context, serviceName, operationName string) (c return context.WithValue(ctx, tracespec.TracingKey, span), span } +// Fork forks the tracing service and operation names in context. func (s *Span) Fork(ctx context.Context, serviceName, operationName string) (context.Context, tracespec.Trace) { span := &Span{ ctx: spanContext{ @@ -89,14 +93,17 @@ func (s *Span) Fork(ctx context.Context, serviceName, operationName string) (con return context.WithValue(ctx, tracespec.TracingKey, span), span } +// SpanId returns the span id. func (s *Span) SpanId() string { return s.ctx.SpanId() } +// TraceId returns the trace id. func (s *Span) TraceId() string { return s.ctx.TraceId() } +// Visit visits the span using fn. func (s *Span) Visit(fn func(key, val string) bool) { s.ctx.Visit(fn) } @@ -126,6 +133,7 @@ func (s *Span) followSpanId() string { return strings.Join(fields, spanSep) } +// StartClientSpan starts the client span with given context, service and operation names. func StartClientSpan(ctx context.Context, serviceName, operationName string) (context.Context, tracespec.Trace) { if span, ok := ctx.Value(tracespec.TracingKey).(*Span); ok { return span.Fork(ctx, serviceName, operationName) @@ -134,6 +142,7 @@ func StartClientSpan(ctx context.Context, serviceName, operationName string) (co return ctx, emptyNoopSpan } +// StartServerSpan starts the server span with given context, carrier, service and operation names. func StartServerSpan(ctx context.Context, carrier Carrier, serviceName, operationName string) ( context.Context, tracespec.Trace) { span := newServerSpan(carrier, serviceName, operationName) diff --git a/core/trace/tracespec/spancontext.go b/core/trace/tracespec/spancontext.go index 4c140837..cb91d888 100644 --- a/core/trace/tracespec/spancontext.go +++ b/core/trace/tracespec/spancontext.go @@ -1,5 +1,6 @@ package tracespec +// SpanContext interface that represents a span context. type SpanContext interface { TraceId() string SpanId() string diff --git a/core/trace/tracespec/trace.go b/core/trace/tracespec/trace.go index 74db6ff7..b0576ce2 100644 --- a/core/trace/tracespec/trace.go +++ b/core/trace/tracespec/trace.go @@ -2,6 +2,7 @@ package tracespec import "context" +// Trace interface represents a tracing. type Trace interface { SpanContext Finish() diff --git a/core/utils/times.go b/core/utils/times.go index 8d03e266..aeec03bb 100644 --- a/core/utils/times.go +++ b/core/utils/times.go @@ -7,32 +7,39 @@ import ( "github.com/tal-tech/go-zero/core/timex" ) +// A ElapsedTimer is a timer to track the elapsed time. type ElapsedTimer struct { start time.Duration } +// NewElapsedTimer returns a ElapsedTimer. func NewElapsedTimer() *ElapsedTimer { return &ElapsedTimer{ start: timex.Now(), } } +// Duration returns the elapsed time. func (et *ElapsedTimer) Duration() time.Duration { return timex.Since(et.start) } +// Elapsed returns the string representation of elapsed time. func (et *ElapsedTimer) Elapsed() string { return timex.Since(et.start).String() } +// ElapsedMs returns the elapsed time of string on milliseconds. func (et *ElapsedTimer) ElapsedMs() string { return fmt.Sprintf("%.1fms", float32(timex.Since(et.start))/float32(time.Millisecond)) } +// CurrentMicros returns the current microseconds. func CurrentMicros() int64 { return time.Now().UnixNano() / int64(time.Microsecond) } +// CurrentMillis returns the current milliseconds. func CurrentMillis() int64 { return time.Now().UnixNano() / int64(time.Millisecond) } diff --git a/core/utils/uuid.go b/core/utils/uuid.go index 237235db..3fa80829 100644 --- a/core/utils/uuid.go +++ b/core/utils/uuid.go @@ -2,6 +2,7 @@ package utils import "github.com/google/uuid" +// NewUuid returns a uuid string. func NewUuid() string { return uuid.New().String() } diff --git a/core/utils/version.go b/core/utils/version.go index 9f98adc7..ad1ded8c 100644 --- a/core/utils/version.go +++ b/core/utils/version.go @@ -14,7 +14,7 @@ var replacer = stringx.NewReplacer(map[string]string{ "-": ".", }) -// operator compare returns true if the first field and the third field equation holds else false +// CompareVersions returns true if the first field and the third field are equal, otherwise false. func CompareVersions(v1, op, v2 string) bool { result := compare(v1, v2) switch op {