observability

package
v0.25.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Feb 20, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// SLO thresholds from ESIGN_APP_TDD.md section 10.2.
	ThresholdAdminReadP95MS          = 400.0
	ThresholdSendEnqueueP95MS        = 700.0
	ThresholdEmailDispatchP99MS      = 60_000.0
	ThresholdFinalizeCompletionP99MS = 120_000.0
	ThresholdMonthlyJobSuccessRate   = 99.5
)

Variables

This section is empty.

Functions

func BuildSLODashboard

func BuildSLODashboard(snapshot MetricsSnapshot, slo SLOStatus, alerts []Alert) map[string]any

BuildSLODashboard converts snapshot/evaluations into dashboard-friendly payload.

func ConfigureLogging

func ConfigureLogging(opts ...LoggerOption)

ConfigureLogging updates package-level logging behavior using options.

func LogOperation

func LogOperation(
	ctx context.Context,
	level slog.Level,
	component, operation, outcome, correlationID string,
	duration time.Duration,
	err error,
	fields map[string]any,
)

LogOperation records a structured operation log with canonical observability fields.

func ObserveAdminRead

func ObserveAdminRead(ctx context.Context, duration time.Duration, success bool, endpoint string)

func ObserveCompletionDelivery

func ObserveCompletionDelivery(ctx context.Context, success bool)

func ObserveEmailDispatchStart

func ObserveEmailDispatchStart(ctx context.Context, duration time.Duration, success bool)

func ObserveFinalize

func ObserveFinalize(ctx context.Context, duration time.Duration, success bool)

func ObserveGoogleAuthChurn

func ObserveGoogleAuthChurn(ctx context.Context, reason string)

func ObserveGoogleImport

func ObserveGoogleImport(ctx context.Context, success bool, reason string)

func ObserveJobResult

func ObserveJobResult(ctx context.Context, jobName string, success bool)

func ObserveProviderResult

func ObserveProviderResult(ctx context.Context, provider string, success bool)

func ObserveSend

func ObserveSend(ctx context.Context, duration time.Duration, success bool)

func ObserveSignerLinkOpen

func ObserveSignerLinkOpen(ctx context.Context, success bool)

func ObserveSignerSubmit

func ObserveSignerSubmit(ctx context.Context, duration time.Duration, success bool)

func ObserveTokenValidationFailure

func ObserveTokenValidationFailure(ctx context.Context, reason string)

func ObserveUnifiedFieldSave

func ObserveUnifiedFieldSave(ctx context.Context, duration time.Duration, success bool)

func ObserveUnifiedSignatureAttach

func ObserveUnifiedSignatureAttach(ctx context.Context, duration time.Duration, success bool)

func ObserveUnifiedSubmitConversion

func ObserveUnifiedSubmitConversion(ctx context.Context, success bool)

func ObserveUnifiedViewerLoad

func ObserveUnifiedViewerLoad(ctx context.Context, duration time.Duration, success bool)

func ResetDefaultMetrics

func ResetDefaultMetrics()

func ResetLogging

func ResetLogging()

ResetLogging resets observability operation logging to no-op defaults.

func ResolveCorrelationID

func ResolveCorrelationID(candidates ...string) string

ResolveCorrelationID returns the first non-empty candidate or generates a new ID.

func SetLogger

func SetLogger(logger Logger)

SetLogger is a convenience wrapper around ConfigureLogging(WithLogger(...)).

func SetMetrics

func SetMetrics(metrics Metrics)

Types

type Alert

type Alert struct {
	Code     string         `json:"code"`
	Severity string         `json:"severity"`
	Message  string         `json:"message"`
	Metadata map[string]any `json:"metadata,omitempty"`
}

Alert captures an actionable operator-facing alert.

func EvaluateAlerts

func EvaluateAlerts(snapshot MetricsSnapshot, policy AlertPolicy) []Alert

EvaluateAlerts returns active alerts for provider/job failure rates above policy thresholds.

type AlertPolicy

type AlertPolicy struct {
	ProviderFailureRatePercentThreshold float64
	JobFailureRatePercentThreshold      float64
	GoogleImportFailureTotalThreshold   int64
	GoogleAuthChurnTotalThreshold       int64
	SignerLinkOpenRatePercentFloor      float64
	SignerSubmitConversionPercentFloor  float64
	CompletionDeliverySuccessRateFloor  float64
}

AlertPolicy defines thresholds for provider/job health checks.

func DefaultAlertPolicy

func DefaultAlertPolicy() AlertPolicy

DefaultAlertPolicy returns baseline thresholds for e-sign runtime alerting.

type Logger

type Logger = glog.Logger

Logger is the go-logger compatible contract used by e-sign observability logging.

type LoggerOption

type LoggerOption func(*loggerOptions)

LoggerOption customizes how operation logging is wired.

func WithLogger

func WithLogger(logger Logger) LoggerOption

WithLogger injects the logger used to emit observability operation logs.

type Metrics

type Metrics interface {
	ObserveAdminRead(ctx context.Context, duration time.Duration, success bool, endpoint string)
	ObserveSend(ctx context.Context, duration time.Duration, success bool)
	ObserveSignerLinkOpen(ctx context.Context, success bool)
	ObserveUnifiedViewerLoad(ctx context.Context, duration time.Duration, success bool)
	ObserveUnifiedFieldSave(ctx context.Context, duration time.Duration, success bool)
	ObserveUnifiedSignatureAttach(ctx context.Context, duration time.Duration, success bool)
	ObserveUnifiedSubmitConversion(ctx context.Context, success bool)
	ObserveSignerSubmit(ctx context.Context, duration time.Duration, success bool)
	ObserveFinalize(ctx context.Context, duration time.Duration, success bool)
	ObserveEmailDispatchStart(ctx context.Context, duration time.Duration, success bool)
	ObserveCompletionDelivery(ctx context.Context, success bool)
	ObserveJobResult(ctx context.Context, jobName string, success bool)
	ObserveProviderResult(ctx context.Context, provider string, success bool)
	ObserveTokenValidationFailure(ctx context.Context, reason string)
	ObserveGoogleImport(ctx context.Context, success bool, reason string)
	ObserveGoogleAuthChurn(ctx context.Context, reason string)
	Snapshot() MetricsSnapshot
}

Metrics captures e-sign telemetry needed for observability/SLO evaluation.

type MetricsSnapshot

type MetricsSnapshot struct {
	AdminReadP95MS          float64
	SendP95MS               float64
	SignerSubmitP95MS       float64
	UnifiedViewerLoadP95MS  float64
	UnifiedFieldSaveP95MS   float64
	UnifiedSignatureP95MS   float64
	FinalizeP99MS           float64
	EmailDispatchStartP99MS float64

	AdminReadSampleTotal     int64
	SendSampleTotal          int64
	SignerSubmitSampleTotal  int64
	UnifiedViewerSampleTotal int64
	UnifiedFieldSaveTotal    int64
	UnifiedSignatureTotal    int64
	FinalizeSampleTotal      int64
	EmailDispatchSampleTotal int64

	SendSuccessTotal               int64
	SendFailureTotal               int64
	SignerLinkOpenSuccessTotal     int64
	SignerLinkOpenFailureTotal     int64
	SignerSubmitSuccessTotal       int64
	SignerSubmitFailureTotal       int64
	UnifiedViewerSuccessTotal      int64
	UnifiedViewerFailureTotal      int64
	UnifiedFieldSaveSuccessTotal   int64
	UnifiedFieldSaveFailureTotal   int64
	UnifiedSignatureSuccessTotal   int64
	UnifiedSignatureFailureTotal   int64
	UnifiedSubmitSuccessTotal      int64
	UnifiedSubmitFailureTotal      int64
	FinalizeSuccessTotal           int64
	FinalizeFailureTotal           int64
	CompletionDeliverySuccessTotal int64
	CompletionDeliveryFailureTotal int64

	JobSuccessTotal      int64
	JobFailureTotal      int64
	EmailSuccessTotal    int64
	EmailFailureTotal    int64
	TokenFailureTotal    int64
	TokenFailureByReason map[string]int64

	GoogleImportSuccessTotal    int64
	GoogleImportFailureTotal    int64
	GoogleImportFailureByReason map[string]int64
	GoogleAuthChurnTotal        int64
	GoogleAuthChurnByReason     map[string]int64

	ProviderSuccessByName map[string]int64
	ProviderFailureByName map[string]int64
	JobSuccessByName      map[string]int64
	JobFailureByName      map[string]int64
}

MetricsSnapshot is a read-model used by alerting and SLO dashboards.

func Snapshot

func Snapshot() MetricsSnapshot

func (MetricsSnapshot) CompletionDeliverySuccessRatePercent

func (s MetricsSnapshot) CompletionDeliverySuccessRatePercent() float64

func (MetricsSnapshot) EmailSuccessRatePercent

func (s MetricsSnapshot) EmailSuccessRatePercent() float64

func (MetricsSnapshot) JobSuccessRatePercent

func (s MetricsSnapshot) JobSuccessRatePercent() float64

func (MetricsSnapshot) SignerLinkOpenRatePercent

func (s MetricsSnapshot) SignerLinkOpenRatePercent() float64

func (MetricsSnapshot) SignerSubmitConversionPercent

func (s MetricsSnapshot) SignerSubmitConversionPercent() float64

func (MetricsSnapshot) UnifiedSubmitConversionPercent

func (s MetricsSnapshot) UnifiedSubmitConversionPercent() float64

type OperationLogger

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

OperationLogger emits canonical structured operation logs for e-sign flows.

func NewOperationLogger

func NewOperationLogger(opts ...LoggerOption) *OperationLogger

NewOperationLogger builds an operation logger from DI-style options.

func (*OperationLogger) LogOperation

func (l *OperationLogger) LogOperation(
	ctx context.Context,
	level slog.Level,
	component, operation, outcome, correlationID string,
	duration time.Duration,
	err error,
	fields map[string]any,
)

LogOperation records a structured operation log with canonical observability fields.

type SLOStatus

type SLOStatus struct {
	OverallPass bool              `json:"overall_pass"`
	Targets     []SLOTargetStatus `json:"targets"`
}

func EvaluateSLO

func EvaluateSLO(snapshot MetricsSnapshot) SLOStatus

EvaluateSLO validates snapshot telemetry against TDD numeric thresholds.

type SLOTargetStatus

type SLOTargetStatus struct {
	Metric     string  `json:"metric"`
	Actual     float64 `json:"actual"`
	Threshold  float64 `json:"threshold"`
	Comparator string  `json:"comparator"`
	Pass       bool    `json:"pass"`
	Unit       string  `json:"unit"`
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL