diff --git a/doc/cookbook/distributed_tracing.md b/doc/cookbook/distributed_tracing.md index 61b50637cc..969812c0eb 100644 --- a/doc/cookbook/distributed_tracing.md +++ b/doc/cookbook/distributed_tracing.md @@ -1,13 +1,13 @@ # Distributed Tracing -We used [OpenTracing API](https://opentracing.io/) to build the tracing framework of Easegress. We officially support [Zipkin](https://zipkin.io/). We can enable tracing in `HTTPServer`, it will start a span whose name is the same ahs the server. The matched pipeline will start a child span, and its internal filters will start children spans according to their implementation, for example, the `Proxy` did it. +Easegress tracing is based on [OpenTracing API](https://opentracing.io/) and officially supports [Zipkin](https://zipkin.io/). We can enable tracing in `HTTPServer` by defining `tracing` entry. Tracing will create spans containing the pipeline name, tracing service name (`tracing.serviceName`), HTTP path and HTTP method. The matched pipeline will start a child span, and its internal filters will start children spans according to their implementation. For example, the `Proxy` filter has specific span implementation. ```yaml kind: HTTPServer name: http-server-example port: 10080 tracing: - serviceName: httpServerExmple + serviceName: httpServerExample zipkin: hostport: 0.0.0.0:10080 serverURL: http://localhost:9412/api/v2/spans @@ -18,4 +18,27 @@ rules: - paths: - pathPrefix: /pipeline backend: http-pipeline-example -``` \ No newline at end of file +``` + +## Custom tags +Custom tags can help to filter tracing spans. For example, sometimes it is useful to include the version or deployment identifier to tracing logs, to see the latency impact of a new deployment. Here's an example with custom tag: + +```yaml +kind: HTTPServer +name: http-server-example +port: 10080 +tracing: + serviceName: httpServerExample + tags: # add "tags" entry and tags as key-value pairs + deployment: '' + zipkin: + hostport: 0.0.0.0:10080 + serverURL: http://localhost:9412/api/v2/spans + sampleRate: 1 + sameSpan: true + id128Bit: false +rules: + - paths: + - pathPrefix: /pipeline + backend: http-pipeline-example +``` diff --git a/pkg/context/httpcontext.go b/pkg/context/httpcontext.go index f26784bdd8..3d4730ecb4 100644 --- a/pkg/context/httpcontext.go +++ b/pkg/context/httpcontext.go @@ -159,9 +159,12 @@ func New(stdw http.ResponseWriter, stdr *http.Request, stdr = stdr.WithContext(stdctx) startTime := fasttime.Now() + span := tracing.NewSpanWithStart(tracer, spanName, startTime) + span.SetTag("http.method", stdr.Method) + span.SetTag("http.path", stdr.URL.Path) return &httpContext{ startTime: startTime, - span: tracing.NewSpanWithStart(tracer, spanName, startTime), + span: span, originalReqCtx: originalReqCtx, stdctx: stdctx, cancelFunc: cancelFunc, diff --git a/pkg/tracing/span.go b/pkg/tracing/span.go index 21cb0da55e..78d4f164a1 100644 --- a/pkg/tracing/span.go +++ b/pkg/tracing/span.go @@ -62,6 +62,9 @@ type ( // "type", "cache timeout", // "waited.millis", 1500) LogKV(kvs ...interface{}) + + // SetTag sets tag key and value. + SetTag(key string, value string) } span struct { @@ -83,9 +86,13 @@ func NewSpanWithStart(tracer *Tracing, name string, startAt time.Time) Span { } func newSpanWithStart(tracer *Tracing, name string, startAt time.Time) Span { + newSpan := tracer.StartSpan(name, opentracing.StartTime(startAt)) + for tagKey, tagValue := range tracer.tags { + newSpan.SetTag(tagKey, tagValue) + } return &span{ tracer: tracer, - span: tracer.StartSpan(name, opentracing.StartTime(startAt)), + span: newSpan, } } @@ -139,3 +146,7 @@ func (s *span) SetName(name string) { func (s *span) LogKV(kv ...interface{}) { s.span.LogKV(kv...) } + +func (s *span) SetTag(key string, value string) { + s.span.SetTag(key, value) +} diff --git a/pkg/tracing/tracing.go b/pkg/tracing/tracing.go index bcd8f5d581..380eb2e8b9 100644 --- a/pkg/tracing/tracing.go +++ b/pkg/tracing/tracing.go @@ -28,7 +28,8 @@ import ( type ( // Spec describes Tracing. Spec struct { - ServiceName string `yaml:"serviceName" jsonschema:"required"` + ServiceName string `yaml:"serviceName" jsonschema:"required"` + Tags map[string]string `yaml:"tags" jsonschema:"omitempty"` Zipkin *zipkin.Spec `yaml:"zipkin" jsonschema:"omitempty"` } @@ -36,6 +37,7 @@ type ( // Tracing is the tracing. Tracing struct { opentracing.Tracer + tags map[string]string closer io.Closer } @@ -62,6 +64,7 @@ func New(spec *Spec) (*Tracing, error) { return &Tracing{ Tracer: tracer, + tags: spec.Tags, closer: closer, }, nil }