[WIP] factor out trace functionality into separate package and add Go docs

replication/driver/replication_driver.go

@@ -10,10 +10,10 @@ import (
 	"sync"
 	"time"
 
+	"github.com/zrepl/zrepl/daemon/logging/trace"
 	"google.golang.org/grpc/codes"
 	"google.golang.org/grpc/status"
 
-	"github.com/zrepl/zrepl/daemon/logging"
 	"github.com/zrepl/zrepl/replication/report"
 	"github.com/zrepl/zrepl/util/chainlock"
 	"github.com/zrepl/zrepl/util/envconst"
@@ -297,7 +297,7 @@ func (a *attempt) do(ctx context.Context, prev *attempt) {
 
 // if no error occurs, returns a map that maps this attempt's a.fss to `prev`'s a.fss
 func (a *attempt) doGlobalPlanning(ctx context.Context, prev *attempt) map[*fs]*fs {
-	ctx, endSpan := logging.WithSpan(ctx, "plan")
+	ctx, endSpan := trace.WithSpan(ctx, "plan")
 	defer endSpan()
 	pfss, err := a.planner.Plan(ctx)
 	errTime := time.Now()
@@ -389,7 +389,7 @@ func (a *attempt) doGlobalPlanning(ctx context.Context, prev *attempt) map[*fs]*
 }
 
 func (a *attempt) doFilesystems(ctx context.Context, prevs map[*fs]*fs) {
-	ctx, endSpan := logging.WithSpan(ctx, "do-repl")
+	ctx, endSpan := trace.WithSpan(ctx, "do-repl")
 	defer endSpan()
 
 	defer a.l.Lock().Unlock()
@@ -402,7 +402,7 @@ func (a *attempt) doFilesystems(ctx context.Context, prevs map[*fs]*fs) {
 		go func(f *fs) {
 			defer fssesDone.Done()
 			// avoid explosion of tasks with name f.report().Info.Name
-			ctx, endTask := logging.WithTaskAndSpan(ctx, "repl-fs", f.report().Info.Name)
+			ctx, endTask := trace.WithTaskAndSpan(ctx, "repl-fs", f.report().Info.Name)
 			defer endTask()
 			f.do(ctx, stepQueue, prevs[f])
 		}(f)
@@ -610,7 +610,7 @@ func (f *fs) do(ctx context.Context, pq *stepQueue, prev *fs) {
 			targetDate := s.step.TargetDate()
 			defer pq.WaitReady(ctx, f, targetDate)()
 			// do the step
-			ctx, endSpan := logging.WithSpan(ctx, fmt.Sprintf("%#v", s.step.ReportInfo()))
+			ctx, endSpan := trace.WithSpan(ctx, fmt.Sprintf("%#v", s.step.ReportInfo()))
 			defer endSpan()
 			err, errTime = s.step.Step(ctx), time.Now() // no shadow
 		})

replication/driver/replication_driver_test.go

@@ -10,8 +10,8 @@ import (
 	"time"
 
 	"github.com/stretchr/testify/require"
+	"github.com/zrepl/zrepl/daemon/logging/trace"
 
-	"github.com/zrepl/zrepl/daemon/logging"
 	"github.com/zrepl/zrepl/replication/report"
 
 	"github.com/stretchr/testify/assert"
@@ -150,7 +150,7 @@ func (f *mockStep) ReportInfo() *report.StepInfo {
 func TestReplication(t *testing.T) {
 
 	ctx := context.Background()
-	defer logging.WithTaskFromStackUpdateCtx(&ctx)()
+	defer trace.WithTaskFromStackUpdateCtx(&ctx)()
 
 	mp := &mockPlanner{}
 	getReport, wait := Do(ctx, mp)

replication/driver/replication_stepqueue.go

@@ -5,7 +5,7 @@ import (
 	"context"
 	"time"
 
-	"github.com/zrepl/zrepl/daemon/logging"
+	"github.com/zrepl/zrepl/daemon/logging/trace"
 	"github.com/zrepl/zrepl/util/chainlock"
 )
 
@@ -158,7 +158,7 @@ func (q *stepQueue) sendAndWaitForWakeup(ident interface{}, targetDate time.Time
 
 // Wait for the ident with targetDate to be selected to run.
 func (q *stepQueue) WaitReady(ctx context.Context, ident interface{}, targetDate time.Time) StepCompletedFunc {
-	defer logging.WithSpanFromStackUpdateCtx(&ctx)()
+	defer trace.WithSpanFromStackUpdateCtx(&ctx)()
 	if targetDate.IsZero() {
 		panic("targetDate of zero is reserved for marking Done")
 	}

replication/driver/replication_stepqueue_test.go

@@ -12,21 +12,20 @@ import (
 
 	"github.com/montanaflynn/stats"
 	"github.com/stretchr/testify/assert"
-
-	"github.com/zrepl/zrepl/daemon/logging"
+	"github.com/zrepl/zrepl/daemon/logging/trace"
 )
 
 // FIXME: this test relies on timing and is thus rather flaky
 // (relies on scheduler responsiveness of < 500ms)
 func TestPqNotconcurrent(t *testing.T) {
-	ctx, end := logging.WithTaskFromStack(context.Background())
+	ctx, end := trace.WithTaskFromStack(context.Background())
 	defer end()
 	var ctr uint32
 	q := newStepQueue()
 	var wg sync.WaitGroup
 	wg.Add(4)
 	go func() {
-		ctx, end := logging.WithTaskFromStack(ctx)
+		ctx, end := trace.WithTaskFromStack(ctx)
 		defer end()
 		defer wg.Done()
 		defer q.WaitReady(ctx, "1", time.Unix(9999, 0))()
@@ -41,7 +40,7 @@ func TestPqNotconcurrent(t *testing.T) {
 
 	// while "1" is still running, queue in "2", "3" and "4"
 	go func() {
-		ctx, end := logging.WithTaskFromStack(ctx)
+		ctx, end := trace.WithTaskFromStack(ctx)
 		defer end()
 		defer wg.Done()
 		defer q.WaitReady(ctx, "2", time.Unix(2, 0))()
@@ -49,7 +48,7 @@ func TestPqNotconcurrent(t *testing.T) {
 		assert.Equal(t, uint32(2), ret)
 	}()
 	go func() {
-		ctx, end := logging.WithTaskFromStack(ctx)
+		ctx, end := trace.WithTaskFromStack(ctx)
 		defer end()
 		defer wg.Done()
 		defer q.WaitReady(ctx, "3", time.Unix(3, 0))()
@@ -57,7 +56,7 @@ func TestPqNotconcurrent(t *testing.T) {
 		assert.Equal(t, uint32(3), ret)
 	}()
 	go func() {
-		ctx, end := logging.WithTaskFromStack(ctx)
+		ctx, end := trace.WithTaskFromStack(ctx)
 		defer end()
 		defer wg.Done()
 		defer q.WaitReady(ctx, "4", time.Unix(4, 0))()
@@ -90,7 +89,7 @@ func (r record) String() string {
 // Hence, perform some statistics on the wakeup times and assert that the mean wakeup
 // times for each step are close together.
 func TestPqConcurrent(t *testing.T) {
-	ctx, end := logging.WithTaskFromStack(context.Background())
+	ctx, end := trace.WithTaskFromStack(context.Background())
 	defer end()
 
 	q := newStepQueue()
@@ -105,7 +104,7 @@ func TestPqConcurrent(t *testing.T) {
 	records := make(chan []record, filesystems)
 	for fs := 0; fs < filesystems; fs++ {
 		go func(fs int) {
-			ctx, end := logging.WithTaskFromStack(ctx)
+			ctx, end := trace.WithTaskFromStack(ctx)
 			defer end()
 			defer wg.Done()
 			recs := make([]record, 0)