go-slog

README

go-slog

Tools and testing for log/slog (hereafter just slog) handlers.

Recent benchmark data is available via GitHub Pages.

See the source or documentation for more detailed documentation.

Table of Contents?

• auto-gen TOC: {:toc}

Repository Contents

• Test harness for benchmarking slog handler performance
• Test harness for verifying slog handler functionality
• Web Server that processes output of previous two steps and provides access to result.
• Static copies of server pages provided via GitHub Pages.
• Functions for use with slog.HandlerOptions.ReplaceAttr
• Utility to redirect internal gin logging to slog

Handler Benchmarks

Benchmarks of slog handlers can be done by creating simple _test.go files that utilize the bench/test.SlogBenchmarkSuite located in this repository. Usage details for this facility are provided in the README file located in the bench package directory.

Benchmarks are intended to compare multiple handlers. This repository is configured to test all known, functional slog handlers that generate JSON.

The benchmark data generated can be processed by two applications:

• tabular
  generates a set of tables, each of which compares handlers for a given benchmark test.
• server
  runs a simple web server showing the same tables plus bar charts and handler verification warnings.

Handler Verification

Verification of slog handlers can be done by creating simple _test.go files that utilize the verify/test.SlogTestSuite located in this repository. Usage details for this facility are provided in the README file located in the verify package directory.

Verification testing is intended to test a single handler or to compare multiple handlers. This repository is configured to test all known, functional slog handlers that generate JSON.

The tests implemented herein were inspired by:

• the slogtest application,
• rules specified in the log/slog.Hander and handler writing guide documentation,
• issues I noticed while exploring go-logging-benchmark
• as well as some other test cases that seemed useful.

Web Server

The cmd/server application is intended to process the benchmark and verification output and display it on a series of web pages. The pages display:

• handler data: benchmarks and warnings
• bench test data: benchmarks and warnings
• verification test data: warnings
• warning definitions and coverage

The benchmark data is displayed as a table (similar to cmd/tabular) and as a series of bar charts comparing tests for a handler or handlers for a test.

Generating GitHub Pages

Server pages are generated on a weekly basis using GitHub Actions and Pages. The GitHub Action:

• builds and runs:
  • handler benchmarks,
  • handler verifications, and
  • the cmd/server application
• at which point the wget tool is used to copy the server pages into the docs subdirectory.

The pages in the docs subdirectory are then vended by GitHub Pages.

Replace Attributes Functions

A small collection of functions in the replace package can be used with slog.HandlerOptions.ReplaceAttr. These functions were intended to "fix" some of the verification issues with various handlers. Unfortunately, other issues prevent these issues from being fixed:

• Attributes can't be directly removed, they can only be made empty, but some handlers tested don't remove empty attributes as they should so this fix doesn't work for them.
• Some handlers don't recognize slog.HandlerOptions.ReplaceAttr.
• Those that do don't always recognize them for the basic fields (time, level, message, and source).

Gin Integration

Package gin contains utilities for using slog with gin-gonic/gin. In particular, this package provides gin.Writer which can be used to redirect Gin-internal logging.

Caveats

JSON Only

The tests in this repository only apply to slog JSON output. Console output can come in a variety of formats and generally doesn't have a performance issue as only humans will look at it.

Who Am I?

Your response to this repository, especially if you are a slog handler author, may well be "who are you to make these rules?" This is a reasonable question.

The author has no authority to dictate slog handler behavior. The tests and warnings contained herein more or less defined themselves based on the behavior of various slog handlers under test.

Benchmark and verification tests come from slog documentation, the slogtest test harness, and tests embedded in betterstack-community/go-logging-benchmarks. Warnings generated by these tests pretty much defined themselves (with the author's help, of course).

Each test and/or warning is based on some sort of justification. This justification is reflected in documentation and comments throughout the code. It should be possible to follow this trail of bread crumbs to justify each test or warning. Whether the reader agrees with this justification is subjective.

The several levels of verification tests are defined based on the strength of justification:

• Required
  Justified from requirements in the slog.Handler documentation.
• Implied
  Implied by documentation but can't be considered required.
• Suggested
  Not mandated by any documentation or requirements. These are the ones that the author just made up because they seemed appropriate.
• Administrative
  Information about the tests or conflicts with other warnings.

As a slog Author

• You don't have to pay attention to any of this. Really.
• If you do pay attention, you should probably work down from Required warnings.
• Consider your users' viewpoint...

As a slog User

• Are you confident that the slog handler you choose will be fine forever?
• Consider the trade-off between performance and functionality.
  • Do you need faster logging without support for picky warnings?
  • Do you need full support of all verification tests at the cost of performance?
• If you need to swap out slog handlers will the new one support your usage of the old one?
  • Should your code use only generally supported features even if more useful ones are available?
  • Are you prepared to change logging statements to use a less functional handler?

IMHO

The author considers the interoperability of logging via slog to be very important, and possibly the best aspect of slog logging. Editing every log statement in a large project can be a real pain.

Links

Slog Documentation

• Documentation of log/slog
• Guide to Implementation of slog Handlers
• Test Harness slogtest

Slog Handlers

The following handlers are currently under test in this repository:

• chanchal/zaphandler
• log/slog.JSONHandler
• phsym/zeroslog
• samber/slog-zap
• samber/slog-zerolog
• samber/slog-logrus

Handlers that have been investigated and found wanting:

• darvaza handlers are based on a different definition of log/slog as an interface that is not compatible with the "real" log/slog/Logger. Since the latter is not an interface there is no way to build a shim. In addition, there is no separate Handler object.

  • darvaza/logrus
  • darvaza/zap
  • darvaza/zerolog

• Some handlers are still using golang.org/x/exp/slog instead of the standard library log/slog:

  • galecore/xslog
  • evanphx/go-hclog-slog

Console handlers are not tested in this repository, but the author likes this one (and uses it in cmd/server):

• phsym/console-slog

Miscellaneous

• Awesome slog list of link to various slog-related projects and resources.
• Go Logging Benchmarks
  • Benchmarks of various Go logging packages (not just slog loggers).
  • Used GitHub Action in this project as template for generating GitHub Pages for the current repository.