Add Tracer creation functions

README.md

@@ -34,21 +34,32 @@ does it require?
 ## Usage instructions
 
 ```go
-
-tp, _ := trace.NewTracerProvider(trace.ConsoleProviderType, "", os.Stdout, true)
-defer tp.Shutdown()
-
-tracer := tp.Tracer("my-service")
-
-ctx, span := tracer.Start(context.Background(), "My process")
+// Get TracerProviderType from configuration
+traceType, collectorUrl := trace.TypeFromEnv()
+
+// Create a new Tracer
+ctx, tracer, cleanup, _ := trace.Create(
+    traceType,
+    TracerProviderConfig{
+        TracerName:        "my-tracer",
+        TracerService:     "tracer-service",
+        TracerEnvironment: "development",
+        TracerID:          1,
+        CollectorURL:      collectorUrl,
+        ConsoleWriter:     os.Stdout,
+    },
+)
+defer cleanup(ctx)
+
+// Setup a Span
+ctx, span := tracer.Start(ctx, "My process")
 defer span.End()
 
 // Do some task
 
 if err != nil {
    span.RecordErrorAndSetStatus(err)
 }
-
 ```
 
 ## Contributing

go.mod

@@ -3,7 +3,7 @@ module github.com/cyberark/conjur-opentelemetry-tracer
 go 1.20
 
 require (
-	github.com/stretchr/testify v1.7.2
+	github.com/stretchr/testify v1.8.4
 	go.opentelemetry.io/otel v1.7.0
 	go.opentelemetry.io/otel/exporters/jaeger v1.7.0
 	go.opentelemetry.io/otel/exporters/stdout/stdouttrace v1.7.0
@@ -12,7 +12,7 @@ require (
 )
 
 require (
-	github.com/davecgh/go-spew v1.1.0 // indirect
+	github.com/davecgh/go-spew v1.1.1 // indirect
 	github.com/go-logr/logr v1.2.3 // indirect
 	github.com/go-logr/stdr v1.2.2 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect

go.sum

@@ -1,5 +1,6 @@
-github.com/davecgh/go-spew v1.1.0 h1:ZDRjVQ15GmhC3fiQ8ni8+OwkZQO4DARzQgrnXU1Liz8=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
 github.com/go-logr/logr v1.2.3 h1:2DntVwHkVopvECVRSlL5PSo9eG+cAkDCuckLubN+rq0=
 github.com/go-logr/logr v1.2.3/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
@@ -9,11 +10,11 @@ github.com/google/go-cmp v0.5.7 h1:81/ik6ipDQS2aGcBfIN5dHDB36BwrStyeAQquSYCV4o=
 github.com/google/go-cmp v0.5.7/go.mod h1:n+brtR0CgQNWTVd5ZUFpTBC8YFBDLK/h/bpaJ8/DtOE=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
-github.com/stretchr/objx v0.1.0 h1:4G4v2dO3VZwixGIRoQ5Lfboy6nUhCyYzaqnIAPPhYs4=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/objx v0.5.0 h1:1zr/of2m5FGMsad5YfcqgdqdWrIhu+EBEJRhR1U7z/c=
 github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
-github.com/stretchr/testify v1.7.2 h1:4jaiDzPyXQvSd7D0EjG45355tLlV3VOECpq10pLC+8s=
-github.com/stretchr/testify v1.7.2/go.mod h1:R6va5+xMeoiuVRoj+gSkQ7d3FALtqAAGI1FQKckRals=
+github.com/stretchr/testify v1.8.4 h1:CcVxjf3Q8PM0mHUKJCdn+eZZtm5yQwehR5yeSVQQcUk=
+github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
 go.opentelemetry.io/otel v1.7.0 h1:Z2lA3Tdch0iDcrhJXDIlC94XE+bxok1F9B+4Lz/lGsM=
 go.opentelemetry.io/otel v1.7.0/go.mod h1:5BdUoMIz5WEs0vt0CUEMtSSaTSHBBVwrhnz7+nrD5xk=
 go.opentelemetry.io/otel/exporters/jaeger v1.7.0 h1:wXgjiRldljksZkZrldGVe6XrG9u3kYDyQmkZwmm5dI0=

pkg/trace/span.go

@@ -14,6 +14,10 @@ type Span interface {
 	// method has been called.
 	End()
 
+	// IsRecording returns the recording state of the Span. It will return
+	// true if the Span is active and events can be recorded.
+	IsRecording() bool
+
 	// RecordError will record err as an exception span event for this span. An
 	// additional call to SetStatus is required if the Status of the Span should
 	// be set to Error, as this method does not change the Span status. If this
@@ -47,6 +51,10 @@ func (s otelSpan) End() {
 	s.spanOtel.End()
 }
 
+func (s otelSpan) IsRecording() bool {
+	return s.spanOtel.IsRecording()
+}
+
 func (s otelSpan) RecordError(err error) {
 	s.spanOtel.RecordError(err)
 }

pkg/trace/tracer-provider.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"fmt"
 	"io"
+	"os"
 
 	"go.opentelemetry.io/otel"
 )
@@ -89,3 +90,48 @@ func GlobalTracer(tracerName string) Tracer {
 	tracer := otel.Tracer(tracerName)
 	return NewOtelTracer(tracer)
 }
+
+// TypeFromAnnotationsOrEnv return a TracerProviderType and optional Jaeger
+// collector URL based on a map of annotation key-value pairs and environment
+// variable configuration. Annotations are prioritized over envvars.
+func TypeFromAnnotationsOrEnv(annots map[string]string) (TracerProviderType, string) {
+	return typeFromAnnotationsOrCustomEnv(annots, os.Getenv)
+}
+
+func typeFromAnnotationsOrCustomEnv(annots map[string]string, getEnv func(string) string) (TracerProviderType, string) {
+	providerType, jaegerUrl := TypeFromAnnotations(annots)
+	if providerType == NoopProviderType {
+		providerType, jaegerUrl = typeFromCustomEnv(getEnv)
+	}
+	return providerType, jaegerUrl
+}
+
+// TypeFromEnv returns a TracerProviderType and optional Jaeger collector URL
+// based on environment variable configuration.
+func TypeFromEnv() (TracerProviderType, string) {
+	return typeFromCustomEnv(os.Getenv)
+}
+
+func typeFromCustomEnv(getEnv func(string) string) (TracerProviderType, string) {
+	jaegerUrl := getEnv("JAEGER_COLLECTOR_URL")
+	if jaegerUrl != "" {
+		return JaegerProviderType, jaegerUrl
+	}
+	if getEnv("LOG_TRACES") == "true" {
+		return ConsoleProviderType, ""
+	}
+	return NoopProviderType, ""
+}
+
+// TypeFromAnnotations returns a TracerProviderType and optional Jaeger
+// collector URL based on a map of annotations key-value pairs.
+func TypeFromAnnotations(annots map[string]string) (TracerProviderType, string) {
+	jaegerUrl := annots["conjur.org/jaeger-collector-url"]
+	if jaegerUrl != "" {
+		return JaegerProviderType, jaegerUrl
+	}
+	if annots["conjur.org/log-traces"] == "true" {
+		return ConsoleProviderType, ""
+	}
+	return NoopProviderType, ""
+}

pkg/trace/tracer-provider_test.go

@@ -0,0 +1,167 @@
+package trace
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestTypeFromAnnotationsOrEnv(t *testing.T) {
+	testCases := []struct {
+		description string
+		env         map[string]string
+		annots      map[string]string
+		assertions  func(*testing.T, TracerProviderType, string)
+	}{
+		{
+			description: "annotations override envvars",
+			env: map[string]string{
+				"JAEGER_COLLECTOR_URL": "http://collector",
+			},
+			annots: map[string]string{
+				"conjur.org/log-traces": "true",
+			},
+			assertions: func(t *testing.T, tpt TracerProviderType, s string) {
+				assert.Empty(t, s)
+				assert.Equal(t, ConsoleProviderType, int(tpt))
+			},
+		},
+		{
+			description: "envvars used if annotations absent",
+			env: map[string]string{
+				"JAEGER_COLLECTOR_URL": "http://collector",
+			},
+			annots: map[string]string{},
+			assertions: func(t *testing.T, tpt TracerProviderType, s string) {
+				assert.Equal(t, "http://collector", s)
+				assert.Equal(t, JaegerProviderType, int(tpt))
+			},
+		},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.description, func(t *testing.T) {
+			pType, collectorUrl := typeFromAnnotationsOrCustomEnv(
+				tc.annots,
+				func(key string) string {
+					return tc.env[key]
+				},
+			)
+			tc.assertions(t, pType, collectorUrl)
+		})
+	}
+}
+
+func TestTypeFromEnv(t *testing.T) {
+	testCases := []struct {
+		description string
+		env         map[string]string
+		assertions  func(*testing.T, TracerProviderType, string)
+	}{
+		{
+			description: "noop type",
+			env:         map[string]string{},
+			assertions: func(t *testing.T, tpt TracerProviderType, s string) {
+				assert.Empty(t, s)
+				assert.Equal(t, NoopProviderType, int(tpt))
+			},
+		},
+		{
+			description: "console type",
+			env: map[string]string{
+				"LOG_TRACES": "true",
+			},
+			assertions: func(t *testing.T, tpt TracerProviderType, s string) {
+				assert.Empty(t, s)
+				assert.Equal(t, ConsoleProviderType, int(tpt))
+			},
+		},
+		{
+			description: "jaeger type",
+			env: map[string]string{
+				"JAEGER_COLLECTOR_URL": "http://collector",
+			},
+			assertions: func(t *testing.T, tpt TracerProviderType, s string) {
+				assert.Equal(t, "http://collector", s)
+				assert.Equal(t, JaegerProviderType, int(tpt))
+			},
+		},
+		{
+			description: "jaeger type overrides console type",
+			env: map[string]string{
+				"LOG_TRACES":           "true",
+				"JAEGER_COLLECTOR_URL": "http://collector",
+			},
+			assertions: func(t *testing.T, tpt TracerProviderType, s string) {
+				assert.Equal(t, "http://collector", s)
+				assert.Equal(t, JaegerProviderType, int(tpt))
+			},
+		},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.description, func(t *testing.T) {
+			pType, collectorUrl := typeFromCustomEnv(
+				func(key string) string {
+					return tc.env[key]
+				},
+			)
+			tc.assertions(t, pType, collectorUrl)
+		})
+	}
+}
+
+func TestTypeFromAnnotations(t *testing.T) {
+	testCases := []struct {
+		description string
+		annots      map[string]string
+		assertions  func(*testing.T, TracerProviderType, string)
+	}{
+		{
+			description: "noop type",
+			annots:      map[string]string{},
+			assertions: func(t *testing.T, tpt TracerProviderType, s string) {
+				assert.Empty(t, s)
+				assert.Equal(t, NoopProviderType, int(tpt))
+			},
+		},
+		{
+			description: "console type",
+			annots: map[string]string{
+				"conjur.org/log-traces": "true",
+			},
+			assertions: func(t *testing.T, tpt TracerProviderType, s string) {
+				assert.Empty(t, s)
+				assert.Equal(t, ConsoleProviderType, int(tpt))
+			},
+		},
+		{
+			description: "jaeger type",
+			annots: map[string]string{
+				"conjur.org/jaeger-collector-url": "http://collector",
+			},
+			assertions: func(t *testing.T, tpt TracerProviderType, s string) {
+				assert.Equal(t, "http://collector", s)
+				assert.Equal(t, JaegerProviderType, int(tpt))
+			},
+		},
+		{
+			description: "jaeger type overrides console type",
+			annots: map[string]string{
+				"conjur.org/log-traces":           "true",
+				"conjur.org/jaeger-collector-url": "http://collector",
+			},
+			assertions: func(t *testing.T, tpt TracerProviderType, s string) {
+				assert.Equal(t, "http://collector", s)
+				assert.Equal(t, JaegerProviderType, int(tpt))
+			},
+		},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.description, func(t *testing.T) {
+			pType, collectorUrl := TypeFromAnnotations(tc.annots)
+			tc.assertions(t, pType, collectorUrl)
+		})
+	}
+}

pkg/trace/tracer.go

@@ -31,3 +31,43 @@ func (t otelTracer) Start(ctx context.Context, spanName string) (context.Context
 	ctx, spanOtel := t.tracerOtel.Start(ctx, spanName)
 	return ctx, newOtelSpan(spanOtel)
 }
+
+// Create returns a Context, Tracer and cleanup function based on the provided
+// TracerProviderType and TracerProviderConfig.
+func Create(
+	providerType TracerProviderType,
+	config TracerProviderConfig,
+) (context.Context, Tracer, func(context.Context), error) {
+	return create(
+		providerType,
+		config,
+		NewTracerProvider,
+	)
+}
+
+func create(
+	providerType TracerProviderType,
+	config TracerProviderConfig,
+	factory func(TracerProviderType, bool, TracerProviderConfig) (TracerProvider, error),
+) (context.Context, Tracer, func(context.Context), error) {
+	tp, err := factory(
+		providerType,
+		SetGlobalProvider,
+		config,
+	)
+	if err != nil {
+		return nil, nil, nil, err
+	}
+
+	ctx, cancel := context.WithCancel(context.Background())
+	tracer := tp.Tracer(config.TracerName)
+	ctx, span := tracer.Start(ctx, "main")
+
+	cleanupFunc := func(ctx context.Context) {
+		span.End()
+		tp.Shutdown(ctx)
+		cancel()
+	}
+
+	return ctx, tracer, cleanupFunc, err
+}