diag

Documentation

Overview

Package diag implements diagnostic functionality, which is a practitioner feedback mechanism for providers. It is designed for display in Terraform user interfaces, rather than logging based feedback, which is generally saved to a file for later inspection and troubleshooting.

Practitioner feedback for provider defined functions is provided by the [function.FuncError] type, rather than the diag.Diagnostic type.

Index

• type Diagnostic
• type DiagnosticWithPath
  • func NewAttributeErrorDiagnostic(path path.Path, summary string, detail string) DiagnosticWithPath
  • func NewAttributeWarningDiagnostic(path path.Path, summary string, detail string) DiagnosticWithPath
  • func WithPath(path path.Path, d Diagnostic) DiagnosticWithPath
• type Diagnostics
  • func (diags *Diagnostics) AddAttributeError(path path.Path, summary string, detail string)
  • func (diags *Diagnostics) AddAttributeWarning(path path.Path, summary string, detail string)
  • func (diags *Diagnostics) AddError(summary string, detail string)
  • func (diags *Diagnostics) AddWarning(summary string, detail string)
  • func (diags *Diagnostics) Append(in ...Diagnostic)
  • func (diags Diagnostics) Contains(in Diagnostic) bool
  • func (diags Diagnostics) Equal(other Diagnostics) bool
  • func (diags Diagnostics) Errors() Diagnostics
  • func (diags Diagnostics) ErrorsCount() int
  • func (diags Diagnostics) HasError() bool
  • func (diags Diagnostics) Warnings() Diagnostics
  • func (diags Diagnostics) WarningsCount() int
• type ErrorDiagnostic
  • func NewErrorDiagnostic(summary string, detail string) ErrorDiagnostic
  • func (d ErrorDiagnostic) Detail() string
  • func (d ErrorDiagnostic) Equal(other Diagnostic) bool
  • func (d ErrorDiagnostic) Severity() Severity
  • func (d ErrorDiagnostic) Summary() string
• type Severity
  • func (s Severity) String() string
• type WarningDiagnostic
  • func NewWarningDiagnostic(summary string, detail string) WarningDiagnostic
  • func (d WarningDiagnostic) Detail() string
  • func (d WarningDiagnostic) Equal(other Diagnostic) bool
  • func (d WarningDiagnostic) Severity() Severity
  • func (d WarningDiagnostic) Summary() string

Types

type Diagnostic

type Diagnostic interface {
	// Severity returns the desired level of feedback for the diagnostic.
	Severity() Severity

	// Summary is a short description for the diagnostic.
	//
	// Typically this is implemented as a title, such as "Invalid Resource Name",
	// or single line sentence.
	Summary() string

	// Detail is a long description for the diagnostic.
	//
	// This should contain all relevant information about why the diagnostic
	// was generated and if applicable, ways to prevent the diagnostic. It
	// should generally be written and formatted for human consumption by
	// practitioners or provider developers.
	Detail() string

	// Equal returns true if the other diagnostic is wholly equivalent.
	Equal(Diagnostic) bool
}

Diagnostic is an interface for providing enhanced feedback.

These are typically practitioner facing, however it is possible for functionality, such as validation, to use these to change behaviors or otherwise have these be manipulated or removed before being presented.

See the ErrorDiagnostic and WarningDiagnostic concrete types for generic implementations.

To add path information to an existing diagnostic, see the WithPath() function.

type DiagnosticWithPath

type DiagnosticWithPath interface {
	Diagnostic

	// Path points to a specific value within an aggregate value.
	//
	// If present, this enables the display of source configuration context for
	// supporting implementations such as Terraform CLI commands.
	Path() path.Path
}

DiagnosticWithPath is a diagnostic associated with an attribute path.

This attribute information is used to display contextual source configuration to practitioners.

func NewAttributeErrorDiagnostic

func NewAttributeErrorDiagnostic(path path.Path, summary string, detail string) DiagnosticWithPath

NewAttributeErrorDiagnostic returns a new error severity diagnostic with the given summary, detail, and path.

func NewAttributeWarningDiagnostic

func NewAttributeWarningDiagnostic(path path.Path, summary string, detail string) DiagnosticWithPath

NewAttributeWarningDiagnostic returns a new warning severity diagnostic with the given summary, detail, and path.

func WithPath

func WithPath(path path.Path, d Diagnostic) DiagnosticWithPath

WithPath wraps a diagnostic with path information or overwrites the path.

type Diagnostics

type Diagnostics []Diagnostic

Diagnostics represents a collection of diagnostics.

While this collection is ordered, the order is not guaranteed as reliable or consistent.

func (*Diagnostics) AddAttributeError

func (diags *Diagnostics) AddAttributeError(path path.Path, summary string, detail string)

AddAttributeError adds a generic attribute error diagnostic to the collection.

func (*Diagnostics) AddAttributeWarning

func (diags *Diagnostics) AddAttributeWarning(path path.Path, summary string, detail string)

AddAttributeWarning adds a generic attribute warning diagnostic to the collection.

func (*Diagnostics) AddError

func (diags *Diagnostics) AddError(summary string, detail string)

AddError adds a generic error diagnostic to the collection.

func (*Diagnostics) AddWarning

func (diags *Diagnostics) AddWarning(summary string, detail string)

AddWarning adds a generic warning diagnostic to the collection.

func (*Diagnostics) Append

func (diags *Diagnostics) Append(in ...Diagnostic)

Append adds non-empty and non-duplicate diagnostics to the collection.

func (Diagnostics) Contains

func (diags Diagnostics) Contains(in Diagnostic) bool

Contains returns true if the collection contains an equal Diagnostic.

func (Diagnostics) Equal

func (diags Diagnostics) Equal(other Diagnostics) bool

Equal returns true if all given diagnostics are equivalent in order and content, based on the underlying (Diagnostic).Equal() method of each.

func (Diagnostics) Errors

func (diags Diagnostics) Errors() Diagnostics

Errors returns all the Diagnostic in Diagnostics that are SeverityError.

func (Diagnostics) ErrorsCount

func (diags Diagnostics) ErrorsCount() int

ErrorsCount returns the number of Diagnostic in Diagnostics that are SeverityError.

func (Diagnostics) HasError

func (diags Diagnostics) HasError() bool

HasError returns true if the collection has an error severity Diagnostic.

func (Diagnostics) Warnings

func (diags Diagnostics) Warnings() Diagnostics

Warnings returns all the Diagnostic in Diagnostics that are SeverityWarning.

func (Diagnostics) WarningsCount

func (diags Diagnostics) WarningsCount() int

WarningsCount returns the number of Diagnostic in Diagnostics that are SeverityWarning.

type ErrorDiagnostic

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

ErrorDiagnostic is a generic diagnostic with error severity.

func NewErrorDiagnostic

func NewErrorDiagnostic(summary string, detail string) ErrorDiagnostic

NewErrorDiagnostic returns a new error severity diagnostic with the given summary and detail.

func (ErrorDiagnostic) Detail

func (d ErrorDiagnostic) Detail() string

Detail returns the diagnostic detail.

func (ErrorDiagnostic) Equal

func (d ErrorDiagnostic) Equal(other Diagnostic) bool

Equal returns true if the other diagnostic is wholly equivalent.

func (ErrorDiagnostic) Severity

func (d ErrorDiagnostic) Severity() Severity

Severity returns the diagnostic severity.

func (ErrorDiagnostic) Summary

func (d ErrorDiagnostic) Summary() string

Summary returns the diagnostic summary.

type Severity

type Severity int

Severity represents the level of feedback for a diagnostic.

Each severity implies behavior changes for the feedback and potentially the further execution of logic.

const (
	// SeverityInvalid represents an undefined severity.
	//
	// It should not be used directly in implementations.
	SeverityInvalid Severity = 0

	// SeverityError represents a terminating condition.
	//
	// This can cause a failing status code for command line programs.
	//
	// Most implementations should return early when encountering an error.
	SeverityError Severity = 1

	// SeverityWarning represents a condition with explicit feedback.
	//
	// Most implementations should continue when encountering a warning.
	SeverityWarning Severity = 2
)

func (Severity) String

func (s Severity) String() string

String returns a textual representation of the severity.

type WarningDiagnostic

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

WarningDiagnostic is a generic diagnostic with warning severity.

func NewWarningDiagnostic

func NewWarningDiagnostic(summary string, detail string) WarningDiagnostic

NewErrorDiagnostic returns a new warning severity diagnostic with the given summary and detail.

func (WarningDiagnostic) Detail

func (d WarningDiagnostic) Detail() string

Detail returns the diagnostic detail.

func (WarningDiagnostic) Equal

func (d WarningDiagnostic) Equal(other Diagnostic) bool

Equal returns true if the other diagnostic is wholly equivalent.

func (WarningDiagnostic) Severity

func (d WarningDiagnostic) Severity() Severity

Severity returns the diagnostic severity.

func (WarningDiagnostic) Summary

func (d WarningDiagnostic) Summary() string

Summary returns the diagnostic summary.