feat: add WithLinks and WithOTELOptions to Tracer

Author: i-naman

README.md

@@ -427,7 +427,7 @@ go func(parentCtx context.Context) {
     link := trace.LinkFromContext(parentCtx) 
 
     // 3. Start a new Root Span with the link
-    ctx, span := tracer.Start(newCtx, "AsyncJob", trace.WithLinks(link))
+    ctx, span := tracer.Start(newCtx, "AsyncJob", ion.WithLinks(link))
     defer span.End()
 
     // Now you have a safe, independent span correlated to the original request

docs/USER_GUIDE.md

@@ -133,7 +133,7 @@ func (s *Service) AsyncEmail(reqCtx context.Context) {
     go func() {
         // 2. Start a FRESH root trace
         // This ensures the email trace is complete even if request finishes.
-        ctx, span := s.tracer.Start(context.Background(), "SendEmail", trace.WithLinks(link))
+        ctx, span := s.tracer.Start(context.Background(), "SendEmail", ion.WithLinks(link))
         defer span.End()
         
         // 3. Work...
@@ -254,8 +254,8 @@ func (s *Syncer) Sync(ctx context.Context) {
         tracer := s.tracer
         // Create a fresh context for the batch
         spanCtx, span := tracer.Start(context.Background(), "ApplyBatch", 
-            trace.WithLinks(trace.LinkFromContext(ctx)), // Link to main sync job
-            trace.WithAttributes(attribute.Int("batch_id", batch.ID)),
+            ion.WithLinks(trace.LinkFromContext(ctx)), // Link to main sync job
+            ion.WithAttributes(attribute.Int("batch_id", batch.ID)),
         )
 
         if err := s.apply(spanCtx, batch); err != nil {

tracer.go

@@ -37,6 +37,8 @@ type SpanOption interface {
 type spanOptions struct {
 	kind       trace.SpanKind
 	attributes []attribute.KeyValue
+	links      []trace.Link
+	otelOpts   []trace.SpanStartOption
 }
 
 type kindOption trace.SpanKind
@@ -53,6 +55,21 @@ func (a attrOption) apply(o *spanOptions) { o.attributes = append(o.attributes,
 // WithAttributes adds attributes to the span.
 func WithAttributes(attrs ...attribute.KeyValue) SpanOption { return attrOption(attrs) }
 
+type linkOption []trace.Link
+
+func (l linkOption) apply(o *spanOptions) { o.links = append(o.links, l...) }
+
+// WithLinks adds links to the span.
+func WithLinks(links ...trace.Link) SpanOption { return linkOption(links) }
+
+type otelOption []trace.SpanStartOption
+
+func (t otelOption) apply(o *spanOptions) { o.otelOpts = append(o.otelOpts, t...) }
+
+// WithOTELOptions allows passing raw OpenTelemetry options directly.
+// This is an escape hatch for advanced features not yet wrapped by Ion.
+func WithOTELOptions(opts ...trace.SpanStartOption) SpanOption { return otelOption(opts) }
+
 // --- OTEL Tracer Implementation ---
 
 type otelTracer struct {
@@ -73,6 +90,12 @@ func (t *otelTracer) Start(ctx context.Context, spanName string, opts ...SpanOpt
 	if len(o.attributes) > 0 {
 		traceOpts = append(traceOpts, trace.WithAttributes(o.attributes...))
 	}
+	if len(o.links) > 0 {
+		traceOpts = append(traceOpts, trace.WithLinks(o.links...))
+	}
+	if len(o.otelOpts) > 0 {
+		traceOpts = append(traceOpts, o.otelOpts...)
+	}
 
 	ctx, span := t.tracer.Start(ctx, spanName, traceOpts...)
 	return ctx, &otelSpan{span: span}

tracer_test.go

@@ -0,0 +1,39 @@
+package ion
+
+import (
+	"testing"
+
+	"go.opentelemetry.io/otel/trace"
+)
+
+func TestTracer_WithLinks(t *testing.T) {
+	// calling WithLinks should not panic
+	opts := WithLinks(trace.Link{
+		SpanContext: trace.SpanContext{},
+	})
+
+	so := &spanOptions{}
+	opts.apply(so)
+
+	if len(so.links) != 1 {
+		t.Errorf("Expected 1 link, got %d", len(so.links))
+	}
+}
+
+func TestTracer_WithOTELOptions(t *testing.T) {
+	// calling WithOTELOptions should not panic
+	// We can't easily inspect the internal otel options without reflection or a mock,
+	// but we can ensure it appends to our internal slice.
+
+	// Create a dummy option
+	dummyOpt := trace.WithAttributes()
+
+	opts := WithOTELOptions(dummyOpt)
+
+	so := &spanOptions{}
+	opts.apply(so)
+
+	if len(so.otelOpts) != 1 {
+		t.Errorf("Expected 1 otel option, got %d", len(so.otelOpts))
+	}
+}