feat: add bounded business state observability

internal/observability/business.go

@@ -0,0 +1,65 @@
+package observability
+
+import (
+	"context"
+	"errors"
+	"time"
+)
+
+// BusinessSnapshot 是存储层返回的固定基数业务快照。
+// Map 的键只由存储层固定状态集合产生，Registry 仍只向目录中的标签写值。
+type BusinessSnapshot struct {
+	// TaskStates Pulse 任务状态的有界计数。
+	TaskStates map[string]uint64
+	// TaskOldestAgeSeconds 未完成任务中最早可处理记录的年龄。
+	TaskOldestAgeSeconds float64
+	// DeliveryStates 结果交付状态的有界计数。
+	DeliveryStates map[string]uint64
+	// DeliveryOldestAgeSeconds 待处理交付中最早可处理记录的年龄。
+	DeliveryOldestAgeSeconds float64
+	// WorkflowStates Weave 实例状态的有界计数。
+	WorkflowStates map[string]uint64
+	// WorkflowOldestAgeSeconds 未终结流程中最早更新时间的年龄。
+	WorkflowOldestAgeSeconds float64
+	// Truncated 是否至少有一类状态达到采样上限。
+	Truncated bool
+}
+
+// RecordBusinessSnapshot records one bounded database sample. A failed sample
+// does not overwrite the last successful state, so stale data remains visible
+// together with an error counter and alertable last-success timestamp.
+func (r *Registry) RecordBusinessSnapshot(snapshot BusinessSnapshot, started time.Time, err error) {
+	if r == nil {
+		return
+	}
+	outcome := "success"
+	if err != nil {
+		outcome = "error"
+		if errors.Is(err, context.DeadlineExceeded) {
+			outcome = "timeout"
+		}
+	}
+	r.AddCounter("orbit_business_snapshot_total", 1, Labels{"outcome": outcome})
+	r.ObserveHistogram("orbit_business_snapshot_duration_seconds", time.Since(started).Seconds(), nil)
+	if err != nil {
+		return
+	}
+	for _, state := range taskStates {
+		r.SetGauge("orbit_pulse_tasks_state", float64(snapshot.TaskStates[state]), Labels{"state": state})
+	}
+	for _, state := range deliveryStates {
+		r.SetGauge("orbit_result_deliveries_state", float64(snapshot.DeliveryStates[state]), Labels{"state": state})
+	}
+	for _, state := range workflowStates {
+		r.SetGauge("orbit_weave_workflows_state", float64(snapshot.WorkflowStates[state]), Labels{"state": state})
+	}
+	r.SetGauge("orbit_pulse_tasks_oldest_age_seconds", snapshot.TaskOldestAgeSeconds, nil)
+	r.SetGauge("orbit_result_delivery_oldest_age_seconds", snapshot.DeliveryOldestAgeSeconds, nil)
+	r.SetGauge("orbit_weave_workflow_oldest_age_seconds", snapshot.WorkflowOldestAgeSeconds, nil)
+	truncated := 0.0
+	if snapshot.Truncated {
+		truncated = 1
+	}
+	r.SetGauge("orbit_business_snapshot_truncated", truncated, nil)
+	r.SetGauge("orbit_business_snapshot_last_success_timestamp_seconds", float64(time.Now().Unix()), nil)
+}