{"id":23508984,"url":"https://github.com/maxbolgarin/logze","last_synced_at":"2025-05-13T15:35:58.742Z","repository":{"id":257121032,"uuid":"850626055","full_name":"maxbolgarin/logze","owner":"maxbolgarin","description":"Structural logging with zerolog efficiency and slog interface","archived":false,"fork":false,"pushed_at":"2025-03-09T10:08:13.000Z","size":35,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"v2","last_synced_at":"2025-03-09T11:17:47.447Z","etag":null,"topics":["go","golang","logging","zerolog"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/maxbolgarin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-09-01T10:23:01.000Z","updated_at":"2025-03-09T10:06:43.000Z","dependencies_parsed_at":"2024-09-14T23:54:01.371Z","dependency_job_id":"b0c276b2-db89-4422-87e1-ee91af929b86","html_url":"https://github.com/maxbolgarin/logze","commit_stats":null,"previous_names":["maxbolgarin/logma"],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxbolgarin%2Flogze","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxbolgarin%2Flogze/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxbolgarin%2Flogze/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxbolgarin%2Flogze/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maxbolgarin","download_url":"https://codeload.github.com/maxbolgarin/logze/tar.gz/refs/heads/v2","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253971097,"owners_count":21992647,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["go","golang","logging","zerolog"],"created_at":"2024-12-25T11:36:17.059Z","updated_at":"2025-05-13T15:35:58.711Z","avatar_url":"https://github.com/maxbolgarin.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# logze\n\n[![Go Version][version-img]][doc] [![GoDoc][doc-img]][doc] [![Build][ci-img]][ci] [![GoReport][report-img]][report]\n\n`logze` is a logging package that wraps the efficient [zerolog](https://github.com/rs/zerolog), providing a user-friendly interface similar to [slog](https://pkg.go.dev/golang.org/x/exp/slog). It offers the performance and features of zerolog with an interface that developers familiar with slog can easily adapt to.\n\n\n## Table of Contents\n\n- [Why you should try](#why-you-should-try)\n- [Installation](#installation)\n- [Usage](#usage)\n  - [Creating a Logger](#creating-a-logger)\n  - [Logging Messages](#logging-messages)\n  - [Logging Messages with formatting](#logging-messages-with-formatting)\n  - [Global logger usage](#global-logger-usage)\n  - [Configuration Options](#configuration-options)\n- [Pros and Cons](#pros-and-cons)\n- [Using Diode](#using-diode)\n- [Benchmarks](#benchmarks)\n- [Contributing](#contributing)\n- [License](#license)\n\n\n## Why you should try\n\nIf you want to log an error in `zerolog` you will write something like this:\n\n```go\nlog.Error().Err(err).Str(\"address\", \"127.0.0.1\").Int(\"retry\", n).Msg(\"cannot start server\")\n```\n\nThis is a quite long piece of code and you should remember the names of these methods. Let's look at a `logze` example:\n\n```go\nlogze.Err(err, \"cannot start server\", \"address\", \"127.0.0.1\", \"retry\", n)\n```\n\nFirstly, it is shorter. Secondly, you call only one method, which names `Err`, like an `err` that you want to log.\n\nIn other hand, you may say, that it is better to use `slog` with the similar interface instead of `logze`. But `logze` also provides a `zerolog` efficency — it is 3 times faster that `slog` and only 15% slower that `zerolog` due to using `Fields()` instead of separate method for each type.\n\n\n\n## Installation\n\nTo install `logze`, use:\n\n```bash\ngo get -u github.com/maxbolgarin/logze/v2\n```\n\n\n## Usage\n\n### Creating a Logger\n\nTo start using `logze` in your project, you can initialize a logger as follows:\n\n```go\npackage main\n\nimport (\n\t\"github.com/maxbolgarin/logze/v2\"\n)\n\nfunc main() {\n\tlogger := logze.New(logze.C().WithConsoleJSON(), \"application\", \"logze-example\")\n\t\n\tlogger.Info(\"Starting application\", \"version\", \"1.0.0\")\n}\n\n// Output: {\"level\":\"info\",\"message\":\"Starting application\",\"version\":\"1.0.0\",\"application\":\"logze-example\",\"time\":\"2023-08-24T15:30:00Z\"}\n```\n\n\n### Logging Messages\n\nOnce you have a logger, you can log messages at various levels:\n\n```go\nlogger.Trace(\"Trace application\", \"version\", \"1.0.0\")\nlogger.Debug(\"Debugging application start\", \"version\", \"1.0.0\") \nlogger.Info(\"Application started successfully\", \"number\", 123) \nlogger.Warn(\"Low memory warning\", \"data\", map[string]int{\"key1\": 1, \"key2\": 2}) \nlogger.Error(\"Disk space low\", \"error\", errors.New(\"disk space error\")) \nlogger.Err(errors.New(\"disk space error\"), \"disk space low\") \n\n/* Example Output:\n{\"level\":\"trace\",\"caller\":\"/Users/alex/code/logze/logze_test.go:210\",\"time\":\"2024-12-12T17:24:24+03:00\",\"message\":\"Trace application\",\"version\":\"1.0.0\"}\n{\"level\":\"debug\",\"message\":\"Debugging application start\",\"version\":\"1.0.0\",\"time\":\"2023-08-24T15:30:00Z\"}\n{\"level\":\"info\",\"message\":\"Application started successfully\",\"number\":123,\"time\":\"2023-08-24T15:30:00Z\"}\n{\"level\":\"warning\",\"message\":\"Low memory warning\",\"data\":{\"key1\":1,\"key2\":2},\"time\":\"2023-08-24T15:30:00Z\"}\n{\"level\":\"error\",\"message\":\"Disk space low\",\"error\":\"disk space error\",\"time\":\"2023-08-24T15:30:00Z\"}\n{\"level\":\"error\",\"message\":\"disk space low\",\"error\":\"disk space error\",\"time\":\"2023-08-24T15:30:00Z\"}\n*/\n```\n\n\n### Logging Messages with formatting\n\nYou can also log messages with formatting and fields in the structured way: you add formatting args and then key-value pairs. For example:\n\n```go\nlogger.Debugf(\"Debugging application start at %s\", time.Now(), \"version\", \"1.0.0\")\nlogger.Infof(\"Application %s started successfully\", \"name\", \"number\", 123)\nlogger.Warnf(\"Low memory warning %d times\", times)\n\n// {\"level\":\"debug\",\"message\":\"Debugging application start at 2023-08-24T15:30:00Z\",\"version\":\"1.0.0\",\"time\":\"2023-08-24T15:30:00Z\"}\n// {\"level\":\"info\",\"message\":\"Application name started successfully\",\"number\":123,\"time\":\"2023-08-24T15:30:00Z\"}\n// {\"level\":\"warning\",\"message\":\"Low memory warning 3 times\",\"time\":\"2023-08-24T15:30:00Z\"}\n```\n\n\n### Global logger usage\n\nYou can use the global logger from `logze` package instead of creating a new one:\n\n```go\n// Init global logger with trace level and one field pair (optional to provide options and fields)\nlogze.Init(logze.NewConfig().WithConsole().WithLevel(logze.TraceLevel), \"foo\", \"bar\")\n\n// Trace log will print Caller\nlogze.Trace(\"trace message\")\n\n// Example of logging an error\nlogze.Err(errm.New(\"some_error\"), \"message\")\n\n\n// Here is the result\t\n// 10:32:57 TRC test/main.go:16 \u003e trace message foo=bar\n// 10:32:57 ERR message error=some_error foo=bar\n```\n\n\n### Configuration Options\n\nYou can configure the logger with various options:\n\n- **Log Level**: Set the log level (`trace`, `debug`, `info`, `warn`, `error`, `fatal`).\n- **Many Output Writers**: Direct logs to console, files or network writers, you can provide as many `io.Writer` as you want.\n- **Ignore Messages**: Ignore specific log messages using `WithToIgnore`, that will check using `strings.Contains` on log message.\n- **Error Counter**: Add error counters using `WithErrorCounter` or `WithSimpleErrorCounter`; it may be useful for metrics to count errors.\n- **Stack Trace**: Enable/disable stack trace of errors; you can use [errm](https://github.com/maxbolgarin/errm) to get stack trace out of the box.\n- **Diode Buffering**: Enable/disable and configure diode buffering.\n\nExample:\n\n```go\nconfig := logze.NewConfig(w1, w2).\n    WithConsole().\n\tWithLevel(logze.DebugLevel).\n\tWithToIgnore(\"ignore me\").\n\tWithSimpleErrorCounter().\n    WithStackTrace().\n\tWithDiodeSize(10000)\n\nlogger := logze.New(config)\n```\n\n\n## Pros and Cons\n\n### Pros\n\n- **High Performance**: 3 times faster than `slog`, leveraging `zerolog` efficient engine.\n- **Structured Logging**: Native support for key-value pairs with any type of value.\n- **Easy Transition**: Compatible interface with `slog`.\n- **Easy Configuration**: Simplified configuration and initialization process.\n- **Diode Buffering**: Supports non-blocking IO operations for high performance.\n\n### Cons\n\n- **Slight Overhead**: Approximately 15% slower than raw `zerolog` due to the usage of fields instead of typed methods.\n- **Complexity**: Advanced features such as diode might be complex for new users.\n\n\n## Using Diode \n\nBy default, `logze` uses diode buffering to prevent blocking on log IO operations. This ensures high throughput but requires careful shutdown handling to prevent log loss. It's crucial to note that if your application shuts down immediately after logging, some log messages might be lost. This can be mitigated waiting for flushing logs or disabling the diode feature. Diode also can drop messages if too many logs are generated in a short span. \n\nTo disable diode buffering:\n\n```go\nconfig := logze.NewConfig().WithNoDiode()\nlogger := logze.New(config)\n```\n\n## Benchmarks\n\nThoughts from benchmarks:\n* `logze` is about 3 times faster than `slog` and for 15% slower than `zerolog`\n* format methods like `logze.Infof` or `Msgf` doesn't add big overhead (only 30% slower and +1 alloc)\n* stack trace is very slow in `logze` and `zerolog`\n* console writer is very slow in `logze` and `zerolog` and should be used only in development (that the case when slog wins over `logze` - if you want to use text writer in production)\n* `logze.Err` is slightly faster that `logze.Error`\n\n\nHere is result of `go test -bench=. -benchmem -benchtime=2s`:\n\n```\ngoos: darwin\ngoarch: arm64\ncpu: Apple M1 Pro\n```\n\nLogging `Info` and two fields:\n```text\nBenchmarkZerologInfo-8                  14365629               151.3 ns/op             0 B/op          0 allocs/op\nBenchmarkLogzeInfo-8                    13851320               171.5 ns/op             0 B/op          0 allocs/op\nBenchmarkSLogInfo-8                      4491897               533.2 ns/op             0 B/op          0 allocs/op\n```\n\nLogging `Infof` (formatted) and two fields:\n```text\nBenchmarkZerologInfoFormat-8            11758495               207.0 ns/op            24 B/op          1 allocs/op\nBenchmarkLogzeInfoFormat-8              10047972               239.8 ns/op            24 B/op          1 allocs/op\nBenchmarkSLogInfoFormat-8                4026775               601.0 ns/op            24 B/op          1 allocs/op\n```\n\n\nLogging `Error` with error and two fields:\n```text\nBenchmarkZerologError-8                 13900646               173.6 ns/op             0 B/op          0 allocs/op\nBenchmarkLogzeError-8                   10827030               221.7 ns/op             0 B/op          0 allocs/op\nBenchmarkSLogError-8                     3757587               635.7 ns/op             0 B/op          0 allocs/op\n```\n\n\nLogging `Error` with error, stack trace and two fields:\n```text\nBenchmarkZerologErrorWithStack-8          545072               4379 ns/op            3298 B/op         73 allocs/op\nBenchmarkLogzeErrorWithStack-8            291956               8065 ns/op            5460 B/op         121 allocs/op\nBenchmarkSLogErrorWithStack-8             612562               3922 ns/op            1617 B/op         3 allocs/op\n```\n\n\nLogging `Info` and two fields using text handler for console / development:\n```text\nBenchmarkZerologInfoConsole-8             682558               3306 ns/op            1922 B/op         51 allocs/op\nBenchmarkLogzeInfoConsole-8               704247               3366 ns/op            1922 B/op         51 allocs/op\nBenchmarkSLogInfoConsole-8               4058850               588.1 ns/op             0 B/op          0 allocs/op\n```\n\n\nAdditional `logze` features\n```text\nBenchmarkLogzeErr-8                     11857878               200.9 ns/op             0 B/op          0 allocs/op\nBenchmarkLogzeToIgnore5-8               10040202               238.5 ns/op             0 B/op          0 allocs/op\n```\n\n\n\n## Contributing\n\nContributions are welcome! Please open issues or submit pull requests.\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n\n\n[version-img]: https://img.shields.io/badge/Go-%3E%3D%201.19-%23007d9c\n[doc-img]: https://pkg.go.dev/badge/github.com/maxbolgarin/logze\n[doc]: https://pkg.go.dev/github.com/maxbolgarin/logze\n[ci-img]: https://github.com/maxbolgarin/logze/actions/workflows/go.yml/badge.svg\n[ci]: https://github.com/maxbolgarin/logze/actions\n[report-img]: https://goreportcard.com/badge/github.com/maxbolgarin/logze\n[report]: https://goreportcard.com/report/github.com/maxbolgarin/logze\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxbolgarin%2Flogze","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaxbolgarin%2Flogze","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxbolgarin%2Flogze/lists"}