Basic diagnostic facilities, for Go
Diagnosticism provides low-level diagnostics facilities to support library programming. The first Diagnosticism library was a C library with a C++ wrapper. There have been several implementations in other languages. Diagnosticism.Go is the Go version.
Install:
go get "github.com/synesissoftware/Diagnosticism.Go"Use:
import d "github.com/synesissoftware/Diagnosticism.Go"Diagnosticism.Go provides components in the following categories:
- Contingent Reporting
- Diagnostic Logging
- Tracing
- Utilities / helpers
NOTE: for the moment, the Diagnostic Logging facilities emit to the standard error stream, via the Contingent Reporting API. In the near future this will be changed to work with more sophisticated logging libraries, including the standard logging facilities and the (as yet to be released) Pantheios.Go.
No public constants are defined at this time.
The following functions are defined:
// Issues the given message and then end the process.
//
// If [IsMirroringToLog] is `true`, then the message will be emitted to the
// log before terminating.
func Abort(message string)
// Issues a formatted message and then end the process.
//
// If [IsMirroringToLog] is `true`, then the message will be emitted to the
// log before terminating.
func Abortf(format string, args ...any)
// Issues the given message to the standard error stream.
//
// If [IsMirroringToLog] is `true`, then the message will also be emitted to
// the log.
func ConRep(message string)
// Issues a formatted message to the standard error stream.
//
// If [IsMirroringToLog] is `true`, then the message will also be emitted to
// the log.
func ConRepf(format string, args ...any)
// Sets whether should mirror contingent reports (via [ConRep], [ConRepf],
// [Abort], [Abortf]) to the log.
func MirrorToLog(enable bool) bool
// Indicates whether mirroring contingent reports (via [ConRep], [ConRepf],
// [Abort], [Abortf]) to the log.
func IsMirroringToLog() bool// Obtains the file information for the calling function.
func File() string
// Obtains the file and line information for the calling function.
func FileLine() string
// Obtains the file, line, and function information for the calling
// function.
func FileLineFunction() string
// Obtains the line information for the calling function.
func Line() int
// Obtains the line and function information for the calling function.
func LineFunction() stringfunc SetBackEnd(be *BackEnd)
// Obtains the current backend handler function.
func GetBackEndHandlerFunc() *BackEnd
// Sets whether logging is enabled.
func EnableLogging(enable bool)
// Indicates whether logging is enabled.
func IsLoggingEnabled() bool
// Logs the arguments at the given severity.
func Log(severity severity.Severity, args ...any)
// Logs the formatted arguments at the given severity.
func Logf(severity severity.Severity, format string, args ...any)func EnableTracing(enable bool) bool
func IsTracingEnabled() bool
// Creates an argument descriptor that will trace the argument name, type,
// and value.
func Trarg(name string, value any) TraceArgument
// Creates an argument descriptor that will trace the argument name, but not
// type and value.
func TrargNameOnly(name string, value any) TraceArgument
// Creates an argument descriptor that will trace the argument name and
// type, but not value.
func TrargNameTypeOnly(name string, value any) TraceArgument
func TrargTrunc(name string, value any) TraceArgument
// Provides named-argument tracing of a function/method, as in:
//
// import d "github.com/synesissoftware/Diagnosticism.Go"
//
// func SomeFunction(x, y int, order string) {
//
// d.Trace(d.FileLineFunction(),
// d.Trarg("x", x),
// d.Trarg("y", y),
// d.TrargNameTypeOnly("order", order),
// )
//
// . . . impl. of SomeFunc()
// }
//
// The first parameter `function_name` is a string, and the remaining
// parameters are a variable length list of TraceArgument instances, which
// may be created using the `Trarg()` and `TrargNameOnly()` functions
func Trace(function_name string, args ...TraceArgument)// Middleware adapter that causes a request to be logged, according to the
// given flags and options
//
// Parameters:
// - +flags+ (LogRequestFlags) A combination of flags that moderate the behaviour
// - +options+ Optional arguments (see below)
//
// Options:
// - * (severity.Severity) The first option of this type is used for before and/or after logging; if none specified, before and/or after logging is done using severity.Informational
func LogRequest(flags LogRequestFlags, options ...any) func(http.Handler) http.Handler// Obtains the stock string form of a severity.
func TranslateStockSeverity(severity Severity) string// Returns the string form of v in base 10, with thousands separators.
func ItoaThousands[T int | int8 | int16 | int32 | int64 | uint | uint8 | uint16 | uint32 | uint64 | uintptr](v T) stringNo public interface are defined at this time.
// Type describing an entry to be processed by the logging back-end.
type BackEndEntry struct {
// The severity of the log statement.
Severity severity.Severity
// The time at which the log statement was consumed.
Time time.Time
// The statement message.
Message string
}
// Backend log handler.
type BackEnd struct {
// Flags that control the back-end behaviour/features
Flags BackEndFlag
// The back-end handler function. May not be nil
HandlerFunc BackEndHandlerFunc
// The string to be used as a separator. If the empty string, then the
// default separator - " : " - is used. If no separator is desired, the
// NoPrefixSeparator flag must be specified
PrefixSeparator string
}// Decimal Order-Of-Magnitude frequency histoGRAM
//
// # Note:
// This is a Go port of the equivalent `stlsoft::doomgram` class from the
// **STLSoft** libraries (https://github.com/synesissoftware/STLSoft-1.11).
type DOOMGram struct {
}Examples are provided in the examples directory, along with a markdown description for each. A detailed list TOC of them is provided in EXAMPLES.md.
Defect reports, feature requests, and pull requests are welcome on https://github.com/synesissoftware/Diagnosticism.Go.
Diagnosticism.Go is released under the 3-clause BSD license. See LICENSE for details.