Documentation
¶
Overview ¶
Package sysdump provides diagnostic data collection infrastructure. It implements a pluggable collector pattern where independent data sources (eBPF maps, NATS state, DNS cache, Prometheus metrics) can be registered and orchestrated by the Manager without tight coupling.
Index ¶
- func GenerateArchive(w io.Writer, bundle *BundleResult) error
- func GenerateMultiNodeArchive(w io.Writer, multiResult *MultiNodeResult, version string) error
- type BundleResult
- type CollectRequest
- type CollectResponse
- type Collector
- type CollectorResult
- type FileEntry
- type Manager
- type Manifest
- type MultiNodeCoordinator
- func (mc *MultiNodeCoordinator) CollectFromCluster(ctx context.Context) (*MultiNodeResult, error)
- func (mc *MultiNodeCoordinator) CollectFromClusterAndArchive(ctx context.Context, progressCallback func(phase, nodeID, status string)) ([]byte, error)
- func (mc *MultiNodeCoordinator) GenerateArchive(w io.Writer, multiResult *MultiNodeResult) error
- type MultiNodeResult
- type NodeCollectionResult
- type NodeInfo
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func GenerateArchive ¶
func GenerateArchive(w io.Writer, bundle *BundleResult) error
GenerateArchive creates a .zip archive from diagnostic bundle results. Streams output to w without loading entire archive into memory. Returns error if archive creation fails.
Memory usage: <50MB for single-node bundles, <100MB for multi-node (<=20 nodes). Archive structure:
manifest.json (first file)
{hostname}-{nodeID}/
{collector-name}.json
If hostname is empty, uses nodeID/ directory instead. Compression: Level 6 (balanced performance vs size)
func GenerateMultiNodeArchive ¶
func GenerateMultiNodeArchive(w io.Writer, multiResult *MultiNodeResult, version string) error
GenerateMultiNodeArchive creates a .zip archive from multi-node collection results. Archive structure:
manifest.json (first file, lists all nodes and their status)
node-1/{collector}.json
node-2/{collector}.json
node-3/{collector}.json
Partial failures recorded in manifest.Warnings with node-specific errors. Memory usage: <100MB for clusters up to 20 nodes.
Types ¶
type BundleResult ¶
type BundleResult struct {
Version string `json:"version"`
GeneratedAt time.Time `json:"generated_at"`
NodeID string `json:"node_id"`
Hostname string `json:"hostname,omitempty"`
CollectorResults map[string]*CollectorResult `json:"collectors"`
Warnings []string `json:"warnings,omitempty"`
}
BundleResult aggregates all collector results
type CollectRequest ¶
type CollectRequest struct {
RequestID string `json:"request_id"` // For tracing
Timeout int `json:"timeout_sec"` // Hint: complete within this timeout
}
CollectRequest is sent to each node via NATS
type CollectResponse ¶
type CollectResponse struct {
NodeID string `json:"node_id"`
Hostname string `json:"hostname"`
Success bool `json:"success"`
Error string `json:"error,omitempty"`
Bundle json.RawMessage `json:"bundle,omitempty"` // BundleResult serialized
}
CollectResponse contains serialized BundleResult from node
type Collector ¶
type Collector interface {
// Name returns the collector identifier (e.g., "ebpf-maps", "nats-state")
Name() string
// Collect gathers diagnostic data and returns it as a serializable structure
// Returns error if collection fails; partial data allowed if documented
Collect(ctx context.Context) (interface{}, error)
}
Collector defines the interface for diagnostic data collection
type CollectorResult ¶
type CollectorResult struct {
Name string `json:"name"`
Data interface{} `json:"data,omitempty"`
Error string `json:"error,omitempty"`
Timestamp time.Time `json:"timestamp"`
Duration time.Duration `json:"duration_ms"`
}
CollectorResult holds the output from a single collector
type FileEntry ¶
type FileEntry struct {
Path string `json:"path"` // Relative path in archive
Size int64 `json:"size"` // Uncompressed size in bytes
SHA256 string `json:"sha256"` // Hex-encoded checksum
}
FileEntry describes a file within the archive
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager orchestrates diagnostic collection from registered collectors
func NewManager ¶
NewManager creates a new sysdump manager
func (*Manager) CollectAll ¶
func (m *Manager) CollectAll(ctx context.Context) (*BundleResult, error)
CollectAll executes all registered collectors and aggregates results Returns partial results even if some collectors fail
func (*Manager) SetupCollectionResponder ¶
SetupCollectionResponder registers NATS handler for collection requests. Called during node initialization to enable cluster-wide collection.
func (*Manager) TeardownCollectionResponder ¶
TeardownCollectionResponder cleans up NATS subscription
type Manifest ¶
type Manifest struct {
SchemaVersion string `json:"schema_version"` // "1.0.0" for initial version
Version string `json:"neuwerk_version"` // Neuwerk version
GeneratedAt time.Time `json:"generated_at"`
CollectionDuration string `json:"collection_duration,omitempty"`
ClusterID string `json:"cluster_id,omitempty"`
NodeID string `json:"node_id"`
Hostname string `json:"hostname,omitempty"`
Nodes []NodeInfo `json:"nodes"`
Files []FileEntry `json:"files"`
Warnings []string `json:"warnings,omitempty"`
}
Manifest describes the diagnostic bundle contents and metadata
type MultiNodeCoordinator ¶
type MultiNodeCoordinator struct {
// contains filtered or unexported fields
}
MultiNodeCoordinator orchestrates diagnostic collection across cluster
func NewMultiNodeCoordinator ¶
func NewMultiNodeCoordinator(nc *nats.Conn, membership cluster.Membership, version string, logger logr.Logger) *MultiNodeCoordinator
NewMultiNodeCoordinator creates a new multi-node collection coordinator
func (*MultiNodeCoordinator) CollectFromCluster ¶
func (mc *MultiNodeCoordinator) CollectFromCluster(ctx context.Context) (*MultiNodeResult, error)
CollectFromCluster collects diagnostics from all cluster nodes with quorum validation
func (*MultiNodeCoordinator) CollectFromClusterAndArchive ¶
func (mc *MultiNodeCoordinator) CollectFromClusterAndArchive( ctx context.Context, progressCallback func(phase, nodeID, status string), ) ([]byte, error)
CollectFromClusterAndArchive collects from all nodes and generates archive in one call. The progressCallback is invoked at key collection milestones:
- ("collecting", nodeID, "in-progress") - before collecting from a node
- ("collecting", nodeID, "complete") - after successful collection from a node
- ("redacting", "", "in-progress") - before redaction phase
- ("redacting", "", "complete") - after redaction phase
- ("archiving", "", "in-progress") - before archive generation
- ("archiving", "", "complete") - after archive generation
- ("complete", "", "success") - on successful completion
- ("error", nodeID, errorMessage) - on error
func (*MultiNodeCoordinator) GenerateArchive ¶
func (mc *MultiNodeCoordinator) GenerateArchive(w io.Writer, multiResult *MultiNodeResult) error
GenerateArchive creates .zip archive from multi-node collection result. Wrapper around GenerateMultiNodeArchive for MultiNodeCoordinator.
type MultiNodeResult ¶
type MultiNodeResult struct {
Results []*NodeCollectionResult
TotalNodes int
}
MultiNodeResult aggregates results from all nodes
type NodeCollectionResult ¶
type NodeCollectionResult struct {
NodeID string
Hostname string
Status string // "success" | "failed"
Error string
Bundle *BundleResult
}
NodeCollectionResult tracks collection result from a single node
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package redactor provides multi-stage secret redaction pipeline for diagnostic bundles.
|
Package redactor provides multi-stage secret redaction pipeline for diagnostic bundles. |