observops

type Capability string

type CapabilityChecker interface {
	// HasCapability checks if the provider supports a given capability.
	HasCapability(cap Capability) bool

	// Capabilities returns all supported capabilities.
	Capabilities() []Capability
}

type ClientOption func(*Config)

type Config struct {
	// ServiceName is the name of the service.
	ServiceName string

	// ServiceVersion is the version of the service.
	ServiceVersion string

	// Endpoint is the backend endpoint.
	Endpoint string

	// APIKey is the API key for authentication.
	APIKey string //nolint:gosec // G117: APIKey is intentionally stored for backend authentication

	// Insecure disables TLS.
	Insecure bool

	// Headers are additional headers to send.
	Headers map[string]string

	// Resource is the resource describing the service.
	Resource *Resource

	// BatchTimeout is the maximum time to wait before exporting.
	BatchTimeout time.Duration

	// BatchSize is the maximum number of items per batch.
	BatchSize int

	// Disabled disables telemetry collection.
	Disabled bool

	// Debug enables debug logging.
	Debug bool

	// EnableMetrics enables the metrics signal (default true in Setup).
	EnableMetrics bool
	// EnableTraces enables the traces signal (default true in Setup).
	EnableTraces bool
	// EnableLogs enables the logs signal (default true in Setup).
	EnableLogs bool
	// EnablePrometheus adds a Prometheus pull exporter and exposes a /metrics handler.
	EnablePrometheus bool
	// EnableStdout mirrors telemetry to stdout (for local debugging).
	EnableStdout bool
	// OverHTTP uses OTLP over HTTP instead of gRPC for push export.
	OverHTTP bool
	// TraceSampleRatio is the head sampling ratio for traces (0..1, default 1.0).
	TraceSampleRatio float64
}

type ConfigError struct {
	Field   string
	Message string
}

type Counter interface {
	// Add increments the counter by the given value.
	Add(ctx context.Context, value float64, opts ...RecordOption)
}

type EventOption func(*eventConfig)

type ExportError struct {
	Signal  string // "metrics", "traces", or "logs"
	Count   int    // Number of items that failed to export
	Details string
	Err     error
}

type Gauge interface {
	// Record records the current gauge value.
	Record(ctx context.Context, value float64, opts ...RecordOption)
}

type Histogram interface {
	// Record records a value in the histogram.
	Record(ctx context.Context, value float64, opts ...RecordOption)
}

type KeyValue struct {
	Key   string
	Value any
}

type LogAttribute struct {
	Key   string
	Value any
}

type Logger interface {
	// Debug logs a debug message.
	Debug(ctx context.Context, msg string, attrs ...LogAttribute)

	// Info logs an info message.
	Info(ctx context.Context, msg string, attrs ...LogAttribute)

	// Warn logs a warning message.
	Warn(ctx context.Context, msg string, attrs ...LogAttribute)

	// Error logs an error message.
	Error(ctx context.Context, msg string, attrs ...LogAttribute)
}

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

type Meter interface {
	// Counter creates a counter metric (monotonically increasing).
	Counter(name string, opts ...MetricOption) (Counter, error)

	// UpDownCounter creates a counter that can increase or decrease.
	UpDownCounter(name string, opts ...MetricOption) (UpDownCounter, error)

	// Histogram creates a histogram for recording value distributions.
	Histogram(name string, opts ...MetricOption) (Histogram, error)

	// Gauge creates a gauge metric for recording current values.
	Gauge(name string, opts ...MetricOption) (Gauge, error)
}

type MetricOption func(*metricConfig)

type Provider interface {
	// Name returns the provider name (e.g., "otlp", "newrelic", "datadog").
	Name() string

	// Meter returns a metric meter for creating and recording metrics.
	Meter() Meter

	// Tracer returns a tracer for creating spans.
	Tracer() Tracer

	// Logger returns a structured logger.
	Logger() Logger

	// SlogHandler returns an slog.Handler that integrates with this provider.
	// The handler automatically correlates logs with active traces.
	// Options can be used to configure local output and filtering.
	SlogHandler(opts ...SlogOption) slog.Handler

	// Shutdown gracefully shuts down the provider, flushing any buffered data.
	Shutdown(ctx context.Context) error

	// ForceFlush forces any buffered telemetry to be exported.
	ForceFlush(ctx context.Context) error
}

type ProviderError struct {
	Provider string
	Op       string
	Err      error
}

type ProviderFactory func(opts ...ClientOption) (Provider, error)

type ProviderInfo struct {
	Name         string
	Description  string
	Website      string
	OpenSource   bool
	SelfHosted   bool
	Capabilities []Capability
}

type RecordOption func(*recordConfig)

type Resource struct {
	ServiceName      string
	ServiceVersion   string
	ServiceNamespace string
	DeploymentEnv    string
	Attributes       map[string]string
}

type SeverityLevel int

type SlogConfig struct {
	// LocalHandler is the handler for local output (console, file).
	// If nil, logs are only sent to the observability backend.
	LocalHandler interface{} // slog.Handler, using interface{} to avoid import cycle

	// RemoteLevel is the minimum level for remote export.
	// Defaults to slog.LevelInfo.
	RemoteLevel int // slog.Level value

	// IncludeTraceContext enables automatic trace_id/span_id injection.
	// Defaults to true.
	IncludeTraceContext bool

	// TraceIDKey is the attribute key for trace ID.
	// Defaults to "trace_id".
	TraceIDKey string

	// SpanIDKey is the attribute key for span ID.
	// Defaults to "span_id".
	SpanIDKey string

	// Disabled disables the handler (returns a noop handler).
	Disabled bool
}

type SlogOption func(*SlogConfig)

type Span interface {
	// End marks the span as finished.
	End(opts ...SpanEndOption)

	// SetAttributes sets attributes on the span.
	SetAttributes(attrs ...KeyValue)

	// SetStatus sets the span status.
	SetStatus(code StatusCode, description string)

	// RecordError records an error on the span.
	RecordError(err error, opts ...EventOption)

	// AddEvent adds an event to the span.
	AddEvent(name string, opts ...EventOption)

	// SpanContext returns the span's context.
	SpanContext() SpanContext

	// IsRecording returns true if the span is recording.
	IsRecording() bool
}

type SpanContext struct {
	TraceID    string
	SpanID     string
	TraceFlags byte
	Remote     bool
}

type SpanEndOption func(*spanEndConfig)

type SpanKind int

type SpanOption func(*spanConfig)

type StatusCode int

type Telemetry struct {
	// Tracer is a ready-to-use tracer named after the service.
	Tracer trace.Tracer
	// Meter is a ready-to-use meter named after the service.
	Meter metric.Meter
	// Logger is an slog.Logger fanning out to the console and, when logs are enabled, to
	// the OpenTelemetry log pipeline. It is also installed as slog.Default().
	Logger *slog.Logger
	// MetricsHandler serves Prometheus metrics when WithPrometheus is set, else nil.
	MetricsHandler http.Handler

	// Providers are exposed for advanced use (custom instruments, registration).
	TracerProvider *sdktrace.TracerProvider
	MeterProvider  *sdkmetric.MeterProvider
	LoggerProvider *sdklog.LoggerProvider
	// contains filtered or unexported fields
}

type Tracer interface {
	// Start creates a new span with the given name.
	Start(ctx context.Context, name string, opts ...SpanOption) (context.Context, Span)

	// SpanFromContext retrieves the current span from context.
	SpanFromContext(ctx context.Context) Span
}

type UpDownCounter interface {
	// Add adds the given value (can be negative).
	Add(ctx context.Context, value float64, opts ...RecordOption)
}