observability

type Collector interface {
	// RecordDuration records the duration of an operation.
	// Use this to track performance metrics like search latency.
	//
	// Parameters:
	//   - operation: Name of the operation (e.g., "search", "index")
	//   - duration: How long the operation took
	//   - labels: Additional labels for filtering and grouping
	RecordDuration(operation string, duration time.Duration, labels map[string]string)

	// RecordCount records the count of an operation.
	// Use this to track operation frequency and success rates.
	//
	// Parameters:
	//   - operation: Name of the operation
	//   - status: Status of the operation (e.g., "success", "failure")
	//   - labels: Additional labels for filtering and grouping
	RecordCount(operation string, status string, labels map[string]string)

	// RecordValue records a custom metric value.
	// Use this for domain-specific metrics that don't fit other categories.
	//
	// Parameters:
	//   - metricName: Name of the metric
	//   - value: The metric value
	//   - labels: Additional labels for filtering and grouping
	RecordValue(metricName string, value float64, labels map[string]string)
}

type NoopMetrics struct{}

type PrometheusMetrics struct {
	// contains filtered or unexported fields
}

type Span interface {
	// SetTag sets a key-value tag on the span.
	// Tags are used to filter and query traces.
	//
	// Parameters:
	//   - key: Tag name
	//   - value: Tag value (can be any type)
	//
	// Example:
	//
	//	span.SetTag("user_id", 123)
	//	span.SetTag("operation", "search")
	SetTag(key string, value interface{})

	// LogEvent logs an event within the span.
	// Events represent point-in-time occurrences during the span's lifetime.
	//
	// Parameters:
	//   - eventName: Name of the event
	//   - fields: Additional structured data about the event
	//
	// Example:
	//
	//	span.LogEvent("cache_hit", map[string]interface{}{
	//	    "key": "query_123",
	//	    "latency_ms": 5,
	//	})
	LogEvent(eventName string, fields map[string]interface{})

	// End completes the span.
	// This should be called when the operation is finished.
	// After End() is called, the span should not be modified.
	End()
}

type Tracer interface {
	// StartSpan starts a new span within a trace.
	// A span represents a unit of work in the system.
	//
	// Parameters:
	//   - ctx: Parent context (may contain existing trace information)
	//   - operationName: Name of the operation being traced
	//
	// Returns:
	//   - context.Context: New context containing the span
	//   - Span: The created span that should be ended when complete
	//
	// Example:
	//
	//	ctx, span := tracer.StartSpan(ctx, "vector_search")
	//	defer span.End()
	//	// ... perform search ...
	StartSpan(ctx context.Context, operationName string) (context.Context, Span)

	// GetSpan retrieves the current span from context.
	// Returns a no-op span if no span is found in the context.
	//
	// Parameters:
	//   - ctx: Context that may contain span information
	//
	// Returns:
	//   - Span: The current span or a no-op span
	GetSpan(ctx context.Context) Span
}