improve tracing feature and document it. fix #298

Makefile

@@ -14,9 +14,19 @@ setup-protobuf-macos:
 	@brew install protobuf
 	@go get github.com/golang/protobuf/protoc-gen-go
 
+run-jaeger-aio:
+	@docker-compose -f ./examples/testing/docker-compose-jaeger.yml up -d
+	@echo "Access jaeger UI @ http://localhost:16686"
+
 run-chat-example:
 	@cd examples/testing && docker-compose up -d etcd nats && cd ../demo/chat/ && go run main.go
 
+run-cluster-example-frontend-tracing:
+	@PITAYA_METRICS_PROMETHEUS_PORT=9090 JAEGER_SAMPLER_PARAM=1 JAEGER_DISABLED=false JAEGER_SERVICE_NAME=example-frontend JAEGER_AGENT_PORT=6832 go run examples/demo/cluster/main.go
+
+run-cluster-example-backend-tracing:
+	@PITAYA_METRICS_PROMETHEUS_PORT=9091 JAEGER_SAMPLER_PARAM=1 JAEGER_DISABLED=false JAEGER_SERVICE_NAME=example-backend JAEGER_AGENT_PORT=6832 go run examples/demo/cluster/main.go --port 3251 --type room --frontend=false
+
 run-cluster-example-frontend:
 	@PITAYA_METRICS_PROMETHEUS_PORT=9090 go run examples/demo/cluster/main.go
 
@@ -74,6 +84,9 @@ ensure-e2e-deps-grpc:
 kill-testing-deps:
 	@cd ./examples/testing && docker-compose down; true
 
+kill-jaeger:
+	@docker-compose -f ./examples/testing/docker-compose-jaeger.yml down; true
+
 e2e-test: e2e-test-nats e2e-test-grpc
 
 e2e-test-nats: ensure-testing-deps ensure-testing-bin

docs/index.rst

@@ -16,6 +16,7 @@ Welcome to Pitaya's documentation!
    configuration
    API
    examples
+   tracing
 
 
 Indices and tables

docs/tracing.md

@@ -0,0 +1,57 @@
+Tracing
+=======
+
+Pitaya supports tracing using [OpenTracing](http://opentracing.io/).
+
+### Using Jaeger tracing
+
+First set the required environment variables:
+
+```bash
+export JAEGER_DISABLED=false
+export JAEGER_SERVICE_NAME=my-pitaya-server
+export JAEGER_SAMPLER_PARAM=1 #Ajust accordingly
+```
+
+With these environment variables set, you can use the following code to configure Jaeger:
+
+```go
+func configureJaeger(config *viper.Viper, logger logrus.FieldLogger) {
+	cfg, err := jaegercfg.FromEnv()
+	if cfg.ServiceName == "" {
+		logger.Error("Could not init jaeger tracer without ServiceName, either set environment JAEGER_SERVICE_NAME or cfg.ServiceName = \"my-api\"")
+		return
+	}
+	if err != nil {
+		logger.Error("Could not parse Jaeger env vars: %s", err.Error())
+		return
+	}
+	options := jaeger.Options{ // import "github.com/topfreegames/pitaya/v2/tracing/jaeger"
+		Disabled:    cfg.Disabled,
+		Probability: cfg.Sampler.Param,
+		ServiceName: cfg.ServiceName,
+	}
+	jaeger.Configure(options)
+}
+```
+
+Then in your main function:
+
+```go
+func main() {
+    // ...
+    configureJaeger(config, logger)
+    // ...
+}
+```
+
+Ensure to run this Jaeger initialization code in all your server types. Only changing the "JAEGER_SERVICE_NAME" env var between different types.
+
+### Testing Locally
+```bash
+make run-jaeger-aio
+make run-cluster-example-frontend-tracing
+make run-cluster-example-backend-tracing
+```
+
+Then access Jaeger UI at http://localhost:16686

examples/demo/cluster/main.go

@@ -4,9 +4,12 @@ import (
 	"context"
 	"flag"
 	"fmt"
+	"os"
 
 	"strings"
 
+	"github.com/sirupsen/logrus"
+	"github.com/spf13/viper"
 	"github.com/topfreegames/pitaya/v2"
 	"github.com/topfreegames/pitaya/v2/acceptor"
 	"github.com/topfreegames/pitaya/v2/cluster"
@@ -15,6 +18,8 @@ import (
 	"github.com/topfreegames/pitaya/v2/examples/demo/cluster/services"
 	"github.com/topfreegames/pitaya/v2/groups"
 	"github.com/topfreegames/pitaya/v2/route"
+	"github.com/topfreegames/pitaya/v2/tracing/jaeger"
+	jaegercfg "github.com/uber/jaeger-client-go/config"
 )
 
 var app pitaya.Pitaya
@@ -73,13 +78,35 @@ func configureFrontend(port int) {
 	}
 }
 
+func configureJaeger(config *viper.Viper, logger logrus.FieldLogger) {
+	cfg, err := jaegercfg.FromEnv()
+	if cfg.ServiceName == "" {
+		logger.Error("Could not init jaeger tracer without ServiceName, either set environment JAEGER_SERVICE_NAME or cfg.ServiceName = \"my-api\"")
+		return
+	}
+	if err != nil {
+		logger.Error("Could not parse Jaeger env vars: %s", err.Error())
+		return
+	}
+	options := jaeger.Options{
+		Disabled:    cfg.Disabled,
+		Probability: cfg.Sampler.Param,
+		ServiceName: cfg.ServiceName,
+	}
+	jaeger.Configure(options)
+}
+
 func main() {
 	port := flag.Int("port", 3250, "the port to listen")
 	svType := flag.String("type", "connector", "the server type")
 	isFrontend := flag.Bool("frontend", true, "if server is frontend")
 
 	flag.Parse()
 
+	if os.Getenv("JAEGER_SERVICE_NAME") != "" {
+		configureJaeger(viper.GetViper(), logrus.New())
+	}
+
 	builder := pitaya.NewDefaultBuilder(*isFrontend, *svType, pitaya.Cluster, map[string]string{}, *config.NewDefaultBuilderConfig())
 	if *isFrontend {
 		tcp := acceptor.NewTCPAcceptor(fmt.Sprintf(":%d", *port))
@@ -88,8 +115,6 @@ func main() {
 	builder.Groups = groups.NewMemoryGroupService(*config.NewDefaultMemoryGroupConfig())
 	app = builder.Build()
 
-	//TODO: Oelze pitaya.SetSerializer(protobuf.NewSerializer())
-
 	defer app.Shutdown()
 
 	if !*isFrontend {

examples/testing/docker-compose-jaeger.yml

@@ -0,0 +1,12 @@
+version: '3.7'
+services:
+  jaeger:
+    image: jaegertracing/all-in-one:latest
+    ports:
+      - "16686:16686"
+      - "14268:14268"
+      - "6831:6831/udp"
+      - "6832:6832/udp"
+    environment:
+      - COLLECTOR_OTLP_ENABLED=true
+      - LOG_LEVEL=debug

tracing/jaeger/config.go

@@ -25,6 +25,7 @@ package jaeger
 import (
 	"io"
 
+	"github.com/topfreegames/pitaya/v2/logger"
 	"github.com/uber/jaeger-client-go"
 	"github.com/uber/jaeger-client-go/config"
 )
@@ -38,6 +39,7 @@ type Options struct {
 
 // Configure configures a global Jaeger tracer
 func Configure(options Options) (io.Closer, error) {
+	logger.Log.Infof("Configuring Jaeger with options: %+v", options)
 	cfg := config.Configuration{
 		Disabled: options.Disabled,
 		Sampler: &config.SamplerConfig{

util/util.go

@@ -24,12 +24,13 @@ import (
 	"context"
 	"errors"
 	"fmt"
-	"github.com/nats-io/nuid"
 	"os"
 	"reflect"
 	"runtime/debug"
 	"strconv"
 
+	"github.com/nats-io/nuid"
+
 	"github.com/topfreegames/pitaya/v2/conn/message"
 	"github.com/topfreegames/pitaya/v2/constants"
 	pcontext "github.com/topfreegames/pitaya/v2/context"
@@ -207,7 +208,9 @@ func StartSpanFromRequest(
 	}
 	parent, err := tracing.ExtractSpan(ctx)
 	if err != nil {
-		logger.Log.Warnf("failed to retrieve parent span: %s", err.Error())
+		if err != opentracing.ErrSpanContextNotFound {
+			logger.Log.Warnf("failed to retrieve parent span: %s", err.Error())
+		}
 	}
 	ctx = tracing.StartSpan(ctx, route, tags, parent)
 	return ctx