Documentation
¶
Overview ¶
Package logs provides workflow run log fetching, caching, filtering, and streaming functionality.
Index ¶
- Constants
- Variables
- func CheckGHCLIAvailable() error
- func CheckGHCLIAvailableWithExecutor(executor exec.CommandExecutor) error
- func ExportAsMarkdown(runLogs *RunLogs, config *FilterConfig) (string, error)
- func GenerateANSILog() string
- func GenerateLargeLogFixture(lines int) string
- func GenerateLargeLogWithErrors(lines int, errorRate float64) string
- func GenerateLogWithTimestamps(lines int) string
- func GenerateMixedLog(lines int) string
- func GenerateMultiStepLog(numSteps, linesPerStep int) string
- func GenerateUnicodeLog() string
- func LoadFixture(tb testing.TB, filename string) string
- type Cache
- type CacheEntry
- type CacheStats
- type Detection
- type Fetcher
- type Filter
- type FilterConfig
- type FilterLevel
- type FilteredLogEntry
- type FilteredResult
- type FilteredStepLogs
- type GHFetcher
- type GitHubClient
- type LogEntry
- type LogFetcher
- type LogLevel
- type LogStreamer
- type Manager
- type MatchPosition
- type Pattern
- type RunLogs
- type StepLogs
- type StreamState
- type StreamUpdate
Constants ¶
const StreamPollInterval = 2 * time.Second
StreamPollInterval is the interval between log polling for active runs.
Variables ¶
var QuickFilters = map[string]*FilterConfig{ string(FilterAll): { Level: FilterAll, SearchTerm: "", CaseSensitive: false, Regex: false, StepIndex: -1, }, string(FilterErrors): { Level: FilterErrors, SearchTerm: "", CaseSensitive: false, Regex: false, StepIndex: -1, }, string(FilterWarnings): { Level: FilterWarnings, SearchTerm: "", CaseSensitive: false, Regex: false, StepIndex: -1, }, }
QuickFilters provides common filter configurations.
Functions ¶
func CheckGHCLIAvailable ¶
func CheckGHCLIAvailable() error
CheckGHCLIAvailable checks if gh CLI is installed and authenticated.
func CheckGHCLIAvailableWithExecutor ¶
func CheckGHCLIAvailableWithExecutor(executor exec.CommandExecutor) error
CheckGHCLIAvailableWithExecutor checks if gh CLI is installed and authenticated using a custom executor.
func ExportAsMarkdown ¶ added in v1.2.0
func ExportAsMarkdown(runLogs *RunLogs, config *FilterConfig) (string, error)
ExportAsMarkdown renders a run's logs as a markdown document: a heading per step with its status, the detected failure signatures, and each step's lines in a fenced block. A nil filter exports everything.
The document is lossy by design: it holds what a reader pastes into an issue, not a byte-exact copy of the run's output.
func GenerateANSILog ¶
func GenerateANSILog() string
GenerateANSILog creates logs with ANSI color codes. Tests proper handling of terminal color escape sequences.
func GenerateLargeLogFixture ¶
GenerateLargeLogFixture creates a realistic log file with N lines. Uses GitHub Actions log format patterns for authenticity.
func GenerateLargeLogWithErrors ¶
GenerateLargeLogWithErrors creates a log with error patterns. The errorRate is a float between 0 and 1 indicating percentage of lines that should be errors.
func GenerateLogWithTimestamps ¶
GenerateLogWithTimestamps creates log lines with timestamp prefixes. Tests timestamp parsing and display.
func GenerateMixedLog ¶
GenerateMixedLog creates a log with various patterns for comprehensive testing. Includes errors, warnings, unicode, ANSI codes, and normal logs.
func GenerateMultiStepLog ¶
GenerateMultiStepLog creates a log output with multiple GitHub Actions steps. Simulates a real workflow run with step grouping.
func GenerateUnicodeLog ¶
func GenerateUnicodeLog() string
GenerateUnicodeLog creates logs with unicode characters. Tests proper handling of international characters and emoji.
Types ¶
type Cache ¶
type Cache struct {
// contains filtered or unexported fields
}
Cache stores fetched logs locally for quick access.
func NewCache ¶
NewCache creates a new log cache. The cacheDir should be something like ~/.cache/lazydispatch/logs/.
type CacheEntry ¶
type CacheEntry struct {
CachedAt time.Time `json:"cached_at"`
Logs *RunLogs `json:"logs"`
ChainName string `json:"chain_name"`
RunID int64 `json:"run_id"`
TTL time.Duration `json:"ttl"`
}
CacheEntry represents cached log data.
type CacheStats ¶
CacheStats provides cache metrics.
type Detection ¶ added in v1.2.0
Detection is one pattern found in one step. A single signature is reported once per step, holding the first line that matched, so a stack trace repeating the same message does not bury the other signatures.
type Fetcher ¶
type Fetcher struct {
// contains filtered or unexported fields
}
Fetcher fetches and parses workflow logs.
func NewFetcher ¶
func NewFetcher(client GitHubClient) *Fetcher
NewFetcher creates a new log fetcher.
func (*Fetcher) FetchRunSummary ¶
FetchRunSummary creates a summary of failed steps without full logs.
type Filter ¶
type Filter struct {
// contains filtered or unexported fields
}
Filter applies filtering logic to log entries.
func NewFilter ¶
func NewFilter(config *FilterConfig) (*Filter, error)
NewFilter creates a new log filter with the given configuration.
func (*Filter) Apply ¶
func (f *Filter) Apply(runLogs *RunLogs) *FilteredResult
Apply filters a RunLogs instance and returns filtered entries.
type FilterConfig ¶
type FilterConfig struct {
Level FilterLevel
SearchTerm string
CaseSensitive bool
Regex bool
StepIndex int // -1 for all steps
}
FilterConfig configures log filtering.
func NewFilterConfig ¶
func NewFilterConfig() *FilterConfig
NewFilterConfig creates a default filter config.
type FilterLevel ¶
type FilterLevel string
FilterLevel represents different log filtering modes.
const ( FilterAll FilterLevel = "all" FilterErrors FilterLevel = "errors" FilterWarnings FilterLevel = "warnings" FilterCustom FilterLevel = "custom" )
Log filtering modes.
type FilteredLogEntry ¶
type FilteredLogEntry struct {
Original LogEntry
Matches []MatchPosition
OriginalIndex int
}
FilteredLogEntry wraps a log entry with match information.
type FilteredResult ¶
type FilteredResult struct {
Config *FilterConfig
Steps []*FilteredStepLogs
}
FilteredResult contains the filtered logs with match information.
func (*FilteredResult) TotalEntries ¶
func (fr *FilteredResult) TotalEntries() int
TotalEntries returns the total number of filtered entries.
type FilteredStepLogs ¶
type FilteredStepLogs struct {
Workflow string
StepName string
Entries []FilteredLogEntry
StepIndex int
}
FilteredStepLogs contains filtered logs for a single step.
type GHFetcher ¶
type GHFetcher struct {
// contains filtered or unexported fields
}
GHFetcher fetches real logs using gh CLI.
func NewGHFetcher ¶
func NewGHFetcher(client GitHubClient) *GHFetcher
NewGHFetcher creates a fetcher that uses gh CLI for real log access.
func NewGHFetcherWithExecutor ¶
func NewGHFetcherWithExecutor(client GitHubClient, executor exec.CommandExecutor) *GHFetcher
NewGHFetcherWithExecutor creates a fetcher with a custom executor (for testing).
func (*GHFetcher) FetchStepLogsReal ¶
FetchStepLogsReal fetches actual logs from GitHub using gh CLI.
type GitHubClient ¶
type GitHubClient interface {
GetWorkflowRun(runID int64) (*github.WorkflowRun, error)
GetWorkflowRunJobs(runID int64) ([]github.Job, error)
}
GitHubClient interface for fetching workflow data.
type LogEntry ¶
type LogEntry struct {
Timestamp time.Time `json:"timestamp"`
Content string `json:"content"`
Level LogLevel `json:"level"` // error, warning, info, debug
StepName string `json:"step_name"` // for grouping
}
LogEntry represents a single log line with metadata.
func ParseLogOutput ¶
ParseLogOutput parses raw log text into LogEntry structs. Detects log levels based on common patterns.
type LogFetcher ¶
LogFetcher defines the interface for fetching logs.
type LogStreamer ¶
type LogStreamer struct {
// contains filtered or unexported fields
}
LogStreamer polls for incremental log updates from active workflow runs.
func NewLogStreamer ¶
func NewLogStreamer(client GitHubClient, runID int64, workflow string) *LogStreamer
NewLogStreamer creates a new LogStreamer for a specific run.
func (*LogStreamer) Stop ¶
func (s *LogStreamer) Stop()
Stop stops the streamer and cleans up resources. Safe to call multiple times.
func (*LogStreamer) Updates ¶
func (s *LogStreamer) Updates() <-chan StreamUpdate
Updates returns the channel for receiving log updates.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager coordinates log fetching, caching, and access.
func NewManager ¶
func NewManager(client GitHubClient, cacheDir string) *Manager
NewManager creates a new log manager that uses gh CLI if available.
func (*Manager) ClearExpired ¶
ClearExpired removes expired entries from the cache.
func (*Manager) GetLogsForChain ¶
GetLogsForChain fetches or retrieves cached logs for a chain execution. Per-step fetch errors are recorded on the affected step rather than returned, but the error return is kept for symmetry with GetLogsForRun since callers assign both into one var.
func (*Manager) GetLogsForRun ¶
GetLogsForRun fetches logs for a single workflow run.
type MatchPosition ¶
MatchPosition indicates where a search term was found in the content.
type Pattern ¶ added in v1.2.0
Pattern is one failure signature a reader would otherwise scroll to find, paired with the first thing worth trying about it.
type RunLogs ¶
type RunLogs struct {
ChainName string `json:"chain_name"`
Branch string `json:"branch"`
Steps []*StepLogs `json:"steps"`
// contains filtered or unexported fields
}
RunLogs contains logs for all steps in a workflow run or chain.
func GenerateRunLogsWithEntries ¶
GenerateRunLogsWithEntries creates RunLogs with N total entries for benchmarking. Distributes entries across multiple steps with varying log levels.
func NewRunLogs ¶
NewRunLogs creates a new RunLogs instance.
type StepLogs ¶
type StepLogs struct {
FetchedAt time.Time `json:"fetched_at"`
Error error `json:"-"`
Workflow string `json:"workflow"`
JobName string `json:"job_name"`
StepName string `json:"step_name"`
Status string `json:"status"`
Conclusion string `json:"conclusion"`
Entries []LogEntry `json:"entries"`
StepIndex int `json:"step_index"`
RunID int64 `json:"run_id"`
}
StepLogs contains all log entries for a single workflow step.
type StreamState ¶
StreamState tracks the state of logs for incremental updates.