kratos: github.com/bilibili/kratos/pkg/net/trace Index | Files | Directories

package trace

import "github.com/bilibili/kratos/pkg/net/trace"

Index

Package Files

config.go const.go context.go dapper.go marshal.go noop.go option.go propagation.go report.go sample.go span.go tag.go tracer.go util.go

Constants

const (
    KratosTraceID    = "kratos-trace-id"
    KratosTraceDebug = "kratos-trace-debug"
)

Trace key

const (
    // The software package, framework, library, or module that generated the associated Span.
    // E.g., "grpc", "django", "JDBI".
    // type string
    TagComponent = "component"

    // Database instance name.
    // E.g., In java, if the jdbc.url="jdbc:mysql://127.0.0.1:3306/customers", the instance name is "customers".
    // type string
    TagDBInstance = "db.instance"

    // A database statement for the given database type.
    // E.g., for db.type="sql", "SELECT * FROM wuser_table"; for db.type="redis", "SET mykey 'WuValue'".
    TagDBStatement = "db.statement"

    // Database type. For any SQL database, "sql". For others, the lower-case database category,
    // e.g. "cassandra", "hbase", or "redis".
    // type string
    TagDBType = "db.type"

    // Username for accessing database. E.g., "readonly_user" or "reporting_user"
    // type string
    TagDBUser = "db.user"

    // true if and only if the application considers the operation represented by the Span to have failed
    // type bool
    TagError = "error"

    // HTTP method of the request for the associated Span. E.g., "GET", "POST"
    // type string
    TagHTTPMethod = "http.method"

    // HTTP response status code for the associated Span. E.g., 200, 503, 404
    // type integer
    TagHTTPStatusCode = "http.status_code"

    // URL of the request being handled in this segment of the trace, in standard URI format.
    // E.g., "https://domain.net/path/to?resource=here"
    // type string
    TagHTTPURL = "http.url"

    // An address at which messages can be exchanged.
    // E.g. A Kafka record has an associated "topic name" that can be extracted by the instrumented producer or consumer and stored using this tag.
    // type string
    TagMessageBusDestination = "message_bus.destination"

    // Remote "address", suitable for use in a networking client library.
    // This may be a "ip:port", a bare "hostname", a FQDN, or even a JDBC substring like "mysql://prod-db:3306"
    // type string
    TagPeerAddress = "peer.address"

    // 	Remote hostname. E.g., "opentracing.io", "internal.dns.name"
    // type string
    TagPeerHostname = "peer.hostname"

    // Remote IPv4 address as a .-separated tuple. E.g., "127.0.0.1"
    // type string
    TagPeerIPv4 = "peer.ipv4"

    // Remote IPv6 address as a string of colon-separated 4-char hex tuples.
    // E.g., "2001:0db8:85a3:0000:0000:8a2e:0370:7334"
    // type string
    TagPeerIPv6 = "peer.ipv6"

    // Remote port. E.g., 80
    // type integer
    TagPeerPort = "peer.port"

    // Remote service name (for some unspecified definition of "service").
    // E.g., "elasticsearch", "a_custom_microservice", "memcache"
    // type string
    TagPeerService = "peer.service"

    // If greater than 0, a hint to the Tracer to do its best to capture the trace.
    // If 0, a hint to the trace to not-capture the trace. If absent, the Tracer should use its default sampling mechanism.
    // type string
    TagSamplingPriority = "sampling.priority"

    // Either "client" or "server" for the appropriate roles in an RPC,
    // and "producer" or "consumer" for the appropriate roles in a messaging scenario.
    // type string
    TagSpanKind = "span.kind"

    // legacy tag
    TagAnnotation = "legacy.annotation"
    TagAddress    = "legacy.address"
    TagComment    = "legacy.comment"
)

Standard Span tags https://github.com/opentracing/specification/blob/master/semantic_conventions.md#span-tags-table

const (
    // The type or "kind" of an error (only for event="error" logs). E.g., "Exception", "OSError"
    // type string
    LogErrorKind = "error.kind"

    // For languages that support such a thing (e.g., Java, Python),
    // the actual Throwable/Exception/Error object instance itself.
    // E.g., A java.lang.UnsupportedOperationException instance, a python exceptions.NameError instance
    // type string
    LogErrorObject = "error.object"

    // A stable identifier for some notable moment in the lifetime of a Span. For instance, a mutex lock acquisition or release or the sorts of lifetime events in a browser page load described in the Performance.timing specification. E.g., from Zipkin, "cs", "sr", "ss", or "cr". Or, more generally, "initialized" or "timed out". For errors, "error"
    // type string
    LogEvent = "event"

    // A concise, human-readable, one-line message explaining the event.
    // E.g., "Could not connect to backend", "Cache invalidation succeeded"
    // type string
    LogMessage = "message"

    // A stack trace in platform-conventional format; may or may not pertain to an error. E.g., "File \"example.py\", line 7, in \<module\>\ncaller()\nFile \"example.py\", line 5, in caller\ncallee()\nFile \"example.py\", line 2, in callee\nraise Exception(\"Yikes\")\n"
    // type string
    LogStack = "stack"
)

Standard log tags

Variables

var (
    // ErrUnsupportedFormat occurs when the `format` passed to Tracer.Inject() or
    // Tracer.Extract() is not recognized by the Tracer implementation.
    ErrUnsupportedFormat = errs.New("trace: Unknown or unsupported Inject/Extract format")

    // ErrTraceNotFound occurs when the `carrier` passed to
    // Tracer.Extract() is valid and uncorrupted but has insufficient
    // information to extract a Trace.
    ErrTraceNotFound = errs.New("trace: Trace not found in Extract carrier")

    // ErrInvalidTrace errors occur when Tracer.Inject() is asked to
    // operate on a Trace which it is not prepared to handle (for
    // example, since it was created by a different tracer implementation).
    ErrInvalidTrace = errs.New("trace: Trace type incompatible with tracer")

    // ErrInvalidCarrier errors occur when Tracer.Inject() or Tracer.Extract()
    // implementations expect a different type of `carrier` than they are
    // given.
    ErrInvalidCarrier = errs.New("trace: Invalid Inject/Extract carrier")

    // ErrTraceCorrupted occurs when the `carrier` passed to
    // Tracer.Extract() is of the expected type but is corrupted.
    ErrTraceCorrupted = errs.New("trace: Trace data corrupted in Extract carrier")
)

func Close Uses

func Close() error

Close trace flush data.

func Init Uses

func Init(cfg *Config)

Init init trace report.

func Inject Uses

func Inject(t Trace, format interface{}, carrier interface{}) error

Inject takes the Trace instance and injects it for propagation within `carrier`. The actual type of `carrier` depends on the value of `format`.

func NewContext Uses

func NewContext(ctx context.Context, t Trace) context.Context

NewContext new a trace context. NOTE: This method is not thread safe.

func SetGlobalTracer Uses

func SetGlobalTracer(tracer Tracer)

SetGlobalTracer SetGlobalTracer

type BuiltinFormat Uses

type BuiltinFormat byte

BuiltinFormat is used to demarcate the values within package `trace` that are intended for use with the Tracer.Inject() and Tracer.Extract() methods.

const (
    // HTTPFormat represents Trace as HTTP header string pairs.
    //
    // the HTTPFormat format requires that the keys and values
    // be valid as HTTP headers as-is (i.e., character casing may be unstable
    // and special characters are disallowed in keys, values should be
    // URL-escaped, etc).
    //
    // the carrier must be a `http.Header`.
    HTTPFormat BuiltinFormat = iota
    // GRPCFormat represents Trace as gRPC metadata.
    //
    // the carrier must be a `google.golang.org/grpc/metadata.MD`.
    GRPCFormat
)

support format list

type Carrier Uses

type Carrier interface {
    Set(key, val string)
    Get(key string) string
}

Carrier propagator must convert generic interface{} to something this implement Carrier interface, Trace can use Carrier to represents itself.

type Config Uses

type Config struct {
    // Report network e.g. unixgram, tcp, udp
    Network string `dsn:"network"`
    // For TCP and UDP networks, the addr has the form "host:port".
    // For Unix networks, the address must be a file system path.
    Addr string `dsn:"address"`
    // Report timeout
    Timeout xtime.Duration `dsn:"query.timeout,200ms"`
    // DisableSample
    DisableSample bool `dsn:"query.disable_sample"`
    // ProtocolVersion
    ProtocolVersion int32 `dsn:"query.protocol_version,1"`
    // Probability probability sampling
    Probability float32 `dsn:"-"`
}

Config config.

type LogField Uses

type LogField struct {
    Key   string
    Value string
}

LogField LogField

func Log Uses

func Log(key string, val string) LogField

Log new log.

type Option Uses

type Option func(*option)

Option dapper Option

func EnableDebug Uses

func EnableDebug() Option

EnableDebug enable debug mode

type Span Uses

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

Span is a trace span.

func (*Span) Context Uses

func (s *Span) Context() spanContext

func (*Span) Duration Uses

func (s *Span) Duration() time.Duration

func (*Span) Finish Uses

func (s *Span) Finish(perr *error)

func (*Span) Follow Uses

func (s *Span) Follow(serviceName, operationName string) Trace

func (*Span) Fork Uses

func (s *Span) Fork(serviceName, operationName string) Trace

func (*Span) Logs Uses

func (s *Span) Logs() []*protogen.Log

func (*Span) Name Uses

func (s *Span) Name() string

func (*Span) SetLog Uses

func (s *Span) SetLog(logs ...LogField) Trace

LogFields is an efficient and type-checked way to record key:value NOTE current unsupport

func (*Span) SetTag Uses

func (s *Span) SetTag(tags ...Tag) Trace

func (*Span) SetTitle Uses

func (s *Span) SetTitle(operationName string)

SetTitle reset trace title

func (*Span) StartTime Uses

func (s *Span) StartTime() time.Time

func (*Span) String Uses

func (s *Span) String() string

func (*Span) Tags Uses

func (s *Span) Tags() []Tag

func (*Span) TraceID Uses

func (s *Span) TraceID() string

func (*Span) Visit Uses

func (s *Span) Visit(fn func(k, v string))

Visit visits the k-v pair in trace, calling fn for each.

type Tag Uses

type Tag struct {
    Key   string
    Value interface{}
}

Tag interface

func Bool Uses

func Bool(key string, val bool) Tag

Bool new tagBool NOTE: use TagBool

func Int Uses

func Int(key string, val int) Tag

Int new tag Int. NOTE: use TagInt

func String Uses

func String(key string, val string) Tag

String new tag String. NOTE: use TagString

func TagBool Uses

func TagBool(key string, val bool) Tag

TagBool new bool tag

func TagFloat32 Uses

func TagFloat32(key string, val float32) Tag

TagFloat32 new float64 tag

func TagFloat64 Uses

func TagFloat64(key string, val float64) Tag

TagFloat64 new float64 tag

func TagInt Uses

func TagInt(key string, val int) Tag

TagInt new int tag

func TagInt64 Uses

func TagInt64(key string, val int64) Tag

TagInt64 new int64 tag.

func TagString Uses

func TagString(key string, val string) Tag

TagString new string tag.

type Trace Uses

type Trace interface {
    // return current trace id.
    TraceID() string
    // Fork fork a trace with client trace.
    Fork(serviceName, operationName string) Trace

    // Follow
    Follow(serviceName, operationName string) Trace

    // Finish when trace finish call it.
    Finish(err *error)

    // Adds a tag to the trace.
    //
    // If there is a pre-existing tag set for `key`, it is overwritten.
    //
    // Tag values can be numeric types, strings, or bools. The behavior of
    // other tag value types is undefined at the OpenTracing level. If a
    // tracing system does not know how to handle a particular value type, it
    // may ignore the tag, but shall not panic.
    // NOTE current only support legacy tag: TagAnnotation TagAddress TagComment
    // other will be ignore
    SetTag(tags ...Tag) Trace

    // LogFields is an efficient and type-checked way to record key:value
    // NOTE current unsupport
    SetLog(logs ...LogField) Trace

    // Visit visits the k-v pair in trace, calling fn for each.
    Visit(fn func(k, v string))

    // SetTitle reset trace title
    SetTitle(title string)
}

Trace trace common interface.

func Extract Uses

func Extract(format interface{}, carrier interface{}) (Trace, error)

Extract returns a Trace instance given `format` and `carrier`. return `ErrTraceNotFound` if trace not found.

func FromContext Uses

func FromContext(ctx context.Context) (t Trace, ok bool)

FromContext returns the trace bound to the context, if any.

func New Uses

func New(operationName string, opts ...Option) Trace

New trace instance with given operationName.

type Tracer Uses

type Tracer interface {
    // New trace instance with given title.
    New(operationName string, opts ...Option) Trace
    // Inject takes the Trace instance and injects it for
    // propagation within `carrier`. The actual type of `carrier` depends on
    // the value of `format`.
    Inject(t Trace, format interface{}, carrier interface{}) error
    // Extract returns a Trace instance given `format` and `carrier`.
    // return `ErrTraceNotFound` if trace not found.
    Extract(format interface{}, carrier interface{}) (Trace, error)
}

Tracer is a simple, thin interface for Trace creation and propagation.

func NewTracer Uses

func NewTracer(serviceName string, report reporter, disableSample bool) Tracer

NewTracer new a tracer.

func TracerFromEnvFlag Uses

func TracerFromEnvFlag() (Tracer, error)

TracerFromEnvFlag new tracer from env and flag

Directories

PathSynopsis
mocktrace
proto

Package trace imports 27 packages (graph) and is imported by 9 packages. Updated 2019-07-18. Refresh now. Tools for package owners.