snapshot

Documentation

Index

• func ExtractResourceGroup(output string) string
• func FetchProwJobData(ctx context.Context, info *ProwJobInfo) (*ProwJobConfig, []TestResult, error)
• func SanitizeTestName(name string) string
• func WriteManifest(dir string, manifest *Manifest) error
• type GatherInput
• type Gatherer
  • func NewGatherer(client *azkustodata.Client) *Gatherer
  • func (g *Gatherer) Gather(ctx context.Context, input GatherInput, outputDir string) (*Manifest, *VerificationReport, error)
• type Manifest
• type ProwJobConfig
• type ProwJobInfo
  • func ParseProwURL(rawURL string) (*ProwJobInfo, error)
• type RequestInfo
• type ResourceEntry
• type TestResult
• type TimeWindow
• type VerificationCase
• type VerificationReport
  • func (r *VerificationReport) Failures() int
  • func (r *VerificationReport) Record(c VerificationCase)
• type VerificationStatus

Functions

func ExtractResourceGroup

func ExtractResourceGroup(output string) string

ExtractResourceGroup parses the resource group name from test output logs. Tests log a line like: "msg"="creating resource group" "resourceGroup"="<name>"

func FetchProwJobData

func FetchProwJobData(ctx context.Context, info *ProwJobInfo) (*ProwJobConfig, []TestResult, error)

FetchProwJobData downloads config and test results from a Prow job's GCS artifacts. Returns the Kusto config and all test results.

func SanitizeTestName

func SanitizeTestName(name string) string

SanitizeTestName replaces characters that are not alphanumeric, dashes, or underscores with underscores, producing a valid filesystem path component.

func WriteManifest

func WriteManifest(dir string, manifest *Manifest) error

WriteManifest serializes the manifest to a manifest.json file in the given directory.

Types

type GatherInput

type GatherInput struct {
	// ClusterURI is the full Kusto cluster endpoint URL.
	ClusterURI string
	// ServiceDatabase is the Kusto database containing service logs.
	ServiceDatabase string
	// HCPDatabase is the Kusto database containing hosted control plane logs.
	HCPDatabase string
	// ResourceGroup is the Azure resource group to scope queries to.
	ResourceGroup string
	// TimeWindow is the time range to query.
	TimeWindow TimeWindow
	// QueryTimeout is the timeout for individual Kusto queries.
	QueryTimeout time.Duration
}

GatherInput provides the parameters needed to gather a diagnostic snapshot.

type Gatherer

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

Gatherer produces structured diagnostic data directories by running a dependency chain of Kusto queries against Azure Data Explorer.

func NewGatherer

func NewGatherer(client *azkustodata.Client) *Gatherer

NewGatherer creates a new Gatherer with the given Kusto SDK client.

func (*Gatherer) Gather

func (g *Gatherer) Gather(ctx context.Context, input GatherInput, outputDir string) (*Manifest, *VerificationReport, error)

Gather runs the full diagnostic data gathering pipeline for a resource group and writes structured output to outputDir.

type Manifest

type Manifest struct {
	// TestName is the name of the test that failed, if this snapshot was gathered
	// from a test failure. Empty when gathered directly from a resource ID.
	TestName string `json:"test_name,omitempty"`

	// ProwJobURL is the URL to the Prow job that triggered this snapshot, if applicable.
	ProwJobURL string `json:"prow_job_url,omitempty"`

	// TimeWindow is the time range over which diagnostic data was gathered.
	TimeWindow TimeWindow `json:"time_window"`

	// ResourceGroup is the Azure resource group that was queried.
	ResourceGroup string `json:"resource_group"`

	// KustoCluster is the Kusto cluster endpoint used for queries.
	KustoCluster string `json:"kusto_cluster"`

	// KustoDatabase is the Kusto database used for queries.
	KustoDatabase string `json:"kusto_database"`

	// Resources lists each ARM resource for which diagnostic data was gathered.
	Resources []ResourceEntry `json:"resources"`

	// DirectoryLayout describes the output directory structure.
	DirectoryLayout map[string]string `json:"directory_layout"`
}

Manifest describes the complete set of diagnostic data gathered for a test or resource.

type ProwJobConfig

type ProwJobConfig struct {
	Region          string
	KustoName       string
	HCPDatabase     string
	ServiceDatabase string
}

ProwJobConfig holds the Kusto connection info extracted from a Prow job's config.yaml.

type ProwJobInfo

type ProwJobInfo struct {
	URL       string
	JobName   string
	ProwID    string
	GCSPrefix string
	IsPR      bool
}

ProwJobInfo holds the parsed information from a Prow job URL.

func ParseProwURL

func ParseProwURL(rawURL string) (*ProwJobInfo, error)

ParseProwURL extracts job name, Prow ID, GCS prefix, and PR status from a Prow job URL. Supports two formats:

• Periodic/postsubmit: https://prow.ci.openshift.org/view/gs/test-platform-results/logs/<job>/<prow-id>
• Presubmit (PR): https://prow.ci.openshift.org/view/gs/test-platform-results/pr-logs/pull/<org_repo>/<pr>/<job>/<prow-id>

type RequestInfo

type RequestInfo struct {
	// ClientRequestID is the unique client request identifier.
	ClientRequestID string `json:"client_request_id"`

	// CorrelationID is the correlation identifier grouping related requests.
	CorrelationID string `json:"correlation_id"`

	// Method is the HTTP method (GET, PUT, DELETE, etc.).
	Method string `json:"method"`

	// Path is the ARM resource path.
	Path string `json:"path"`

	// Status is the HTTP response status code.
	Status int `json:"status"`

	// Timestamp is when the request was received.
	Timestamp time.Time `json:"timestamp"`

	// Dir is the path to this request's output directory, relative to the snapshot root.
	Dir string `json:"dir"`
}

RequestInfo describes a single ARM request traced during diagnostic gathering.

type ResourceEntry

type ResourceEntry struct {
	// Type is the ARM resource type (e.g. "Microsoft.RedHatOpenShift/hcpOpenShiftClusters").
	Type string `json:"type"`

	// Name is the ARM resource name.
	Name string `json:"name"`

	// Dir is the path to this resource's output directory, relative to the snapshot root.
	Dir string `json:"dir"`

	// ResourceID is the full ARM resource ID.
	ResourceID string `json:"resource_id,omitempty"`

	// ClusterResourceID is the full ARM resource ID of the parent HCP cluster.
	ClusterResourceID string `json:"cluster_resource_id,omitempty"`

	// ClusterResourceName is the HCP cluster name (the parent cluster for child resources).
	ClusterResourceName string `json:"cluster_resource_name,omitempty"`

	// InternalID is the internal resource identifier discovered from backend logs.
	InternalID string `json:"internal_id,omitempty"`

	// ClusterID is the Clusters Service identifier for this cluster.
	ClusterID string `json:"cluster_id,omitempty"`

	// HostedClusterNamespace is the management cluster namespace for the hosted cluster.
	HostedClusterNamespace string `json:"hosted_cluster_namespace,omitempty"`

	// HostedControlPlaneNamespace is the management cluster namespace for the hosted control plane.
	HostedControlPlaneNamespace string `json:"hosted_control_plane_namespace,omitempty"`

	// Requests lists the ARM requests traced for this resource.
	Requests []RequestInfo `json:"requests,omitempty"`
}

ResourceEntry describes diagnostic data gathered for a single ARM resource.

type TestResult

type TestResult struct {
	Name          string
	Output        string
	Error         string
	Failed        bool
	StartTime     time.Time
	EndTime       time.Time
	ResourceGroup string // extracted from test output
}

TestResult represents a single test with its metadata.

type TimeWindow

type TimeWindow struct {
	Start time.Time `json:"start"`
	End   time.Time `json:"end"`
}

TimeWindow represents a bounded time range for diagnostic queries.

type VerificationCase

type VerificationCase struct {
	// Suite is the grouping key for this case (e.g. "type/name" or "context").
	Suite string
	// Query is the "component/queryName" identifier.
	Query string
	// Category is the query category for display purposes.
	Category string
	// ResourceType is the ARM resource type (e.g. "microsoft.redhatopenshift/hcpopenshiftclusters").
	// Used to produce stable jUnit test identifiers that don't change with resource names.
	ResourceType string
	// Status is the verification outcome.
	Status VerificationStatus
	// Message provides context about the failure or skip reason.
	Message string
	// RenderedKQL is the fully rendered KQL query text, provided so that
	// downstream consumers (e.g. HTML overview) can display it without
	// needing access to the query templates or data.
	RenderedKQL string
}

VerificationCase records the outcome of a single query's verification check.

type VerificationReport

type VerificationReport struct {
	Cases []VerificationCase
}

VerificationReport collects all verification cases from a gathering run.

func (*VerificationReport) Failures

func (r *VerificationReport) Failures() int

Failures returns the number of failed verification cases.

func (*VerificationReport) Record

func (r *VerificationReport) Record(c VerificationCase)

Record adds a verification case to the report.

type VerificationStatus

type VerificationStatus string

VerificationStatus represents the outcome of a verification check on a query.

const (
	// VerificationPass indicates the query returned results as expected.
	VerificationPass VerificationStatus = "pass"
	// VerificationFail indicates the query was expected to return results but did not.
	VerificationFail VerificationStatus = "fail"
	// VerificationSkipped indicates the query was not executed because prerequisites were not met.
	VerificationSkipped VerificationStatus = "skipped"
)