{"id":25933337,"url":"https://github.com/robertwhurst/blackbox","last_synced_at":"2025-03-04T00:53:28.986Z","repository":{"id":138841013,"uuid":"126051496","full_name":"RobertWHurst/blackbox","owner":"RobertWHurst","description":"Blackbox is a simple logger with support for contextual information, and multiple write targets","archived":false,"fork":false,"pushed_at":"2025-01-11T04:07:43.000Z","size":44,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-01-11T04:38:49.347Z","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":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RobertWHurst.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":null,"license":"license.txt","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":"2018-03-20T16:51:32.000Z","updated_at":"2025-01-11T04:07:39.000Z","dependencies_parsed_at":"2024-09-11T07:11:37.684Z","dependency_job_id":"ba7debb2-0e8d-415b-9bb4-478204b24d73","html_url":"https://github.com/RobertWHurst/blackbox","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RobertWHurst%2Fblackbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RobertWHurst%2Fblackbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RobertWHurst%2Fblackbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RobertWHurst%2Fblackbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RobertWHurst","download_url":"https://codeload.github.com/RobertWHurst/blackbox/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241763726,"owners_count":20016162,"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":"2025-03-04T00:53:28.451Z","updated_at":"2025-03-04T00:53:28.977Z","avatar_url":"https://github.com/RobertWHurst.png","language":"Go","funding_links":["https://github.com/sponsors/RobertWHurst"],"categories":[],"sub_categories":[],"readme":"\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://pkg.go.dev/github.com/RobertWHurst/blackbox\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/go-mod/go-version/RobertWHurst/blackbox\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/RobertWHurst/blackbox/actions/workflows/ci.yml\"\u003e\n    \u003cimg src=\"https://github.com/RobertWHurst/blackbox/actions/workflows/ci.yml/badge.svg\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/sponsors/RobertWHurst\"\u003e\n    \u003cimg src=\"https://img.shields.io/static/v1?label=Sponsor\u0026message=%E2%9D%A4\u0026logo=GitHub\u0026color=%23fe8e86\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n# blackbox - A flight recorder for Go\n\n__If you encounter a bug please [report it][bug-report].__\n\nBlackbox is a simple logger that will do exactly what you want a logger\nto do - log messages, messages that are clear and contextual.\n\n```go\nlogger := blackbox.New()\n\nlogger.AddTarget(blackbox.NewPrettyTarget(os.Stdout, os.Stderr))\n\nlogger.Info(\"Hello world\", blackbox.Ctx{ \"type\": \"greeting\" })\n```\n\n## Getting started\n\nTo add blackbox to your project use go get:\n\n```sh\ngo get github.com/RobertWHurst/blackbox\n```\n\nNext you'll need to create a logger in your project.\n\n```go\nlogger := blackbox.New()\n```\n\nThis logger will not output anything until you add a target to it. So let's do\nthat now. We'll add a pretty target that will output to stdout and stderr.\n\n```go\nlogger.AddTarget(blackbox.NewPrettyTarget(os.Stdout, os.Stderr))\n```\n\nThe pretty target will output messages in a human readable format.\n\n```sh\n2000-01-01T12:00:00Z00:00 info    Hello world type=greeting\n```\n\n## Providing Context\n\nblackbox has a concept called contexts. Contexts are a way to provide\nadditional information associated with a message. For example, if you're\nlogging a message about a user, you might want to include the user's id in the\nmessage. You could do this by logging a string containing the user's id, but\nthat might be more difficult to parse, and search for. Instead you can use\ncontexts which can be formatted in a searchable way.\n\nContexts are also useful for associating things like request ids, component\nnames, and other information that might be useful to have in a log message.\n\n```go\nlogger.Info(\"Hello world\", blackbox.Ctx{ \"type\": \"greeting\" })\n```\n\nContext data can be added to log messages by passing blackbox.Ctx as an argument\nto any of the logging methods, but it can also be added to the logger itself.\n\n```go\nlogger := blackbox.NewWithCtx(blackbox.Ctx{ \"context\": \"greeter\" })\n```\n\nThis logger will now attach the context above to every message it logs. This\ncan be useful for attaching things like component names, or request ids.\n\nLastly, it's possible to create a new logger with a parent logger. This will\ncause the new logger to inherit the parent's context.\n\n```go\nsubLogger := logger.WithCtx(blackbox.Ctx{ \"context\": \"greeter-formatter\" })\n```\n\nThis sub logger will now have the context of both the parent logger, and the\ncontext passed to WithCtx.\n\n## Levels\n\nblackbox has 6 levels. Trace, Debug, Info, Warn, Error, and Fatal. Each level\nhas a purpose, and a meaning. Some have special behavior such as Fatal which\nwill cause the program to exit.\n\n### Trace\n\nTrace should be used for overly detailed information to help debug the flow of\na program.\n\n### Debug\n\nDebug should be used to aid in debugging, but should be less detailed than\nTrace.\n\n### Info\n\nInfo should be used for general information about the flow of a program.\nThese messages should be expected to be recorded in production.\n\n### Warn\n\nWarn should be used to indicate that something unexpected happened, but the\nprogram is still able to continue.\n\n### Error\n\nError should be used to indicate that something unexpected happened, and it\ncaused a failure, but the program is still able to continue.\n\n### Fatal\n\nFatal should be used to indicate that a critical failure has occurred, and the\nprogram needs to exit. Fatal will call os.Exit(1) after logging the message.\n\n## Targets\n\nTargets handle logger output. Loggers can have more than one target. There are\ntwo targets included with blackbox. A pretty target, and a JSON target. Both\nwill write to any pair of io.Writer. This allows you to write to files, stdout,\nstderr, or any other io.Writer.\n\n```go\nlogger.AddTarget(blackbox.NewPrettyTarget(os.Stdout, os.Stderr))\n```\n\nThe above example will add a pretty target that will write to stdout, and\nstderr.\n\nLet's take a look at these two targets.\n\n### Pretty\n\nThe pretty target will output messages in a human readable format.\n\n```sh\n2000-01-01T12:00:00Z00:00 info    Hello world type=greeting\n```\n\nNot shown in the example above, but the pretty target will also colorize the\nlevel of the message, and the keys in the context using ansi color codes.\n\nYou can also customize the format of the message by way of SetLevel,\nShowTimestamp, ShowContext, and UseColor.\n\n```go\nlogger.AddTarget(blackbox.NewPrettyTarget(os.Stdout, os.Stderr).\n    SetLevel(blackbox.Trace).\n    ShowTimestamp(false).\n    ShowContext(false).\n    UseColor(false))\n```\n\n### JSON\n\nThe json target will output messages in a JSON format.\n\n```json\n{\"time\":\"2000-01-01T12:00:00Z00:00\",\"level\":\"info\",\"message\":\"Hello world\"}\n```\n\nWith the exception of color, the json target has the same customization\noptions as the pretty target.\n\n```go\nlogger.AddTarget(blackbox.NewPrettyTarget(os.Stdout, os.Stderr).\n    SetLevel(blackbox.Trace).\n    ShowTimestamp(false).\n    ShowContext(false))\n```\n\n## Implementing Targets\n\nTargets are simple to implement. They only need to implement the Target\ninterface - a single Log Method.\n\n```go\ntype Target interface {\n    Log(level Level, values []interface{}, context Context) error\n}\n```\n\nPlease note that if synchronization is needed, it should be handled by the\ntarget. The logger will not handle synchronization.\n\nLet's go over the arguments to the Log method.\n\nThe first argument is the level of the message, exactly as it was passed to the\nlogger.\n\nThe second argument is a slice of values. The reason this isn't a single string\nis because the logger will accept any number of arguments of any type. By\npassing the values to the target, it allows the target to decide how to\nformat and/or consume them respective of value type.\n\nThe third argument is the context of the message, a map with string keys and\ninterface{} as the values.\n\nWith these values targets can to a wide range of things with maximum flexibility\nand control.\n\n## Help Welcome\n\nIf you want to support this project by throwing be some coffee money It's\ngreatly appreciated.\n\n[![sponsor](https://img.shields.io/static/v1?label=Sponsor\u0026message=%E2%9D%A4\u0026logo=GitHub\u0026color=%23fe8e86)](https://github.com/sponsors/RobertWHurst)\n\nIf your interested in providing feedback or would like to contribute please feel\nfree to do so. I recommend first [opening an issue][feature-request] expressing\nyour feedback or intent to contribute a change, from there we can consider your\nfeedback or guide your contribution efforts. Any and all help is greatly\nappreciated since this is an open source effort after all.\n\nThank you!\n\n[bug-report]: https://github.com/RobertWHurst/blackbox/issues/new?template=bug_report.md\n[feature-request]: https://github.com/RobertWHurst/blackbox/issues/new?template=feature_request.md\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobertwhurst%2Fblackbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frobertwhurst%2Fblackbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobertwhurst%2Fblackbox/lists"}