{"id":16828111,"url":"https://github.com/kataras/golog","last_synced_at":"2025-05-14T20:07:55.280Z","repository":{"id":43771797,"uuid":"98416413","full_name":"kataras/golog","owner":"kataras","description":"A  high-performant Logging Foundation for Go Applications. X3 faster than the rest leveled loggers.","archived":false,"fork":false,"pushed_at":"2025-03-29T00:49:55.000Z","size":273,"stargazers_count":332,"open_issues_count":10,"forks_count":44,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-04-08T13:00:40.180Z","etag":null,"topics":["easy-to-use","go","golang","high-performance","iris","iris-golang","log","logger","logging","logs","modular","stdout"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kataras.png","metadata":{"files":{"readme":"README.md","changelog":"HISTORY.md","contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"kataras"}},"created_at":"2017-07-26T11:40:56.000Z","updated_at":"2025-04-02T09:00:42.000Z","dependencies_parsed_at":"2023-01-30T20:10:21.434Z","dependency_job_id":"495283f6-34b7-4c6d-b899-556e345017d5","html_url":"https://github.com/kataras/golog","commit_stats":{"total_commits":65,"total_committers":6,"mean_commits":"10.833333333333334","dds":0.09230769230769231,"last_synced_commit":"a8efabd46b9e6e4cb9209fd0461104c0d11dbfc9"},"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kataras%2Fgolog","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kataras%2Fgolog/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kataras%2Fgolog/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kataras%2Fgolog/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kataras","download_url":"https://codeload.github.com/kataras/golog/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254219373,"owners_count":22034397,"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":["easy-to-use","go","golang","high-performance","iris","iris-golang","log","logger","logging","logs","modular","stdout"],"created_at":"2024-10-13T11:24:45.592Z","updated_at":"2025-05-14T20:07:55.228Z","avatar_url":"https://github.com/kataras.png","language":"Go","funding_links":["https://github.com/sponsors/kataras"],"categories":["Go"],"sub_categories":[],"readme":"# ✒️ golog\n\n_golog_ is a zero-dependency simple, fast and easy-to-use level-based logger written in [Go Programming Language](https://go.dev).\n\n![Output from win terminal](screen.png)\n\n[![build status](https://img.shields.io/github/actions/workflow/status/kataras/golog/ci.yml)](https://github.com/kataras/golog/actions) [![report card](https://img.shields.io/badge/report%20card-a%2B-ff3333.svg?style=flat-square)](http://goreportcard.com/report/kataras/golog) [![godocs](https://img.shields.io/badge/online-documentation-0366d6.svg?style=flat-square)](https://pkg.go.dev/github.com/kataras/golog) [![github issues](https://img.shields.io/github/issues/kataras/golog.svg?style=flat-square)](https://github.com/kataras/golog/issues?q=is%3Aopen+is%3Aissue)\n\n\u003c!-- ## 🥇 Features\n\n* Focus on high performance and agile perspective of things\n* Easy API and a default package-level instance, i.e `golog#Fatalf/Errorf/Warnf/Infof/Debugf`\n* Fully compatible with the standard library\n* Thanks to the [pio library](https://github.com/kataras/pio) it supports any type of structure, gives you the ability to `Hijack` and `Handle` or `Intercept` the on-going logs too \n* Set or even Add unlimited number of output targets, `io.Writer`\n* Scan from any `io.Reader` and log to the defined output target(s)\n* Levels such as `fatal`,`error`, `warn`, `info`, `debug`, or `disable`\n* Beautiful (**customizable**) colors for leveled logs, automatically omit colors when output does not support colors (i.e files)\n* Incredible high-performant, 3 times faster than your favourite logger\n* Never-Panics\n\nNavigate through [_examples](_examples/) and [integrations](_examples/integrations/) to learn if that fair solution suits your needs. --\u003e\n\n## 🚀 Installation\n\nThe only requirement is the Go Programming Language[*](https://go.dev/dl).\n\n\u003cdetails\u003e\n\u003csummary\u003eGo modules\u003c/summary\u003e\n\n```bash\n$ go get github.com/kataras/golog@latest\n```\n\nOr edit your project's go.mod file and execute $ go build.\n\n```mod\nmodule your_project_name\n\ngo 1.22\n\nrequire (\n    github.com/kataras/golog v0.1.12\n)\n```\n\n\u003e `$ go build`\n\n\u003c/details\u003e\n\n```bash\n$ go get github.com/kataras/golog@latest\n```\n\n```go\npackage main\n\nimport (\n    \"github.com/kataras/golog\"\n)\n\nfunc main() {\n    // Default Output is `os.Stdout`,\n    // but you can change it:\n    // golog.SetOutput(os.Stderr)\n\n    // Time Format defaults to: \"2006/01/02 15:04\"\n    // you can change it to something else or disable it with:\n    // golog.SetTimeFormat(\"\")\n\n    // Level defaults to \"info\",\n    // but you can change it:\n    golog.SetLevel(\"debug\")\n\n    golog.Println(\"This is a raw message, no levels, no colors.\")\n    golog.Info(\"This is an info message, with colors (if the output is terminal)\")\n    golog.Warn(\"This is a warning message\")\n    golog.Error(\"This is an error message\")\n    golog.Debug(\"This is a debug message\")\n    golog.Fatal(`Fatal will exit no matter what,\n    but it will also print the log message if logger's Level is \u003e=FatalLevel`)\n\n    // Use any other supported logger through golog, e.g. the new \"log/slog\":\n    // golog.Install(slog.Default())\n}\n```\n\n## Log Levels\n\n| Name      | Method                  | Text     | Color              |\n| ----------|-------------------------|----------|--------------------|\n| `\"fatal\"` | `Fatal, Fatalf`         | `[FTAL]` | Red background     |\n| `\"error\"` | `Error, Errorf`         | `[ERRO]` | Red foreground     |\n| `\"warn\"`  | `Warn, Warnf, Warningf` | `[WARN]` | Magenta foreground |\n| `\"info\"`  | `Info, Infof`           | `[INFO]` | Cyan foreground    |\n| `\"debug\"` | `Debug, Debugf`         | `[DBUG]` | Yellow foreground  |\n\n\u003e On debug level the logger will store stacktrace information to the log instance, which is not printed but can be accessed through a `Handler` (see below).\n\n### Helpers\n\n```go\n// GetTextForLevel returns the level's (rich) text. \nfatalRichText := golog.GetTextForLevel(golog.FatalLevel, true)\n\n// fatalRichText == \"\\x1b[41m[FTAL]\\x1b[0m\"\n```\n\n```go\n// ParseLevel returns a Level based on its string name.\nlevel := golog.ParseLevel(\"debug\")\n\n// level == golog.DebugLevel\n```\n\n### Customization\n\nYou can customize the log level attributes.\n\n```go\nfunc init() {\n    // Levels contains a map of the log levels and their attributes.\n    errorAttrs := golog.Levels[golog.ErrorLevel]\n\n    // Change a log level's text.\n    customColorCode := 156\n    errorAttrs.SetText(\"custom text\", customColorCode)\n\n    // Get (rich) text per log level.\n    enableColors := true\n    errorRichText := errorAttrs.Text(enableColors)\n}\n```\n\nAlternatively, to change a specific text on a known log level, you can just call:\n\n```go\ngolog.ErrorText(\"custom text\", 156)\n```\n\n## Integration\n\nThe `golog.Logger` is using common, expected log methods, therefore you can integrate it with ease.\n\nTake for example the [badger](github.com/dgraph-io/badger) database. You want to add a prefix of `[badger]` in your logs  when badger wants to print something.\n\n1. Create a child logger with a prefix text using the `Child` function,\n2. disable new lines (because they are managed by badger itself) and you are ready to GO:\n\n```go\nopts := badger.DefaultOptions(\"./data\")\nopts.Logger = golog.Child(\"[badger]\").DisableNewLine()\n\ndb, err := badger.Open(opts)\n// [...]\n```\n\n### Level-based and standard Loggers\n\nYou can put `golog` in front of your existing loggers using the [Install](https://pkg.go.dev/github.com/kataras/golog?tab=doc#Logger.Install) method.\n\nSupporte loggers:\n\n- log\n- slog\n- logrus\n\nExample for `log/slog` standard package:\n\n```go\n// Simulate an slog.Logger preparation.\nvar myLogger = slog.New(slog.NewJSONHandler(os.Stdout, \u0026slog.HandlerOptions{\n    Level: slog.LevelDebug,\n}))\n\nfunc main() {\n    golog.SetLevel(\"error\")\n    golog.Install(myLogger)\n\n    golog.Error(\"error message\")\n}\n```\n\nExample for `log` standard package:\n\n```go\n// Simulate a log.Logger preparation.\nmyLogger := log.New(os.Stdout, \"\", 0)\n\ngolog.SetLevel(\"error\")\ngolog.Install(myLogger)\n\ngolog.Error(\"error message\")\n```\n\nExample for [sirupsen/logrus](https://github.com/sirupsen/logrus):\n\n```go\n// Simulate a logrus logger preparation.\nlogrus.SetLevel(logrus.InfoLevel)\nlogrus.SetFormatter(\u0026logrus.JSONFormatter{})\n\ngolog.Install(logrus.StandardLogger())\n\ngolog.Debug(`this debug message will not be shown,\n    because the logrus level is InfoLevel`)\ngolog.Error(`this error message will be visible as JSON,\n    because of logrus.JSONFormatter`)\n```\n\n## Output Format\n\nAny value that completes the [Formatter interface](https://github.com/kataras/golog/blob/master/formatter.go) can be used to write to the (leveled) output writer. By default the `\"json\"` formatter is available.\n\n### JSON\n\n```go\nimport \"github.com/kataras/golog\"\n\nfunc main() {\n    golog.SetLevel(\"debug\")\n    golog.SetFormat(\"json\", \"    \") // \u003c --\n\n    // main.go#29\n    golog.Debugf(\"This is a %s with data (debug prints the stacktrace too)\", \"message\", golog.Fields{\n        \"username\": \"kataras\",\n    })\n}\n```\n\n**Output**\n\n```json\n{\n    \"timestamp\": 1591423477,\n    \"level\": \"debug\",\n    \"message\": \"This is a message with data (debug prints the stacktrace too)\",\n    \"fields\": {\n        \"username\": \"kataras\"\n    },\n    \"stacktrace\": [\n        {\n            \"function\": \"main.main\",\n            \"source\": \"C:/example/main.go:29\"\n        }\n    ]\n}\n```\n\n### Register custom Formatter\n\n```go\ngolog.RegisterFormatter(new(myFormatter))\ngolog.SetFormat(\"myformat\", options...)\n```\n\nThe `Formatter` interface looks like this:\n\n```go\n// Formatter is responsible to print a log to the logger's writer.\ntype Formatter interface {\n\t// The name of the formatter.\n\tString() string\n\t// Set any options and return a clone,\n\t// generic. See `Logger.SetFormat`.\n\tOptions(opts ...any) Formatter\n\t// Writes the \"log\" to \"dest\" logger.\n\tFormat(dest io.Writer, log *Log) bool\n}\n```\n\n### Custom Format using `Handler`\n\nThe Logger can accept functions to handle (and print) each [Log](https://pkg.go.dev/github.com/kataras/golog?tab=doc#Log) through its [Handle](https://pkg.go.dev/github.com/kataras/golog?tab=doc#Logger.Handle) method. The Handle method accepts a [Handler](https://pkg.go.dev/github.com/kataras/golog?tab=doc#Handler).\n\n```go\ntype Handler func(value *Log) (handled bool)\n```\n\nThis method can be used to alter Log's fields based on custom logic or to change the output destination and its **output format**.\n\n**Create a JSON handler**\n\n```go\nimport \"encoding/json\"\n\nfunc jsonOutput(l *golog.Log) bool {\n    enc := json.NewEncoder(l.Logger.GetLevelOutput(l.Level.String()))\n    enc.SetIndent(\"\", \"    \")\n    err := enc.Encode(l)\n    return err == nil\n}\n```\n\n**Register the handler and log something**\n\n```go\nimport \"github.com/kataras/golog\"\n\nfunc main() {\n    golog.SetLevel(\"debug\")\n    golog.Handle(jsonOutput)\n\n    // main.go#29\n    golog.Debugf(\"This is a %s with data (debug prints the stacktrace too)\", \"message\", golog.Fields{\n        \"username\": \"kataras\",\n    })\n}\n```\n\n## Examples\n\n\n* [basic](_examples/basic/main.go)\n* [output per level](_examples/level-output/main.go)\n* [child](_examples/child/main.go)\n* [add new level](_examples/customize-levels/new-level/main.go)\n* [change text and color](_examples/customize-levels/text-and-colors/main.go)\n* [customize output](_examples/customize-output/main.go)\n* [multi output](_examples/multi-output/main.go)\n* [scan](_examples/scan/main.go)\n* [logurs integration](_examples/integrations/logrus/main.go)\n* [log.Logger std integration](_examples/integrations/std/main.go)\n* [ngrok integration](_examples/ngrok-logger/main.go) **NEW**\n* [postgres integration](https://github.com/kataras/pgx-golog) **NEW**\n* [new instance](_examples/instance/main.go)\n\n## 🔥 Benchmarks\n\n| test | times ran (large is better) |  ns/op (small is better) | B/op (small is better) | allocs/op (small is better) |\n| -----------|--------|-------------|-------------|-------------|\n| **BenchmarkGologPrint** | 10000000 | 3749 ns/op | 890 B/op | 28 allocs/op |\n| BenchmarkLogrusPrint | \u0026nbsp; 3000000 | 9609 ns/op | 1611 B/op | 64 allocs/op |\n\nClick [here](_benchmarks) for details.\n\n## 👥 Contributing\n\nIf you find that something is not working as expected please open an [issue](https://github.com/kataras/golog/issues).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkataras%2Fgolog","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkataras%2Fgolog","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkataras%2Fgolog/lists"}