Introducing the instana.Collector (#414)

* Introduced SensorLogger interface with methods: Tracer() ot.Tracer, Logger() LeveledLogger, SetLogger(l LeveledLogger)
* Introduced TracerLogger interface. It embeds instana.Tracer instana.LeveledLogger and instana.SensorLogger
* instana.Tracer interface added StartSpanWithOptions method to match tracerS
* Introduced instana.Collector that implements TracerLogger
* instana.Sensor now implements TracerLogger
* New Option Recorder

Author: willianpc

adapters.go

@@ -14,6 +14,14 @@ import (
 	otlog "github.com/opentracing/opentracing-go/log"
 )
 
+var _ TracerLogger = (*Sensor)(nil)
+
+type SensorLogger interface {
+	Tracer() ot.Tracer
+	Logger() LeveledLogger
+	SetLogger(l LeveledLogger)
+}
+
 // SpanSensitiveFunc is a function executed within a span context
 //
 // Deprecated: use instana.ContextWithSpan() and instana.SpanFromContext() to inject and retrieve spans
@@ -32,6 +40,8 @@ type Tracer interface {
 	Options() TracerOptions
 	// Flush sends all finished spans to the agent
 	Flush(context.Context) error
+	// StartSpanWithOptions starts a span with the given options and return the span reference
+	StartSpanWithOptions(string, ot.StartSpanOptions) ot.Span
 }
 
 // Sensor is used to inject tracing information into requests
@@ -40,7 +50,7 @@ type Sensor struct {
 	logger LeveledLogger
 }
 
-// NewSensor creates a new instana.Sensor
+// NewSensor creates a new [Sensor]
 func NewSensor(serviceName string) *Sensor {
 	return NewSensorWithTracer(NewTracerWithOptions(
 		&Options{
@@ -49,7 +59,7 @@ func NewSensor(serviceName string) *Sensor {
 	))
 }
 
-// NewSensorWithTracer returns a new instana.Sensor that uses provided tracer to report spans
+// NewSensorWithTracer returns a new [Sensor] that uses provided tracer to report spans
 func NewSensorWithTracer(tracer ot.Tracer) *Sensor {
 	return &Sensor{
 		tracer: tracer,
@@ -168,3 +178,88 @@ func (s *Sensor) WithTracingContext(name string, w http.ResponseWriter, req *htt
 		f(span, ContextWithSpan(req.Context(), span))
 	})
 }
+
+// Compliance with TracerLogger
+
+// Extract() returns a SpanContext instance given `format` and `carrier`. It matches [opentracing.Tracer.Extract].
+func (s *Sensor) Extract(format interface{}, carrier interface{}) (ot.SpanContext, error) {
+	return s.tracer.Extract(format, carrier)
+}
+
+// Inject() takes the `sm` SpanContext instance and injects it for
+// propagation within `carrier`. The actual type of `carrier` depends on
+// the value of `format`. It matches [opentracing.Tracer.Inject]
+func (s *Sensor) Inject(sm ot.SpanContext, format interface{}, carrier interface{}) error {
+	return s.tracer.Inject(sm, format, carrier)
+}
+
+// Create, start, and return a new Span with the given `operationName` and
+// incorporate the given StartSpanOption `opts`. (Note that `opts` borrows
+// from the "functional options" pattern, per
+// http://dave.cheney.net/2014/10/17/functional-options-for-friendly-apis)
+//
+// It matches [opentracing.Tracer.StartSpan].
+func (s *Sensor) StartSpan(operationName string, opts ...ot.StartSpanOption) ot.Span {
+	return s.tracer.StartSpan(operationName, opts...)
+}
+
+// StartSpanWithOptions creates and starts a span by setting Instana relevant data within the span.
+// It matches [instana.Tracer.StartSpanWithOptions].
+func (s *Sensor) StartSpanWithOptions(operationName string, opts ot.StartSpanOptions) ot.Span {
+	if t, ok := s.tracer.(Tracer); ok {
+		return t.StartSpanWithOptions(operationName, opts)
+	}
+
+	s.logger.Warn("Sensor.StartSpanWithOptions() not implemented by interface: ", s.tracer, " - returning nil")
+
+	return nil
+}
+
+// Options gets the current tracer options
+// It matches [instana.Tracer.Options].
+func (s *Sensor) Options() TracerOptions {
+	if t, ok := s.tracer.(Tracer); ok {
+		return t.Options()
+	}
+
+	s.logger.Warn("Sensor.Options() not implemented by interface: ", s.tracer, " - returning DefaultTracerOptions()")
+
+	return DefaultTracerOptions()
+}
+
+// Flush sends all finished spans to the agent
+// It matches [instana.Tracer.Flush].
+func (s *Sensor) Flush(ctx context.Context) error {
+	if t, ok := s.tracer.(Tracer); ok {
+		return t.Flush(ctx)
+	}
+
+	s.logger.Warn("Sensor.Flush() not implemented by interface: ", s.tracer, " - returning nil")
+
+	return nil
+}
+
+// Debug logs a debug message by calling [LeveledLogger] underneath
+func (s *Sensor) Debug(v ...interface{}) {
+	s.logger.Debug(v...)
+}
+
+// Info logs an info message by calling [LeveledLogger] underneath
+func (s *Sensor) Info(v ...interface{}) {
+	s.logger.Info(v...)
+}
+
+// Warn logs a warning message by calling [LeveledLogger] underneath
+func (s *Sensor) Warn(v ...interface{}) {
+	s.logger.Warn(v...)
+}
+
+// Error logs a error message by calling [LeveledLogger] underneath
+func (s *Sensor) Error(v ...interface{}) {
+	s.logger.Error(v...)
+}
+
+// LegacySensor returns a reference to [Sensor].
+func (s *Sensor) LegacySensor() *Sensor {
+	return s
+}

agent_communicator.go

@@ -199,7 +199,7 @@ func (a *agentCommunicator) sendDataToAgent(suffix string, data interface{}) err
 	if resp != nil {
 		respCode := resp.StatusCode
 		if respCode < 200 || respCode >= 300 {
-			a.l.Debug("Sending data to agent: response code: ", resp.StatusCode, "-", resp.Status)
+			a.l.Debug("Sending data to agent: response code: ", resp.StatusCode, "-", resp.Status, "; ", url)
 		}
 
 		io.CopyN(ioutil.Discard, resp.Body, 256<<10)

azure_agent_test.go

@@ -106,7 +106,7 @@ func TestAzureAgent_SpanDetails(t *testing.T) {
           "functionname": "testfunction",
           "triggername": "HTTP",
           "runtime": "custom"
-        } }`, string(spans[0]["data"]))
+        }, "service": "instana.test"}`, string(spans[0]["data"]))
 }
 
 func setupAzureFunctionEnv() func() {

collector.go

@@ -0,0 +1,131 @@
+// (c) Copyright IBM Corp. 2023
+
+package instana
+
+import (
+	"context"
+
+	ot "github.com/opentracing/opentracing-go"
+)
+
+// TracerLogger represents the Instana Go collector and is composed by a tracer, a logger and a reference to the legacy sensor.
+type TracerLogger interface {
+	Tracer
+	LeveledLogger
+	LegacySensor() *Sensor
+	SensorLogger
+}
+
+// Collector is used to inject tracing information into requests
+type Collector struct {
+	t Tracer
+	LeveledLogger
+	*Sensor
+}
+
+var _ TracerLogger = (*Collector)(nil)
+
+// InitCollector creates a new [Collector]
+func InitCollector(opts *Options) TracerLogger {
+
+	// if instana.C is already an instance of Collector, we just return
+	if _, ok := C.(*Collector); ok {
+		C.Warn("InitCollector was previously called. instana.C is reused")
+		return C
+	}
+
+	if opts == nil {
+		opts = &Options{
+			Recorder: NewRecorder(),
+		}
+	}
+
+	if opts.Recorder == nil {
+		opts.Recorder = NewRecorder()
+	}
+
+	StartMetrics(opts)
+
+	tracer := &tracerS{
+		recorder: opts.Recorder,
+	}
+
+	C = &Collector{
+		t:             tracer,
+		LeveledLogger: defaultLogger,
+		Sensor:        NewSensorWithTracer(tracer),
+	}
+
+	return C
+}
+
+// Extract() returns a SpanContext instance given `format` and `carrier`. It matches [opentracing.Tracer.Extract].
+func (c *Collector) Extract(format interface{}, carrier interface{}) (ot.SpanContext, error) {
+	return c.t.Extract(format, carrier)
+}
+
+// Inject() takes the `sm` SpanContext instance and injects it for
+// propagation within `carrier`. The actual type of `carrier` depends on
+// the value of `format`. It matches [opentracing.Tracer.Inject]
+func (c *Collector) Inject(sm ot.SpanContext, format interface{}, carrier interface{}) error {
+	return c.t.Inject(sm, format, carrier)
+}
+
+// Create, start, and return a new Span with the given `operationName` and
+// incorporate the given StartSpanOption `opts`. (Note that `opts` borrows
+// from the "functional options" pattern, per
+// http://dave.cheney.net/2014/10/17/functional-options-for-friendly-apis)
+//
+// It matches [opentracing.Tracer.StartSpan].
+func (c *Collector) StartSpan(operationName string, opts ...ot.StartSpanOption) ot.Span {
+	return c.t.StartSpan(operationName, opts...)
+}
+
+// StartSpanWithOptions creates and starts a span by setting Instana relevant data within the span.
+// It matches [instana.Tracer.StartSpanWithOptions].
+func (c *Collector) StartSpanWithOptions(operationName string, opts ot.StartSpanOptions) ot.Span {
+	return c.t.StartSpanWithOptions(operationName, opts)
+}
+
+// Options gets the current tracer options
+// It matches [instana.Tracer.Options].
+func (c *Collector) Options() TracerOptions {
+	return c.t.Options()
+}
+
+// Flush sends all finished spans to the agent
+// It matches [instana.Tracer.Flush].
+func (c *Collector) Flush(ctx context.Context) error {
+	return c.t.Flush(ctx)
+}
+
+// Debug logs a debug message by calling [LeveledLogger] underneath
+func (c *Collector) Debug(v ...interface{}) {
+	c.LeveledLogger.Debug(v...)
+}
+
+// Info logs an info message by calling [LeveledLogger] underneath
+func (c *Collector) Info(v ...interface{}) {
+	c.LeveledLogger.Info(v...)
+}
+
+// Warn logs a warning message by calling [LeveledLogger] underneath
+func (c *Collector) Warn(v ...interface{}) {
+	c.LeveledLogger.Warn(v...)
+}
+
+// Error logs a error message by calling [LeveledLogger] underneath
+func (c *Collector) Error(v ...interface{}) {
+	c.LeveledLogger.Error(v...)
+}
+
+// LegacySensor returns a reference to [Sensor] that can be used for old instrumentations that still require it.
+//
+// Example:
+//
+//	// Instrumenting HTTP incoming calls
+//	c := instana.InitCollector("my-service")
+//	http.HandleFunc("/", instana.TracingNamedHandlerFunc(c.LegacySensor(), "", "/{name}", handle))
+func (c *Collector) LegacySensor() *Sensor {
+	return c.Sensor
+}

collector_noop.go

@@ -0,0 +1,89 @@
+// (c) Copyright IBM Corp. 2023
+
+package instana
+
+import (
+	"context"
+	"errors"
+
+	ot "github.com/opentracing/opentracing-go"
+)
+
+var (
+	_                   TracerLogger = (*noopCollector)(nil)
+	noopCollectorErrMsg string       = "collector not initialized. make sure to initialize the Collector. eg: instana.InitCollector"
+	noopCollectorErr    error        = errors.New(noopCollectorErrMsg)
+)
+
+type noopCollector struct {
+	l LeveledLogger
+}
+
+func newNoopCollector() TracerLogger {
+	c := &noopCollector{
+		l: defaultLogger,
+	}
+	return c
+}
+
+func (c *noopCollector) Extract(format interface{}, carrier interface{}) (ot.SpanContext, error) {
+	c.l.Error(noopCollectorErrMsg)
+	return nil, noopCollectorErr
+}
+
+func (c *noopCollector) Inject(sm ot.SpanContext, format interface{}, carrier interface{}) error {
+	c.l.Error(noopCollectorErrMsg)
+	return noopCollectorErr
+}
+
+func (c *noopCollector) StartSpan(operationName string, opts ...ot.StartSpanOption) ot.Span {
+	c.l.Error(noopCollectorErrMsg)
+	return nil
+}
+
+func (c *noopCollector) StartSpanWithOptions(operationName string, opts ot.StartSpanOptions) ot.Span {
+	c.l.Error(noopCollectorErrMsg)
+	return nil
+}
+
+func (c *noopCollector) Options() TracerOptions {
+	return TracerOptions{}
+}
+
+func (c *noopCollector) Flush(ctx context.Context) error {
+	return noopCollectorErr
+}
+
+func (c *noopCollector) Debug(v ...interface{}) {
+	c.l.Error(noopCollectorErrMsg)
+}
+
+func (c *noopCollector) Info(v ...interface{}) {
+	c.l.Error(noopCollectorErrMsg)
+}
+
+func (c *noopCollector) Warn(v ...interface{}) {
+	c.l.Error(noopCollectorErrMsg)
+}
+
+func (c *noopCollector) Error(v ...interface{}) {
+	c.l.Error(noopCollectorErrMsg)
+}
+
+func (c *noopCollector) LegacySensor() *Sensor {
+	c.l.Error(noopCollectorErrMsg)
+	return nil
+}
+
+func (c *noopCollector) Tracer() ot.Tracer {
+	c.l.Error(noopCollectorErrMsg)
+	return nil
+}
+
+func (c *noopCollector) Logger() LeveledLogger {
+	c.l.Error(noopCollectorErrMsg)
+	return nil
+}
+
+// SetLogger sets the logger
+func (c *noopCollector) SetLogger(l LeveledLogger) {}