Merge pull request #103 from cschleiden/document-tracing

Make tracer available to workflows and document

Author: cschleiden

README.md

@@ -536,6 +536,40 @@ logger := activity.Logger(ctx)
 
 The returned `logger` implements the `Logger` interface, and already has the id of the activity, and the workflow instance and execution IDs set as default fields.
 
+### Tracing
+
+The library supports tracing via [OpenTelemetry](https://opentelemetry.io/). When you pass a `TracerProvider` when creating a backend instance, workflow execution will be traced. You can also add additional spans for both activities and workflows.
+
+_Note: the support is considered experimental right now, if you decide to use it, please leave feedback_
+
+#### Activities
+
+The `context.Context` passed into activities is set up with the correct current span. If you create additional spans, they'll show up under the `ActivityTaskExecution`:
+
+```go
+func Activity1(ctx context.Context, a, b int) (int, error) {
+	ctx, span := otel.Tracer("activity1").Start(ctx, "Custom Activity1 span")
+	defer span.End()
+
+	// Do something
+}
+```
+
+#### Workflows
+
+For workflows the usage is a bit different, the tracer needs to be aware of whether the workflow is being replayed or not:
+
+```go
+func Workflow(ctx workflow.Context) error {
+	ctx, span := workflow.Tracer(ctx).Start(ctx, "Workflow1 span", trace.WithAttributes(
+		// Add additional
+		attribute.String("msg", "hello world"),
+	))
+
+	// Do something
+
+	span.End()
+```
 
 ## Tools
 

samples/tracing/workflow.go

@@ -7,6 +7,8 @@ import (
 	"github.com/cschleiden/go-workflows/activity"
 	"github.com/cschleiden/go-workflows/workflow"
 	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/attribute"
+	"go.opentelemetry.io/otel/trace"
 )
 
 type Inputs struct {
@@ -19,6 +21,15 @@ func Workflow1(ctx workflow.Context, msg string, times int, inputs Inputs) (int,
 	logger.Debug("Entering Workflow1", "msg", msg, "times", times, "inputs", inputs)
 	defer logger.Debug("Leaving Workflow1")
 
+	ctx, span := workflow.Tracer(ctx).Start(ctx, "Workflow1 span", trace.WithAttributes(
+		// Add additional
+		attribute.String("msg", "hello world"),
+	))
+
+	// Do something
+
+	span.End()
+
 	workflow.ExecuteActivity[int](ctx, workflow.DefaultActivityOptions, Activity1, 35, 12).Get(ctx)
 
 	workflow.Sleep(ctx, time.Second*1)

workflow/tracer.go

@@ -0,0 +1,30 @@
+package workflow
+
+import (
+	"github.com/cschleiden/go-workflows/internal/workflowtracer"
+	"go.opentelemetry.io/otel/trace"
+)
+
+type Span interface {
+	End()
+}
+
+type WorkflowTracer interface {
+	Start(ctx Context, name string, opts ...trace.SpanStartOption) (Context, Span)
+}
+
+func Tracer(ctx Context) WorkflowTracer {
+	return &workflowTracer{
+		t: workflowtracer.Tracer(ctx),
+	}
+}
+
+type workflowTracer struct {
+	t *workflowtracer.WorkflowTracer
+}
+
+func (wt *workflowTracer) Start(ctx Context, name string, opts ...trace.SpanStartOption) (Context, Span) {
+	ctx, span := wt.t.Start(ctx, name, opts...)
+
+	return ctx, &span
+}