slogxslack

README

go-slogx-slack

Handler for the `go.innotegrity.dev/slogx` package which enables logging to Slack via a webhook URL.

---

---

Table of Contents

• 👁️ Overview
• ✅ Requirements
• 📃 License
• ❓ Questions, Issues and Feature Requests

👁️ Overview

go-slogx-slack is a handler for the go.innotegrity.dev/slogx package. It allows you to use the slogx or log/slog library to log messages to Slack by using a webhook URL.

Please review the module documentation for details on how to properly the functions and classes contained in this module.

✅ Requirements

This module is supported for Go v1.21 and later.

📃 License

This module is distributed under the MIT License.

❓ Questions, Issues and Feature Requests

If you have questions about this project, find a bug or wish to submit a feature request, please submit an issue.

Documentation

Index

• Constants
• func DefaultSlackMessageFormatter() *slackMessageFormatter
• func NewSlackHandler(opts SlackHandlerOptions) (*slackHandler, error)
• func NewSlackMessageFormatter(opts SlackMessageFormatterOptions) *slackMessageFormatter
• type SlackHandlerOptions
  • func DefaultSlackHandlerOptions() SlackHandlerOptions
  • func GetSlackHandlerOptionsFromContext(ctx context.Context) *SlackHandlerOptions
  • func (o *SlackHandlerOptions) AddToContext(ctx context.Context) context.Context
• type SlackMessageFormatter
• type SlackMessageFormatterOptions
  • func DefaultSlackMessageFormatterOptions() SlackMessageFormatterOptions
  • func GetSlackMessageFormatterOptionsFromContext(ctx context.Context) *SlackMessageFormatterOptions
  • func (o *SlackMessageFormatterOptions) AddToContext(ctx context.Context) context.Context

Constants

const (
	// SlackMessageFormatterSourcePrefix is the default text to prepend when outputting the source location.
	SlackMessageFormatterSourcePrefix = "Source:\t\t\t"

	// SlackMessageFormatterTimeAttr is the default text to prepend when outputting the time of the record.
	SlackMessageFormatterTimePrefix = "Occurred at:\t"
)

Functions

func DefaultSlackMessageFormatter

func DefaultSlackMessageFormatter() *slackMessageFormatter

DefaultSlackMessageFormatter returns a Slack message formatter with typical defaults already set.

func NewSlackHandler

func NewSlackHandler(opts SlackHandlerOptions) (*slackHandler, error)

NewSlackHandler creates a new handler object.

func NewSlackMessageFormatter

func NewSlackMessageFormatter(opts SlackMessageFormatterOptions) *slackMessageFormatter

NewSlackMessageFormatter creates and returns a new slack message formatter.

Types

type SlackHandlerOptions

type SlackHandlerOptions struct {
	// EnableAsync will execute the Handle() function in a separate goroutine.
	//
	// When async is enabled, you should be sure to call the Shutdown() function or use the slogx.Shutdown()
	// function to ensure all goroutines are finished and any pending records have been written.
	EnableAsync bool

	// HTTPClient allows for the use of a custom HTTP client for posting the webhook message.
	//
	// If nil, http.DefaultClient is used.
	HTTPClient *http.Client

	// Level is the minimum log level to write to the handler.
	//
	// By default, the level will be set to slog.LevelInfo if not supplied.
	Level slog.Leveler

	// RecordFormatter specifies the formatter to use to format the record before sending it to Slack.
	//
	// If no formatter is supplied, DefaultSlackMessageFormatter is used to format the output.
	RecordFormatter SlackMessageFormatter

	// WebhookURL is the Slack webhook URL to use in order to send the message.
	//
	// This is a required option.
	WebhookURL string
}

SlackHandlerOptions holds the options for the Slack handler.

func DefaultSlackHandlerOptions

func DefaultSlackHandlerOptions() SlackHandlerOptions

DefaultSlackHandlerOptions returns a default set of options for the handler.

func GetSlackHandlerOptionsFromContext

func GetSlackHandlerOptionsFromContext(ctx context.Context) *SlackHandlerOptions

GetSlackHandlerOptionsFromContext retrieves the options from the context.

If the options are not set in the context, a set of default options is returned instead.

func (*SlackHandlerOptions) AddToContext

func (o *SlackHandlerOptions) AddToContext(ctx context.Context) context.Context

AddToContext adds the options to the given context and returns the new context.

type SlackMessageFormatter

type SlackMessageFormatter interface {
	// FormatRecord should take the data from the record and format it as needed, storing it in the returned
	// webhook message.
	FormatRecord(context.Context, time.Time, slogx.Level, uintptr, string, []slog.Attr) (*slack.WebhookMessage, error)
}

SlackMessageFormatter describes the interface a formatter which outputs a record to a Slack message must implement.

type SlackMessageFormatterOptions

type SlackMessageFormatterOptions struct {
	// ApplicationIconURL is a URL to an icon to display next to the application name in the output message.
	//
	// If this is empty, no icon is shown next to the application name.
	ApplicationIconURL string

	// ApplicationName is the name of the application to display above the message.
	//
	// If this is empty, no application name is shown.
	ApplicationName string

	// AttrFormatter is the middleware formatting function to call to format any attribute.
	//
	// Attribute values should be resolved by the handler before formatting. Any value returned by the formatter should
	// be resolved prior to return.
	//
	// If nil, attributes are simply printed unchanged.
	AttrFormatter formatter.FormatAttrFn

	// IgnoreAttrs is a list of regular expressions to use for matching attributes which should not be printed.
	//
	// Note that this only applies to attributes and not defined parts like the level, message, source or time.
	//
	// If any regular expression does not compile, it is simply ignored.
	IgnoreAttrs []string

	// IncludeAttrs indicates whether or not to include attributes in the Slack message.
	IncludeAttrs bool

	// IncludeSource indicates whether or not to include source file location information in the Slack mesage.
	IncludeSource bool

	// LevelFormatter is the middleware formatting function to call to format the level.
	//
	// If nil, the level is printed using FormatLevelValueDefault().
	LevelFormatter formatter.FormatLevelValueFn

	// MessageFormatter is the middlware formatting function to call to format the message.
	//
	// If nil, the message is printed as-is.
	MessageFormatter formatter.FormatMessageValueFn

	// SortAttrs indicates whether or not to sort the attributes alphabetically before adding them to the message.
	SortAttrs bool

	// SourcePrefix is the text to prefix the source information with in the output message.
	//
	// If this is empty, the default value of "Source:\t\t\t" is used.
	SourcePrefix string

	// SourceFormatter is the middleware formatting function to call to format the source code location where the record
	// was created.
	//
	// If nil, the source code location is printed using FormatSourceValueDefault().
	SourceFormatter formatter.FormatSourceValueFn

	// SpecificAttrFormatter is the middleware formatting function to call to format a specific attribute.
	//
	// The key for the map corresponds to the name of the specific attribute to format. If an attribute is nested within
	// a group, use a single period (.) to designate the group and attribute (eg: GROUP.ATTRIBUTE). Nested groups use
	// the same format (eg: GROUP1.GROUP2.ATTRIBUTE).
	//
	// Attribute values should be resolved by the handler before formatting. Any value returned by the formatter should
	// be resolved prior to return.
	//
	// If nil or if the attribute does not exist in the map, the default is to fall back to the AttrFormatter function.
	SpecificAttrFormatter map[string]formatter.FormatAttrFn

	// TimePrefix is the text to prefix the record timestamp with in the output message.
	//
	// If this is empty, the default value of "Occurred at:\t" is used.
	TimePrefix string

	// TimeFormatter is the middleware formatting function to call to the time of the record.
	//
	// If nil, the time is printed using FormatTimeValueDefault().
	TimeFormatter formatter.FormatTimeValueFn
}

SlackMessageFormatterOptions holds the options for the message formatter.

func DefaultSlackMessageFormatterOptions

func DefaultSlackMessageFormatterOptions() SlackMessageFormatterOptions

DefaultSlackMessageFormatterOptions returns a default set of options for the Slack message formatter.

func GetSlackMessageFormatterOptionsFromContext

func GetSlackMessageFormatterOptionsFromContext(ctx context.Context) *SlackMessageFormatterOptions

GetSlackMessageFormatterOptionsFromContext retrieves the options from the context.

If the options are not set in the context, a set of default options is returned instead.

func (*SlackMessageFormatterOptions) AddToContext

func (o *SlackMessageFormatterOptions) AddToContext(ctx context.Context) context.Context

AddToContext adds the options to the given context and returns the new context.