Documentation
¶
Overview ¶
Package db manages the MySQL connection and event log writes.
Index ¶
- type CampaignLookup
- type CampaignMetricRow
- type CampaignReasonDetailRow
- type CampaignReasonRow
- type CampaignRunDetail
- type CampaignRunRecord
- type CampaignRunSummary
- type DB
- func (d *DB) CampaignExportTable(ctx context.Context, campaignRunIDs []string, name string) (ExportTable, error)
- func (d *DB) CampaignExportTables(ctx context.Context, campaignRunIDs []string) ([]ExportTable, error)
- func (d *DB) CampaignMetricRows(ctx context.Context, campaignRunIDs []string) ([]CampaignMetricRow, error)
- func (d *DB) CampaignReasonDetailRows(ctx context.Context, campaignRunIDs []string) ([]CampaignReasonDetailRow, error)
- func (d *DB) CampaignReasonRows(ctx context.Context, campaignRunIDs []string) ([]CampaignReasonRow, error)
- func (d *DB) CampaignRunDetails(ctx context.Context, campaignRunIDs []string) ([]CampaignRunDetail, error)
- func (d *DB) Close() error
- func (d *DB) CloseCampaignRun(ctx context.Context, campaignRunID string, endedAt time.Time, reason string) error
- func (d *DB) CloseRun(ctx context.Context, runID string, endedAt time.Time, reason string) error
- func (d *DB) GroundTruthEventsForRun(ctx context.Context, runID string) ([]GroundTruthEvent, error)
- func (d *DB) InsertCampaignRun(ctx context.Context, r CampaignRunRecord) error
- func (d *DB) InsertGroundTruthEvent(ctx context.Context, e GroundTruthEvent) error
- func (d *DB) InsertMonitorReport(ctx context.Context, r MonitorReportRow) error
- func (d *DB) InsertRun(ctx context.Context, r RunRecord) error
- func (d *DB) MonitorReportsForRun(ctx context.Context, runID string) ([]MonitorReportRow, error)
- func (d *DB) ResolveCampaign(ctx context.Context, input string) (*CampaignLookup, error)
- func (d *DB) RunIDsForCampaign(ctx context.Context, campaignRunID string) ([]string, error)
- func (d *DB) UpsertDerivedMetric(ctx context.Context, r DerivedMetricRow) error
- type DerivedMetricRow
- type ExportTable
- type GroundTruthEvent
- type MonitorReportRow
- type RunRecord
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type CampaignLookup ¶
type CampaignLookup struct {
Input string
Runs []CampaignRunSummary
MatchedAsRunID bool // input matched a campaign_runs.id
MatchedAsConfigID bool // input matched at least one campaign_runs.campaign_id
}
CampaignLookup is the result of resolving a user-supplied campaign identifier to one or more campaign_runs rows. Either a concrete campaign_runs.id or the stable campaign_id from the campaign TOML is accepted; the report tool uses this to log which interpretation hit and to surface the aggregation depth in the output.
type CampaignMetricRow ¶
type CampaignMetricRow struct {
RunID string
FailureType string
ServiceID string
MetricName string
MetricValue *float64
MetricText string
}
CampaignMetricRow is one derived_metrics row joined to its campaign replay context for reporting.
type CampaignReasonDetailRow ¶
type CampaignReasonDetailRow struct {
FailureType string
ServiceID string
ReasonCode string
Detail string
Runs int
}
CampaignReasonDetailRow is one bucket of structured monitor_reports reason details joined to campaign replay context. ReasonCode is the machine bucket; Detail is the provider/adapter text that explains what happened.
type CampaignReasonRow ¶
type CampaignReasonRow struct {
RunID string
FailureType string
ServiceID string
ReasonCode string
}
CampaignReasonRow is one structured monitor_reports.reason_code row joined to its campaign replay context for reporting. Reason-code counts stay separate from derived_metrics so the support matrix remains queryable even when metric derivation changes.
type CampaignRunDetail ¶
type CampaignRunDetail struct {
ID string
CampaignID string
ConfigTOML string
MasterSeed int64
StartedAt time.Time
EndedAt *time.Time
ResolutionReason string
AdapterVersions string
TargetFleetVersion string
}
CampaignRunDetail carries the campaign_runs audit columns needed to reproduce the generated plan and preserve report metadata.
type CampaignRunRecord ¶
type CampaignRunRecord struct {
ID string
CampaignID string // from campaign TOML's `id` field
ConfigTOML string // verbatim campaign config
MasterSeed int64
StartedAt time.Time
AdapterVersions any // map[string]string of service_id → SHA, JSON-encoded
TargetFleetVersion string // commit SHA of target/dns binaries
}
CampaignRunRecord is a campaign_runs row. The audit-trail fields (ConfigTOML, MasterSeed, AdapterVersions, TargetFleetVersion) let a reader of a published comparison post regenerate the campaign deterministically. See docs/roadmap.md "Automated randomized testing campaigns" → "Methodology audit trail".
type CampaignRunSummary ¶
type CampaignRunSummary struct {
ID string
CampaignID string
StartedAt time.Time
EndedAt *time.Time // nil for an in-progress campaign
}
CampaignRunSummary describes one campaign_runs row resolved by ResolveCampaign — the audit-trail metadata the report tool needs to disclose how an aggregated report was scoped.
type DB ¶
type DB struct {
// contains filtered or unexported fields
}
DB wraps a *sql.DB with uptime-bench-specific query methods.
func Open ¶
Open connects to MySQL using the given DSN. DSN format: user:password@tcp(host:3306)/uptime_bench?parseTime=true
func (*DB) CampaignExportTable ¶
func (d *DB) CampaignExportTable(ctx context.Context, campaignRunIDs []string, name string) (ExportTable, error)
CampaignExportTable returns one allowlisted raw database table filtered to the selected campaign run IDs.
func (*DB) CampaignExportTables ¶
func (d *DB) CampaignExportTables(ctx context.Context, campaignRunIDs []string) ([]ExportTable, error)
CampaignExportTables returns the raw database evidence for a finalized report bundle. Table names and queries are intentionally allowlisted so callers cannot turn this into an arbitrary SQL interface.
func (*DB) CampaignMetricRows ¶
func (d *DB) CampaignMetricRows(ctx context.Context, campaignRunIDs []string) ([]CampaignMetricRow, error)
CampaignMetricRows returns derived metrics for every scenario run belonging to the given campaign_runs.id values. Callers first resolve a user-supplied identifier via ResolveCampaign so the report path can log which interpretation matched and how many runs were aggregated; passing the run-id list explicitly here keeps that signal out of band from the data fetch.
func (*DB) CampaignReasonDetailRows ¶
func (d *DB) CampaignReasonDetailRows(ctx context.Context, campaignRunIDs []string) ([]CampaignReasonDetailRow, error)
CampaignReasonDetailRows returns structured reason-code buckets split by retrieve_unknown_reason detail. It is intentionally grouped in SQL so report.md can show provider failure causes without replaying raw logs.
func (*DB) CampaignReasonRows ¶
func (d *DB) CampaignReasonRows(ctx context.Context, campaignRunIDs []string) ([]CampaignReasonRow, error)
CampaignReasonRows returns structured monitor report reason codes for every scenario run belonging to the given campaign_runs.id values. These rows power support-matrix reporting such as capability_mismatch counts.
func (*DB) CampaignRunDetails ¶
func (d *DB) CampaignRunDetails(ctx context.Context, campaignRunIDs []string) ([]CampaignRunDetail, error)
CampaignRunDetails returns campaign_runs audit rows for finalized report bundles. Rows are ordered by started_at, id for deterministic output.
func (*DB) CloseCampaignRun ¶
func (d *DB) CloseCampaignRun(ctx context.Context, campaignRunID string, endedAt time.Time, reason string) error
CloseCampaignRun sets ended_at and resolution_reason on an existing campaign row, mirroring CloseRun's shape for individual runs.
func (*DB) GroundTruthEventsForRun ¶
GroundTruthEventsForRun returns all ground_truth_events for a run, ordered by occurred_at.
func (*DB) InsertCampaignRun ¶
func (d *DB) InsertCampaignRun(ctx context.Context, r CampaignRunRecord) error
InsertCampaignRun writes a new campaign_runs row at campaign start.
func (*DB) InsertGroundTruthEvent ¶
func (d *DB) InsertGroundTruthEvent(ctx context.Context, e GroundTruthEvent) error
InsertGroundTruthEvent writes one ground_truth_events row.
func (*DB) InsertMonitorReport ¶
func (d *DB) InsertMonitorReport(ctx context.Context, r MonitorReportRow) error
InsertMonitorReport writes one monitor_reports row.
func (*DB) MonitorReportsForRun ¶
MonitorReportsForRun returns all monitor_reports for a run.
func (*DB) ResolveCampaign ¶
ResolveCampaign finds every campaign_runs row matching the input as either a concrete id or a stable campaign_id. Returns a lookup with MatchedAsRunID / MatchedAsConfigID flags so the caller can tell the user which interpretation hit (and warn when the answer is "neither — your report will be empty"). Rows are ordered by started_at, id for deterministic downstream consumption.
func (*DB) RunIDsForCampaign ¶
RunIDsForCampaign returns scenario_runs IDs belonging to a campaign run, ordered by start time for deterministic batch metric derivation.
func (*DB) UpsertDerivedMetric ¶
func (d *DB) UpsertDerivedMetric(ctx context.Context, r DerivedMetricRow) error
UpsertDerivedMetric inserts or replaces one derived_metrics row. The UNIQUE KEY on (run_id, service_id, metric_name) makes this idempotent.
type DerivedMetricRow ¶
type DerivedMetricRow struct {
RunID string
ServiceID string
MetricName string
MetricValue *float64
MetricText string
ComputedAt time.Time
}
DerivedMetricRow is a derived_metrics row.
type ExportTable ¶
ExportTable is one raw TSV-ready table exported for a finalized campaign.
type GroundTruthEvent ¶
type GroundTruthEvent struct {
RunID string
EventType string // run_start, run_end, failure_start, failure_end
TargetID string
FailureType string // empty for run_start / run_end
OccurredAt time.Time
Details any // will be JSON-encoded; may be nil
}
GroundTruthEvent is a ground_truth_events row.
type MonitorReportRow ¶
type MonitorReportRow struct {
RunID string
ServiceID string
RetrieveStatus string // "known" or "unknown"
RetrieveUnknownReason string // free-form detail, populated when unknown
ReasonCode string // structured code, e.g. "capability_mismatch"; see docs/events.md
EventType string // may be empty when unknown
RawClassification string
NormalizedClassification string
ReportedAt *time.Time
RetrievedAt time.Time
Metadata any
}
MonitorReportRow is a monitor_reports row.
type RunRecord ¶
type RunRecord struct {
ID string
ScenarioID string
ScenarioVersion string
Seed int64
TargetID string
CampaignID string // empty for direct (non-campaign) runs
Parameters any // will be JSON-encoded
StartedAt time.Time
EndedAt *time.Time
ResolutionReason *string
}
RunRecord is a scenario run row.