o11y

type Baggage map[string]string

type ClosableMetricsProvider interface {
	MetricsProvider
	io.Closer
}

type Helpers interface {
	// ExtractPropagation pulls propagation information out of the context
	ExtractPropagation(ctx context.Context) PropagationContext
	// InjectPropagation adds propagation header fields into the returned root span returning
	// the context carrying that span
	InjectPropagation(context.Context, PropagationContext) (context.Context, Span)
	// TraceIDs return standard o11y ids
	TraceIDs(ctx context.Context) (traceID, parentID string)
}

type Metric struct {
	Type MetricType
	// Name is the metric name that will be emitted
	Name string
	// Field is the span field to use as the metric's value
	Field string
	// FixedTag is an optional tag added at Metric definition time
	FixedTag *Tag
	// TagFields are additional span fields to use as metric tags
	TagFields []string
}

type MetricType string

type MetricsProvider interface {
	// Histogram aggregates values agent side for a period of time.
	// This is similar to TimeInMilliseconds, but not limited to timing data
	Histogram(name string, value float64, tags []string, rate float64) error
	// TimeInMilliseconds measures timing data only. For example, how long a network call takes
	TimeInMilliseconds(name string, value float64, tags []string, rate float64) error
	// Gauge measures the value of a metric at a particular time.
	Gauge(name string, value float64, tags []string, rate float64) error
	// Count sends an individual value in time.
	Count(name string, value int64, tags []string, rate float64) error
}

type Pair struct {
	Key   string
	Value interface{}
}

type PropagationContext struct {
	// Parent contains single string serialisation of just the trace parent fields
	Parent string
	// Headers contains the map of all context propagation headers
	Headers map[string]string
}

type Provider interface {
	// AddGlobalField adds data which should apply to every span in the application
	//
	// eg. version, service, k8s_replicaset
	AddGlobalField(key string, val interface{})

	// StartSpan begins a new span that'll represent a unit of work
	//
	// `name` should be a short human readable identifier of the work.
	// It can and should include some details to distinguish it from other
	// similar spans - like the URL or the DB query name.
	//
	// The caller is responsible for calling End(), usually via defer:
	//
	//   ctx, span := o11y.StartSpan(ctx, "GET /help")
	//   defer span.End()
	StartSpan(ctx context.Context, name string) (context.Context, Span)

	// GetSpan returns the currently active span
	GetSpan(ctx context.Context) Span

	// AddField is for adding application-level information to the currently active span
	//
	// Any field name will be prefixed with "app."
	AddField(ctx context.Context, key string, val interface{})

	// AddFieldToTrace is for adding useful information to the root span.
	//
	// This will be propagated onto every child span.
	//
	// eg. build-url, plan-id, project-id, org-id etc
	AddFieldToTrace(ctx context.Context, key string, val interface{})

	// Log sends a zero duration trace event.
	Log(ctx context.Context, name string, fields ...Pair)

	Close(ctx context.Context)

	// MetricsProvider grants lower control over the metrics that o11y sends, allowing skipping spans.
	MetricsProvider() MetricsProvider

	// Helpers returns some specific helper functions
	Helpers() Helpers
}

type Span interface {
	// AddField is for adding application-level information to the span
	//
	// Any field name will be prefixed with "app."
	AddField(key string, val interface{})

	// AddRawField is for adding useful information to the span in library/plumbing code
	// Generally application code should prefer AddField() to avoid namespace clashes
	//
	// eg. result, http.status_code, db.system etc
	//
	// Refer to the opentelemetry draft spec for naming inspiration
	// https://github.com/open-telemetry/opentelemetry-specification/tree/7ae3d066c95c716ef3086228ef955d84ba03ac88/specification/trace/semantic_conventions
	AddRawField(key string, val interface{})

	// RecordMetric tells the provider to emit a metric to its metric backend when the span ends
	RecordMetric(metric Metric)

	// End sets the duration of the span and tells the related provider that the span is complete,
	// so it can do its appropriate processing. The span should not be used after End is called.
	End()
}

type Tag struct {
	Name  string
	Value interface{}
}