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 CommandEcho
- 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 SignatureWindow = 200
SignatureWindow is how many of a step's trailing lines carry its cause.
A signature is a regular expression over log text, so anywhere else in a long step it matches the vocabulary of ordinary output: a parametrized test ID reading "access denied not retryable", a Storybook story titled "Missing Secret Error". Measured over 42 runs of a repository with 26 workflows, the two matches that named a real cause sat 329 and 54 lines from their step's end, and every one of the other ten sat further back or in a step that succeeded. Widening this trades that precision away; see AGENTS.local.md for how to re-measure before changing it.
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 CommandEcho ¶ added in v1.3.0
type CommandEcho struct {
// contains filtered or unexported fields
}
CommandEcho tracks whether a step's lines are currently inside the command echo. Feed it a step's lines in order; a zero value starts outside.
func (*CommandEcho) Echoed ¶ added in v1.3.0
func (c *CommandEcho) Echoed(line string) bool
Echoed advances over line and reports whether it is script source rather than the step's own output.
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) *Manager
NewManager creates a new log manager that uses gh CLI if available.
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.
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.