fix #316; Add more tracing information

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
-```
+```
+
+## 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: '<id>'
+  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
+```

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,

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)
+}

pkg/tracing/tracing.go

@@ -28,14 +28,16 @@ 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"`
 	}
 
 	// 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
 }