separates functionality by packages: this allows clients importing just the bits they need without bringing all the transitive module dependencies
extensible configuration API: Using a fluent-API we can add new options without breaking API or being forced to leave a trail of deprecated methods.
Zerolog
The main problems is v1 didn't offer any API to have cobrautil consumers adjust how the logger was configured. This is important as zerolog provides a vast API with many knobs to tweak.
a fluent API is offered so that cobrautil/zerolog can be extended with options as the need arises.
v1 assumed the consumer would use the zerolog/log global instance package. This forces the consuming application to use that global instance. The WithTarget option offers a callback when the logger is instantiated, so e.g. consumers can cache the instance somewhere else. It continues to default to that global instance.
v1 used zerolog global level. This is an unexpected side-effect the consumer may not want, specially given cobrautil is creating an instance of a zerolog Logger. The implementation now adjusts the level on the logger instance instead.
v1 methods are provided to offer an easy path of migration to v2.
WithAsync configures the logger to be non-blocking, implemented using diode buffered-ring. This is default by default to retain v1 behaviour.
Closes https://github.com/jzelinskie/cobrautil/issues/17
Main design choices
Zerolog
The main problems is v1 didn't offer any API to have
cobrautilconsumers adjust how the logger was configured. This is important as zerolog provides a vast API with many knobs to tweak.cobrautil/zerologcan be extended with options as the need arises.zerolog/logglobal instance package. This forces the consuming application to use that global instance. TheWithTargetoption offers a callback when the logger is instantiated, so e.g. consumers can cache the instance somewhere else. It continues to default to that global instance.Logger. The implementation now adjusts the level on the logger instance instead.WithAsyncconfigures the logger to be non-blocking, implemented using diode buffered-ring. This is default by default to retain v1 behaviour.See how it's used in https://github.com/authzed/spicedb/pull/844/files#diff-df0635588ca5d6a577487faacc185c3838a3fe2b321660c36372541797c54c74R59-R67
OTel
zerologand replaces withgo-log/logrWithLoggermakes it possible to set the global logger used by the OTel librarydebugHTTP
WithLoggerallows injecting a customgo-log/logrvalueWithHandlerallows injecting ahttp.Handlerinto thehttp.Serverto be createddebuginstead ofinfo. Can be tweaked withWithPreRunLevelwarnlevel logging for non-https configuration moves topreRunLevel. Insecure http is used behind load-balancers that do TLS offloading.gRPC
WithLoggerallows injecting a customgo-log/logrvaluedebuginstead ofinfo. Can be tweaked withWithPreRunLevelwarnlevel logging for non-https configuration moves topreRunLevel. Insecure http is used behind load-balancers that do TLS offloading.