{"id":15597513,"url":"https://github.com/cdimascio/go-bunyan-logger","last_synced_at":"2025-03-29T11:45:10.270Z","repository":{"id":83296510,"uuid":"77752465","full_name":"cdimascio/go-bunyan-logger","owner":"cdimascio","description":"Structured logger: Bunyan compatible JSON logging library for Go","archived":false,"fork":false,"pushed_at":"2017-01-01T01:17:04.000Z","size":485,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-02-04T12:48:10.340Z","etag":null,"topics":[],"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/cdimascio.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":"2016-12-31T18:54:11.000Z","updated_at":"2017-01-01T01:36:30.000Z","dependencies_parsed_at":"2023-03-12T17:53:50.999Z","dependency_job_id":null,"html_url":"https://github.com/cdimascio/go-bunyan-logger","commit_stats":{"total_commits":10,"total_committers":1,"mean_commits":10.0,"dds":0.0,"last_synced_commit":"46ce7c0ce6739ca4ef4a9a356609744ddf6fe57c"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cdimascio%2Fgo-bunyan-logger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cdimascio%2Fgo-bunyan-logger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cdimascio%2Fgo-bunyan-logger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cdimascio%2Fgo-bunyan-logger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cdimascio","download_url":"https://codeload.github.com/cdimascio/go-bunyan-logger/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246180888,"owners_count":20736459,"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":[],"created_at":"2024-10-03T01:22:13.278Z","updated_at":"2025-03-29T11:45:10.244Z","avatar_url":"https://github.com/cdimascio.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n##go-bunyan-logger\n**go-bunyan-logger** is a simple and fast JSON structured-logging library for Go. It is inspired by [bunyan](https://github.com/trentm/node-bunyan) and compatible with bunyan's CLI.\n\n```go\n\tlog := logger.NewLogger(\"myapp\")\n\tlog.Info(\"An information message\")\n```\n\n**go-bunyan-logger** is a proponent of the [bunyan](https://github.com/trentm/node-bunyan) manifesto: \"Server logs should be structured. JSON's a good format. Let's do that. A log record is one line of JSON.stringify'd output. Let's also specify some common names for the requisite and common fields for a log record (see below).\"\n\n### Compatible with [bunyan's CLI](https://github.com/trentm/node-bunyan)\n\nOutput with bunyan cli `myapp | bunyan`:\n\n![](https://github.com/cdimascio/go-bunyan-logger/raw/master/assets/ex-bunyan-cli.png)\n\nOutput (short) with bunyan cli `myapp | bunyan -o 'short'`:\n\n![](https://github.com/cdimascio/go-bunyan-logger/raw/master/assets/ex-bunyan-cli-short.png)\n\nOutput raw:\n\n```json\n{\"hostname\":\"Carmines-MacBook-Pro-7.local\",\"key\":\"value\",\"key2\":10,\"level\":30,\"msg\":\"Woop!\",\"name\":\"my-app\",\"pid\":50230,\"time\":\"2016-12-31T21:16:14.242Z\",\"v\":0}\n{\"hostname\":\"Carmines-MacBook-Pro-7.local\",\"level\":50,\"msg\":\"Error: 500 (Internal Server Error)\",\"name\":\"my-app\",\"pid\":50230,\"time\":\"2016-12-31T21:16:14.242Z\",\"v\":0}\n{\"hostname\":\"Carmines-MacBook-Pro-7.local\",\"level\":60,\"msg\":\"Fatal message\",\"name\":\"my-app\",\"pid\":50230,\"time\":\"2016-12-31T21:16:14.242Z\",\"v\":0}\n{\"hostname\":\"Carmines-MacBook-Pro-7.local\",\"level\":40,\"msg\":\"Warning message\",\"name\":\"my-app\",\"pid\":50230,\"time\":\"2016-12-31T21:16:14.242Z\",\"v\":0}\n{\"hostname\":\"Carmines-MacBook-Pro-7.local\",\"level\":20,\"msg\":\"Debug message\",\"name\":\"my-app\",\"pid\":50230,\"time\":\"2016-12-31T21:16:14.242Z\",\"v\":0}\n{\"hostname\":\"Carmines-MacBook-Pro-7.local\",\"level\":10,\"msg\":\"Trace message\",\"name\":\"my-app\",\"pid\":50230,\"time\":\"2016-12-31T21:16:14.242Z\",\"v\":0}\n```\n\n\nCode to generate the output above:\n\n```go\npackage main\n\nimport \"github.com/cdimascio/go-bunyan-logger\"\n\nvar l = logger.NewLogger(\"my-app\").SetLevel(logger.LevelTrace)\n\nfunc main() {\n\tl.WithFields(logger.Fields{\n\t\t\"key\": \"value\",\n\t\t\"key2\": 10,\n\t}).Info(\"Woop!\")\n\n\n\tl.Errorf(\"Error: %d (%s)\", 500, \"Internal Server Error\")\n\tl.Fatal(\"Fatal message\")\n\tl.Warn(\"Warning message\")\n\tl.Debug(\"Debug message\")\n\tl.Trace(\"Trace message\")\n}\n```\n\n\n## Installation\n`go get github.com/cdimascio/go-bunyan-logger`\n\n## Usage\n\nQuick start example:\n\n```go\npackage main\n\nimport (\n  \"github.com/cdimascio/go-bunyan-logger\"\n)\n\nfunc main() {\n\t// Create a logger instance. Note: you can create many instances\n\tlog := logger.NewLogger(\"myapp\")\n\n\t// Log messages\n\tlog.Info(\"An information message\")\n\n\t// Log messages in Printf style\n\tlog.Infof(\"An information message from %s\", \"go-bunyan-logger!\")\n\n\t// Log messages with custom fields\n\tlog.WithFields(logger.Fields{\n\t\t\"fieldOne\": \"value 1\",\n\t}).Infof(\"Msg %s\", \"Info message!\")\n\n}\n```\n\nOutput:\n\n```json\n{\"hostname\":\"Carmines-MacBook-Pro-7.local\",\"level\":30,\"msg\":\"An information message\",\"name\":\"myapp\",\"pid\":38851,\"time\":\"2016-12-31T11:34:52-05:00\",\"v\":0}\n\n{\"hostname\":\"Carmines-MacBook-Pro-7.local\",\"level\":30,\"msg\":\"An information message from [go-bunyan-logger!]\",\"name\":\"myapp\",\"pid\":38851,\"time\":\"2016-12-31T11:34:52-05:00\",\"v\":0}\n\n{\"fieldOne\":\"value 1\",\"hostname\":\"Carmines-MacBook-Pro-7.local\",\"level\":30,\"msg\":\"An information message with fields\",\"name\":\"myapp\",\"pid\":38851,\"time\":\"2016-12-31T11:34:52-05:00\",\"v\":0}\n\n\n```\n\n**With Global fields**\n\n\n```go\n   // apply global field to all log entries for this logger instance\n  \tlog := logger.NewLogger().WithGlobalFields(Fields{\n\t\t\"globalFieldOne\": \"value 1\",\n\t\t\"globalFieldTwo\": 2.0,\n\t})\n\n\tlog.Error(\"An error message\")\n\n\tlog.Errorf(\"An error message with status %d\", 500)\n\n\tlog.WithFields(Fields{\n\t\t\"fieldOne\": \"value 1\",\n\t}).Errorf(\"An error message with %d fields, %d of which are global\", 3, 2)\n```\n\nOutput:\n\n```json\n{\"globalFieldOne\":\"value 1\",\"globalFieldTwo\":2,\"hostname\":\"Carmines-MacBook-Pro-7.local\",\"level\":50,\"msg\":\"An error message\",\"name\":\"example-app\",\"pid\":38851,\"time\":\"2016-12-31T11:34:52-05:00\",\"v\":0}\n\n{\"globalFieldOne\":\"value 1\",\"globalFieldTwo\":2,\"hostname\":\"Carmines-MacBook-Pro-7.local\",\"level\":50,\"msg\":\"An error message with status [500]\",\"name\":\"example-app\",\"pid\":38851,\"time\":\"2016-12-31T11:34:52-05:00\",\"v\":0}\n\n{\"fieldOne\":\"value 1\",\"globalFieldOne\":\"value 1\",\"globalFieldTwo\":2,\"hostname\":\"Carmines-MacBook-Pro-7.local\",\"level\":50,\"msg\":\"An error message with 3 fields, 2 of which are global\",\"name\":\"example-app\",\"pid\":38851,\"time\":\"2016-12-31T11:34:52-05:00\",\"v\":0}\n\n\n```\n\n##Configure\nThe Logger's level and timeformat are configurable\n\n```go\n\t// Set the logger level. LevelInfo is the default\n\tlog.SetLevel(logger.LevelInfo)\n\n\t// defaults to Bunyan time\n\tlog.SetTimeFormat(time.RFC3339)\n\n```\n\n##Methods\n```go\n\tFatal(msg string)\n\tError(msg string)\n\tWarn(msg string)\n\tInfo(msg string)\n\tDebug(msg string)\n\tTrace(msg string)\n\n\tFatalf(format string, args ...interface{})\n\tErrorf(format string, args ...interface{})\n\tWarnf(format string, args ...interface{})\n\tInfof(format string, args ...interface{})\n\tTracef(format string, args ...interface{})\n\n\tWithFields(fields Fields) *Entry\n\tWithField(key string, value interface{}) *Entry\n\tWithError(err error) * Entry\n```\n\n\n##Levels\n\nThe log levels in go-bunyan-logger are as follows. The level descriptions are best practice opinions of the [bunyan](https://github.com/trentm/node-bunyan) author.\n\n- \"fatal\" (60): The service/app is going to stop or become unusable now. An operator should definitely look into this soon.\n- \"error\" (50): Fatal for a particular request, but the service/app continues servicing other requests. An operator should look at this soon(ish).\n- \"warn\" (40): A note on something that should probably be looked at by an operator eventually.\n- \"info\" (30): Detail on regular operation.\n- \"debug\" (20): Anything else, i.e. too verbose to be included in \"info\" level.\n- \"trace\" (10): Logging from external libraries used by your app or very detailed application logging.\n\nChange the Logger instance level:\n\n```\n\tlog.SetLevel(logger.LevelInfo)\n```\n\n## Core fields\nCore fields are provided in each and every log entry.\n\n| field    | required | type   | can be overriden | description                                                                                             | default value |\n|----------|----------|--------|------------------|---------------------------------------------------------------------------------------------------------|---------------|\n| `v`        | yes      | number    | no               | The go-bunyan-logger format version. The current value is 0.                                                   | `0`             |\n| `name`     | yes      | string | yes              | The Logger name. Provided at Logger creation. You must specify a name for your logger when creating it. | n/a           |\n| `hostname` | yes      | string | yes              | The hostname. Determined at Logger creation and populated automatically.                                | `os.Hostname()` |\n| `pid`      | yes      | number    | no               | The process id. Populated automatically.                                                                | `os.Getpid()`   |\n| `time`     | yes      | string | yes              | The timestamp. Populated automatically                                                                  | `time.Now()`    |\n| `msg`      | yes      | string | yes              | Every log method e.g. `log.Debug(...)` must provide a msg.                                              | n/a           |\n\nGo ahead and add more fields. Nested ones are fine too!\n\n## Contributing\nPull requests welcomed :)\n\n## License\nMIT","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcdimascio%2Fgo-bunyan-logger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcdimascio%2Fgo-bunyan-logger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcdimascio%2Fgo-bunyan-logger/lists"}