feat: add ion.Attr type alias for OTel attributes

- Add attrs.go with Attr type alias for attribute.KeyValue
- Update Span interface to use ion.Attr in public API
- Document OTel integration philosophy in README

This makes Ion's API appear self-contained while still using
standard OTel types underneath. Users continue to import
go.opentelemetry.io/otel/attribute for constructors.

Author: i-naman

README.md

@@ -326,6 +326,22 @@ func ProcessOrder(ctx context.Context, orderID string) error {
 }
 ```
 
+> **📘 OTel Types in Ion**
+> 
+> Ion uses OpenTelemetry for tracing and metrics. The `ion.Attr` type (visible in Ion's API signatures) is an alias for `attribute.KeyValue`.
+> 
+> To create attributes, import the OTel package directly:
+> ```go
+> import "go.opentelemetry.io/otel/attribute"
+> 
+> span.SetAttributes(
+>     attribute.String("order.id", orderID),
+>     attribute.Int64("retry.count", 3),
+> )
+> ```
+> 
+> This is intentional: **Ion abstracts provider lifecycle, not the instrumentation API.** Users benefit from learning the standard OTel API.
+
 ---
 
 ## Common Configurations

attrs.go

@@ -0,0 +1,38 @@
+// Package ion provides unified observability for JupiterMeta applications.
+//
+// This file defines type aliases for OpenTelemetry attribute types used in
+// tracing and metrics. These aliases allow Ion's API to appear self-contained
+// in documentation while still using the standard OTel types underneath.
+package ion
+
+import "go.opentelemetry.io/otel/attribute"
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Attribute Types (for Tracing and Metrics)
+// ─────────────────────────────────────────────────────────────────────────────
+//
+// Attr is a key-value pair used for trace span attributes and metric dimensions.
+// This is an alias for the OpenTelemetry attribute.KeyValue type.
+//
+// Create attributes using the standard OTel constructors:
+//
+//	import "go.opentelemetry.io/otel/attribute"
+//
+//	span.SetAttributes(
+//	    attribute.String("order.id", orderID),
+//	    attribute.Int64("retry.count", 3),
+//	)
+//
+// Or for metrics:
+//
+//	counter.Add(ctx, 1, metric.WithAttributes(
+//	    attribute.String("shard_id", "3"),
+//	))
+//
+// Note: Ion intentionally does NOT wrap attribute constructors. This ensures
+// users learn the standard OpenTelemetry API, which is an industry skill.
+type Attr = attribute.KeyValue
+
+// AttrKey is a type alias for attribute keys.
+// Use attribute.Key("mykey").String("value") for advanced patterns.
+type AttrKey = attribute.Key

tracer.go

@@ -4,7 +4,6 @@ import (
 	"context"
 
 	"go.opentelemetry.io/otel"
-	"go.opentelemetry.io/otel/attribute"
 	"go.opentelemetry.io/otel/codes"
 	"go.opentelemetry.io/otel/trace"
 )
@@ -32,9 +31,11 @@ type Span interface {
 	// RecordError records an error as an event.
 	RecordError(err error)
 	// SetAttributes sets attributes on the span.
-	SetAttributes(attrs ...attribute.KeyValue)
+	// Use attribute.String(), attribute.Int64(), etc. to create Attr values.
+	SetAttributes(attrs ...Attr)
 	// AddEvent adds an event to the span.
-	AddEvent(name string, attrs ...attribute.KeyValue)
+	// Use attribute.String(), attribute.Int64(), etc. to create Attr values.
+	AddEvent(name string, attrs ...Attr)
 }
 
 // SpanOption configures span creation.
@@ -44,7 +45,7 @@ type SpanOption interface {
 
 type spanOptions struct {
 	kind       trace.SpanKind
-	attributes []attribute.KeyValue
+	attributes []Attr
 	links      []trace.Link
 	otelOpts   []trace.SpanStartOption
 }
@@ -56,12 +57,13 @@ func (k kindOption) apply(o *spanOptions) { o.kind = trace.SpanKind(k) }
 // WithSpanKind sets the span kind (client, server, etc).
 func WithSpanKind(kind trace.SpanKind) SpanOption { return kindOption(kind) }
 
-type attrOption []attribute.KeyValue
+type attrOption []Attr
 
 func (a attrOption) apply(o *spanOptions) { o.attributes = append(o.attributes, a...) }
 
 // WithAttributes adds attributes to the span.
-func WithAttributes(attrs ...attribute.KeyValue) SpanOption { return attrOption(attrs) }
+// Use attribute.String(), attribute.Int64(), etc. to create Attr values.
+func WithAttributes(attrs ...Attr) SpanOption { return attrOption(attrs) }
 
 type linkOption []trace.Link
 
@@ -113,11 +115,11 @@ type otelSpan struct {
 	span trace.Span
 }
 
-func (s *otelSpan) End()                                      { s.span.End() }
-func (s *otelSpan) SetStatus(code codes.Code, desc string)    { s.span.SetStatus(code, desc) }
-func (s *otelSpan) RecordError(err error)                     { s.span.RecordError(err) }
-func (s *otelSpan) SetAttributes(attrs ...attribute.KeyValue) { s.span.SetAttributes(attrs...) }
-func (s *otelSpan) AddEvent(name string, attrs ...attribute.KeyValue) {
+func (s *otelSpan) End()                                   { s.span.End() }
+func (s *otelSpan) SetStatus(code codes.Code, desc string) { s.span.SetStatus(code, desc) }
+func (s *otelSpan) RecordError(err error)                  { s.span.RecordError(err) }
+func (s *otelSpan) SetAttributes(attrs ...Attr)            { s.span.SetAttributes(attrs...) }
+func (s *otelSpan) AddEvent(name string, attrs ...Attr) {
 	s.span.AddEvent(name, trace.WithAttributes(attrs...))
 }
 
@@ -131,8 +133,8 @@ func (noopTracer) Start(ctx context.Context, _ string, _ ...SpanOption) (context
 
 type noopSpan struct{}
 
-func (noopSpan) End()                                   {}
-func (noopSpan) SetStatus(codes.Code, string)           {}
-func (noopSpan) RecordError(error)                      {}
-func (noopSpan) SetAttributes(...attribute.KeyValue)    {}
-func (noopSpan) AddEvent(string, ...attribute.KeyValue) {}
+func (noopSpan) End()                         {}
+func (noopSpan) SetStatus(codes.Code, string) {}
+func (noopSpan) RecordError(error)            {}
+func (noopSpan) SetAttributes(...Attr)        {}
+func (noopSpan) AddEvent(string, ...Attr)     {}