diagnosticism

Diagnosticism.Go

Basic diagnostic facilities, for Go

Table of Contents

• Introduction
• Installation
• Components
  • Constants
  • Functions
    • Contingent Reporting
    • Debug
    • Logging/Tracing
  • Interfaces
  • Structures
    • Logging/Tracing
    • Timing
• Examples
• Project Information
  • Where to get help
  • Contribution guidelines
  • Dependencies
    • Development Dependencies
  • Dependent projects
  • Related projects
  • License

Introduction

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.

Installation

Install:

go get "github.com/synesissoftware/Diagnosticism.Go"

Use:

import diagnosticism "github.com/synesissoftware/Diagnosticism.Go"

Components

Diagnosticism.Go provides components in the following categories:

• Contingent Reporting
• Diagnostic Logging
• Tracing

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.

Constants

No public constants are defined at this time.

Functions

The following functions are defined:

Contingent Reporting

// 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

Debug

// 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() string

Logging/Tracing

func 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

Interfaces

No public interface are defined at this time.

Structures

Logging/Tracing

// 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
}

Timing

// 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

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.

Project Information

Where to get help

GitHub Page

Contribution guidelines

Defect reports, feature requests, and pull requests are welcome on https://github.com/synesissoftware/Diagnosticism.Go.

Dependencies

• ver2go

Development Dependencies

• testify
• STEGoL

Dependent projects

• libpath.Go
• recls.Go

Related projects

• Diagnosticism
• Diagnosticism.Python
• Diagnosticism.Ruby

License

Diagnosticism.Go is released under the 3-clause BSD license. See LICENSE for details.