observability

type ComponentChecker func(ctx context.Context) HealthCheckResult

type DependencyChecker func(ctx context.Context) DependencyHealth

type DependencyHealth struct {
	// Name is the name of the dependency.
	//
	// Name 是依赖的名称。
	Name string `json:"name"`

	// Type is the type of dependency (e.g., "database", "redis", "grpc").
	//
	// Type 是依赖的类型（如 "database", "redis", "grpc"）。
	Type string `json:"type"`

	// Status is the health status of the dependency.
	//
	// Status 是依赖的健康状态。
	Status HealthStatus `json:"status"`

	// Message provides additional details.
	//
	// Message 提供额外详情。
	Message string `json:"message,omitempty"`

	// Latency is the time taken to check the dependency.
	//
	// Latency 是检查依赖所花费的时间。
	Latency time.Duration `json:"latency"`
}

type Field struct {
	Key   string
	Value any
}

type HealthCheckResult struct {
	// Name is the name of the component being checked.
	//
	// Name 是被检查组件的名称。
	Name string `json:"name"`

	// Status is the health status of the component.
	//
	// Status 是组件的健康状态。
	Status HealthStatus `json:"status"`

	// Message provides additional details about the health status.
	//
	// Message 提供健康状态的额外详情。
	Message string `json:"message,omitempty"`

	// Error contains the error if the health check failed.
	//
	// Error 包含健康检查失败的错误信息。
	Error string `json:"error,omitempty"`

	// Latency is the time taken to perform the health check.
	//
	// Latency 是执行健康检查所花费的时间。
	Latency time.Duration `json:"latency"`

	// Timestamp is when the health check was performed.
	//
	// Timestamp 是健康检查执行的时间戳。
	Timestamp time.Time `json:"timestamp"`

	// Metadata contains additional component-specific information.
	//
	// Metadata 包含额外的组件特定信息。
	Metadata map[string]any `json:"metadata,omitempty"`
}

type HealthChecker interface {
	// Check performs a health check and returns the aggregated report.
	//
	// Check 执行健康检查并返回聚合报告。
	Check(ctx context.Context) (*HealthReport, error)

	// CheckComponent performs a health check for a specific component.
	//
	// CheckComponent 对特定组件执行健康检查。
	CheckComponent(ctx context.Context, name string) (*HealthCheckResult, error)

	// AddChecker registers a component health checker.
	//
	// AddChecker 注册组件健康检查器。
	AddChecker(name string, checker ComponentChecker)

	// AddDependency registers a dependency health checker.
	//
	// AddDependency 注册依赖健康检查器。
	AddDependency(name string, dep DependencyChecker)
}

type HealthCheckerConfig struct {
	// ServiceName is the name of the service.
	//
	// ServiceName 是服务名称。
	ServiceName string `mapstructure:"service_name"`

	// Version is the service version.
	//
	// Version 是服务版本。
	Version string `mapstructure:"version"`

	// Timeout is the timeout for individual health checks.
	//
	// Timeout 是单个健康检查的超时时间。
	Timeout time.Duration `mapstructure:"timeout"`

	// CheckDependencies indicates whether to check dependencies.
	//
	// CheckDependencies 表示是否检查依赖。
	CheckDependencies bool `mapstructure:"check_dependencies"`
}

type HealthReport struct {
	// Service is the name of the service.
	//
	// Service 是服务名称。
	Service string `json:"service"`

	// Status is the overall health status of the service.
	//
	// Status 是服务的整体健康状态。
	Status HealthStatus `json:"status"`

	// Version is the service version.
	//
	// Version 是服务版本。
	Version string `json:"version"`

	// Timestamp is when the report was generated.
	//
	// Timestamp 是报告生成的时间戳。
	Timestamp time.Time `json:"timestamp"`

	// Checks contains individual health check results.
	//
	// Checks 包含各个健康检查的结果。
	Checks map[string]HealthCheckResult `json:"checks"`

	// Dependencies contains health status of dependent services.
	//
	// Dependencies 包含依赖服务的健康状态。
	Dependencies map[string]DependencyHealth `json:"dependencies,omitempty"`
}

type HealthStatus string

type Logger interface {
	Debug(msg string, fields ...Field)
	Info(msg string, fields ...Field)
	Warn(msg string, fields ...Field)
	Error(msg string, fields ...Field)

	With(fields ...Field) Logger
}

type Metrics interface {
	Counter(name string, labels map[string]string, delta float64)
	Gauge(name string, labels map[string]string, value float64)
	Histogram(name string, labels map[string]string, value float64)
	Timing(name string, labels map[string]string, duration time.Duration)
}

type Observability interface {
	Metrics() Metrics
	Tracer() Tracer
	Logger() Logger
	ErrorReporter() resiliencecontract.ErrorReporter
}

type ObservabilityConfig struct {
	MetricsEnabled        bool
	TracingEnabled        bool
	ErrorReportingEnabled bool
	ServiceName           string
	Environment           string
	Version               string
	SamplingRate          float64
}

type RequestContext struct {
	TraceID   string
	RequestID string
	Span      Span
	StartTime time.Time
	Labels    map[string]string
}

type Span interface {
	End(options ...SpanEndOption)
	AddEvent(name string, attributes map[string]interface{})
	SetTag(key string, value interface{})
	SetAttributes(attributes map[string]interface{})
	SetError(err error)
	SetStatus(code SpanStatusCode, description string)
	SpanContext() SpanContext
	IsRecording() bool
	Context() context.Context
}

type SpanConfig struct {
	Kind       SpanKind
	Attributes map[string]interface{}
	StartTime  time.Time
	Links      []SpanLink
}

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

type SpanEndConfig struct {
	EndTime time.Time
}

type SpanEndOption func(*SpanEndConfig)

type SpanKind int

type SpanLink struct {
	SpanContext SpanContext
	Attributes  map[string]interface{}
}

type SpanOption func(*SpanConfig)

type SpanStatusCode int

type TextMapCarrier interface {
	Get(key string) string
	Set(key string, value string)
	Keys() []string
}

type TraceFlags byte

type Tracer interface {
	StartSpan(ctx context.Context, name string, opts ...SpanOption) (context.Context, Span)
	SpanFromContext(ctx context.Context) Span
	Inject(ctx context.Context, carrier TextMapCarrier) error
	Extract(ctx context.Context, carrier TextMapCarrier) (context.Context, error)
}

type TracerConfig struct {
	SchemaURL  string
	Version    string
	Attributes map[string]interface{}
}

type TracerOption func(*TracerConfig)

type TracerProvider interface {
	Tracer(name string, options ...TracerOption) Tracer
	Shutdown(ctx context.Context) error
	ForceFlush(ctx context.Context) error
}

type TracingConfig struct {
	Enabled            bool
	ServiceName        string
	Environment        string
	Version            string
	ExporterType       string
	ExporterEndpoint   string
	SamplingRate       float64
	Propagators        []string
	ResourceAttributes map[string]string
	BatchTimeout       int
	MaxQueueSize       int
	MaxExportBatchSize int
}