FlowWatch

README

FlowWatch

FlowWatch is an abstraction layer for OpenTelemetry, standardizing tracing, logging (both local and remote), metrics, and exception handling across the company's ecosystem programs. Its goal is to simplify implementation and ensure consistent usage.

---

1. OpenTelemetry Integration

Setup

To set up OpenTelemetry, initialize it at the start of your program:

otelHelper.SetupOtelHelper()
defer otelHelper.Shutdown() // Recommended: Graceful shutdown at program end

Tracing

To start a trace, use the following methods:

tracer := otel.Tracer("TracerName")          // Initialize the tracer
ctx, span := tracer.Start(ctx, "SpanName")  // Start a new span
defer span.End()                            // End the span (defer recommended)

Note: Use the updated context ctx in all subsequent operations to ensure that logs and spans are properly associated.

---

2. Logging

Example

To log messages, retrieve the logging helper and use the appropriate log level:

lh := loggingHelper.GetLogHelper()
lh.Info(ctx, "Info log message")
lh.Warn(ctx, "Warning log message")

Note: Supported log levels are Debug, Info, Warn, Error, and Fatal.

---

3. Exception Handling

• Recommendation: Use pkg/errors for creating and wrapping errors:

err := errors.Wrap(CustomError1, "Additional context")

• Global Variables: Declare errors as global variables to ensure consistent error messages:

var CustomError1 = errors.New("Error message")

Logging an Error

if err != nil {
  lh.Error(ctx, err)
}

---

4. Example

package main

import (
  "context"
  "github.com/LucaSchmitz2003/FlowWatch/loggingHelper"
  "github.com/LucaSchmitz2003/FlowWatch/otelHelper"
  "github.com/pkg/errors"
  "go.opentelemetry.io/otel"
)

var (
  CustomError1 = errors.New("Error message")
  tracer       = otel.Tracer("TestTracer")
  logger       = loggingHelper.GetLogHelper()
)

func errorTest() error {
  // Something went wrong
  err := errors.Wrap(CustomError1, "Error in errorTest()")
  return err
}

func main() {
  ctx := context.Background()

  // Initialize the OpenTelemetry SDK connection to the backend
  otelHelper.SetupOtelHelper()
  defer otelHelper.Shutdown() // Defer the shutdown function to ensure a graceful shutdown of the SDK connection at the end

  // Create a sub-span
  ctx, span := tracer.Start(ctx, "Test span")
  defer span.End()

  // Call function, catch error and log it
  err := errorTest()
  if err != nil {
	  logger.Warn(ctx, err)
  }
}

---

5. Import in other projects

export GOPRIVATE=github.com/LucaSchmitz2003/*
GIT_SSH_COMMAND="ssh -v" go get github.com/LucaSchmitz2003/FlowWatch@main

6. Environment variables

OTEL_SERVICE_NAME="<name>"
OTEL_COLLECTOR_URL="<url>:<port>"
OTEL_SUPPORT_TLS=<bool>

Documentation

Index

• func SetLogLevel(level Level)
• type Level
  • func (l Level) String() string
• type LogHelper
  • func GetLogHelper() *LogHelper
  • func (lh *LogHelper) Debug(ctx context.Context, args ...interface{})
  • func (lh *LogHelper) Error(ctx context.Context, args ...interface{})
  • func (lh *LogHelper) Fatal(ctx context.Context, args ...interface{})
  • func (lh *LogHelper) Info(ctx context.Context, args ...interface{})
  • func (lh *LogHelper) Warn(ctx context.Context, args ...interface{})
• type LogrusContextHook
  • func (hook LogrusContextHook) Fire(entry *logrus.Entry) error
  • func (hook LogrusContextHook) Levels() []logrus.Level
• type LogrusOtelHook
  • func (hook LogrusOtelHook) Fire(entry *logrus.Entry) error
  • func (hook LogrusOtelHook) Levels() []logrus.Level
• type LogrusOtelShutdownHook
  • func (hook LogrusOtelShutdownHook) Fire(entry *logrus.Entry) error
  • func (hook LogrusOtelShutdownHook) Levels() []logrus.Level

Functions

func SetLogLevel

func SetLogLevel(level Level)

SetLogLevel updates the log level of the logger library.

Types

type Level

type Level uint32

Level is an enumeration for the log levels to abstract it from the logging library.

const (
	Debug Level = iota
	Info
	Warn
	Error
	Fatal
)

func (Level) String

func (l Level) String() string

String returns the string representation of the log level.

type LogHelper

type LogHelper struct {
	Logger *logrus.Logger
}

LogHelper is an abstraction for the Logger instance to enable simpler switching between logging libraries.

func GetLogHelper

func GetLogHelper() *LogHelper

GetLogHelper returns the LogHelper instance or creates a new one if it does not exist according to the singleton pattern.

func (*LogHelper) Debug

func (lh *LogHelper) Debug(ctx context.Context, args ...interface{})

Debug logs a message at the debug level.

func (*LogHelper) Error

func (lh *LogHelper) Error(ctx context.Context, args ...interface{})

Error logs a message at the error level.

func (*LogHelper) Fatal

func (lh *LogHelper) Fatal(ctx context.Context, args ...interface{})

Fatal logs a message at the fatal level.

func (*LogHelper) Info

func (lh *LogHelper) Info(ctx context.Context, args ...interface{})

Info logs a message at the info level.

func (*LogHelper) Warn

func (lh *LogHelper) Warn(ctx context.Context, args ...interface{})

Warn logs a message at the warning level.

type LogrusContextHook

type LogrusContextHook struct{}

LogrusContextHook is a hook for logrus that adds the file and line number to the log entry.

func (LogrusContextHook) Fire

func (hook LogrusContextHook) Fire(entry *logrus.Entry) error

Fire is called when the LogrusContextHook is activated (when a log entry is made).

func (LogrusContextHook) Levels

func (hook LogrusContextHook) Levels() []logrus.Level

Levels returns all log levels for which the LogrusContextHook should be activated (warning level and higher, because runtime.Caller is expensive and debug, because it should be disabled in production).

type LogrusOtelHook

type LogrusOtelHook struct{}

LogrusOtelHook is a hook for logrus that enables logging to OpenTelemetry.

func (LogrusOtelHook) Fire

func (hook LogrusOtelHook) Fire(entry *logrus.Entry) error

Fire is called when the LogrusOtelHook is activated (when a log entry is made).

func (LogrusOtelHook) Levels

func (hook LogrusOtelHook) Levels() []logrus.Level

Levels returns all log levels for which the LogrusOtelHook should be activated (warning level and higher).

type LogrusOtelShutdownHook

type LogrusOtelShutdownHook struct{}

LogrusOtelShutdownHook is a hook for logrus that ensures that the connection to OpenTelemetry is shut down properly.

func (LogrusOtelShutdownHook) Fire

func (hook LogrusOtelShutdownHook) Fire(entry *logrus.Entry) error

Fire is called when the LogrusOtelShutdownHook is activated (when a fatal log entry is made).

func (LogrusOtelShutdownHook) Levels

func (hook LogrusOtelShutdownHook) Levels() []logrus.Level

Levels returns all log levels for which the LogrusOtelShutdownHook should be activated (fatal level and higher since it terminates the program).