Documentation
¶
Overview ¶
Package annotations provides loggers for emitting structured build and CI annotations such as errors, warnings, and notices.
Unlike ordinary log lines, annotations are intended for systems that can highlight issues in a richer way, for example by attaching messages to files and line numbers or surfacing build problems prominently in the UI.
The package provides a generic annotation model plus platform-specific formatters for common CI systems. Annotation loggers are built on top of the repository's [logs.Loggers] abstraction so they can reuse existing logging sinks.
References:
- GitHub Actions workflow commands: https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-commands
- Azure DevOps logging commands: https://learn.microsoft.com/en-us/azure/devops/pipelines/scripts/logging-commands
- TeamCity service messages: https://www.jetbrains.com/help/teamcity/service-messages.html
Index ¶
- func SeverityStrings() []string
- type Annotation
- type AnnotationLogger
- func NewAzureDevOpsLogger(baseLogger baselogs.Loggers) (*AnnotationLogger, error)
- func NewGitHubLogger(baseLogger baselogs.Loggers) (*AnnotationLogger, error)
- func NewLogger(baseLogger baselogs.Loggers, formatter IFormatter) (*AnnotationLogger, error)
- func NewTeamCityLogger(baseLogger baselogs.Loggers) (*AnnotationLogger, error)
- func (l *AnnotationLogger) Check() error
- func (l *AnnotationLogger) WriteAnnotation(annotation *Annotation) error
- func (l *AnnotationLogger) WriteError(message string, options ...AnnotationOption) error
- func (l *AnnotationLogger) WriteNotice(message string, options ...AnnotationOption) error
- func (l *AnnotationLogger) WriteWarning(message string, options ...AnnotationOption) error
- type AnnotationOption
- type AzureDevOpsFormatter
- type GitHubFormatter
- type IAnnotationLogger
- type IFormatter
- type Severity
- func (i Severity) IsASeverity() bool
- func (i Severity) MarshalJSON() ([]byte, error)
- func (i Severity) MarshalText() ([]byte, error)
- func (i Severity) MarshalYAML() (interface{}, error)
- func (i Severity) String() string
- func (i *Severity) UnmarshalJSON(data []byte) error
- func (i *Severity) UnmarshalText(text []byte) error
- func (i *Severity) UnmarshalYAML(unmarshal func(interface{}) error) error
- type TeamCityFormatter
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func SeverityStrings ¶
func SeverityStrings() []string
SeverityStrings returns a slice of all String values of the enum
Types ¶
type Annotation ¶
type Annotation struct {
// Severity identifies whether the annotation is an error, warning, or notice.
Severity Severity
// Message is the human-readable annotation text.
Message string
// File is the file path associated with the annotation, if any.
File string
// Line is the 1-based line number associated with the annotation, if any.
Line *int
// Column is the 1-based column number associated with the annotation, if any.
Column *int
}
Annotation describes a structured annotation message.
type AnnotationLogger ¶
AnnotationLogger formats annotations and emits them through an underlying logger.
The logger delegates final emission to an existing [logs.Loggers] implementation and is therefore suitable for any sink already supported by the logs package.
func NewAzureDevOpsLogger ¶
func NewAzureDevOpsLogger(baseLogger baselogs.Loggers) (*AnnotationLogger, error)
NewAzureDevOpsLogger creates an Azure DevOps-formatted annotation logger backed by baseLogger.
func NewGitHubLogger ¶
func NewGitHubLogger(baseLogger baselogs.Loggers) (*AnnotationLogger, error)
NewGitHubLogger creates a GitHub-formatted annotation logger backed by baseLogger.
func NewLogger ¶
func NewLogger(baseLogger baselogs.Loggers, formatter IFormatter) (*AnnotationLogger, error)
NewLogger creates an annotation logger backed by baseLogger.
func NewTeamCityLogger ¶
func NewTeamCityLogger(baseLogger baselogs.Loggers) (*AnnotationLogger, error)
NewTeamCityLogger creates a TeamCity-formatted annotation logger backed by baseLogger.
func (*AnnotationLogger) Check ¶
func (l *AnnotationLogger) Check() error
func (*AnnotationLogger) WriteAnnotation ¶
func (l *AnnotationLogger) WriteAnnotation(annotation *Annotation) error
WriteAnnotation writes annotation using the configured formatter.
func (*AnnotationLogger) WriteError ¶
func (l *AnnotationLogger) WriteError(message string, options ...AnnotationOption) error
WriteError writes an error-level annotation.
func (*AnnotationLogger) WriteNotice ¶
func (l *AnnotationLogger) WriteNotice(message string, options ...AnnotationOption) error
WriteNotice writes a notice-level annotation.
func (*AnnotationLogger) WriteWarning ¶
func (l *AnnotationLogger) WriteWarning(message string, options ...AnnotationOption) error
WriteWarning writes a warning-level annotation.
type AnnotationOption ¶
type AnnotationOption func(*Annotation) *Annotation
AnnotationOption configures an annotation.
func WithColumn ¶
func WithColumn(column int) AnnotationOption
WithColumn sets the column associated with an annotation.
func WithFile ¶
func WithFile(path string) AnnotationOption
WithFile sets the file path associated with an annotation.
func WithLine ¶
func WithLine(line int) AnnotationOption
WithLine sets the line associated with an annotation.
type AzureDevOpsFormatter ¶
type AzureDevOpsFormatter struct{}
AzureDevOpsFormatter formats annotations as Azure DevOps logging commands.
Reference:
func (AzureDevOpsFormatter) Format ¶
func (AzureDevOpsFormatter) Format(annotation *Annotation) string
type GitHubFormatter ¶
type GitHubFormatter struct{}
GitHubFormatter formats annotations as GitHub Actions annotation commands.
Reference:
func (GitHubFormatter) Format ¶
func (GitHubFormatter) Format(annotation *Annotation) string
type IAnnotationLogger ¶
type IAnnotationLogger interface {
baselogs.Loggers
// WriteAnnotation writes annotation using the configured formatter.
WriteAnnotation(annotation *Annotation) error
// WriteError writes an error-level annotation.
WriteError(message string, options ...AnnotationOption) error
// WriteWarning writes a warning-level annotation.
WriteWarning(message string, options ...AnnotationOption) error
// WriteNotice writes a notice-level annotation.
WriteNotice(message string, options ...AnnotationOption) error
}
IAnnotationLogger extends [logs.Loggers] with methods for writing structured annotations.
An annotation logger emits issue records in a format that CI systems can interpret specially, for example by surfacing them as file-linked errors or warnings in the build UI.
type IFormatter ¶
type IFormatter interface {
Format(annotation *Annotation) string
}
IFormatter converts an annotation into the platform-specific line to emit.
References:
- GitHub Actions workflow commands: https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-commands
- Azure DevOps logging commands: https://learn.microsoft.com/en-us/azure/devops/pipelines/scripts/logging-commands
- TeamCity service messages: https://www.jetbrains.com/help/teamcity/service-messages.html
type Severity ¶
type Severity int
Severity identifies the severity of an annotation.
func SeverityString ¶
SeverityString retrieves an enum value from the enum constants string name. Throws an error if the param is not part of the enum.
func SeverityValues ¶
func SeverityValues() []Severity
SeverityValues returns all values of the enum
func (Severity) IsASeverity ¶
IsASeverity returns "true" if the value is listed in the enum definition. "false" otherwise
func (Severity) MarshalJSON ¶
MarshalJSON implements the json.Marshaler interface for Severity
func (Severity) MarshalText ¶
MarshalText implements the encoding.TextMarshaler interface for Severity
func (Severity) MarshalYAML ¶
MarshalYAML implements a YAML Marshaler for Severity
func (*Severity) UnmarshalJSON ¶
UnmarshalJSON implements the json.Unmarshaler interface for Severity
func (*Severity) UnmarshalText ¶
UnmarshalText implements the encoding.TextUnmarshaler interface for Severity
func (*Severity) UnmarshalYAML ¶
UnmarshalYAML implements a YAML Unmarshaler for Severity
type TeamCityFormatter ¶
type TeamCityFormatter struct{}
TeamCityFormatter formats annotations as TeamCity service messages.
Reference:
func (TeamCityFormatter) Format ¶
func (TeamCityFormatter) Format(annotation *Annotation) string
Source Files