{"id":16586971,"url":"https://github.com/ollien/xtrace","last_synced_at":"2025-10-29T08:32:57.917Z","repository":{"id":57485552,"uuid":"196937321","full_name":"ollien/xtrace","owner":"ollien","description":"A simple library to extract traces from golang's xerrors","archived":false,"fork":false,"pushed_at":"2020-04-09T12:14:31.000Z","size":79,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-08-13T20:54:59.433Z","etag":null,"topics":["errors","golang","xerrors"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ollien.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}},"created_at":"2019-07-15T06:25:46.000Z","updated_at":"2020-04-09T12:14:33.000Z","dependencies_parsed_at":"2022-09-02T00:10:24.230Z","dependency_job_id":null,"html_url":"https://github.com/ollien/xtrace","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/ollien/xtrace","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ollien%2Fxtrace","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ollien%2Fxtrace/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ollien%2Fxtrace/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ollien%2Fxtrace/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ollien","download_url":"https://codeload.github.com/ollien/xtrace/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ollien%2Fxtrace/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":281588591,"owners_count":26526990,"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","status":"online","status_checked_at":"2025-10-29T02:00:06.901Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["errors","golang","xerrors"],"created_at":"2024-10-11T22:53:00.071Z","updated_at":"2025-10-29T08:32:57.622Z","avatar_url":"https://github.com/ollien.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# xtrace\n\n[![](https://godoc.org/github.com/ollien/xtrace?status.svg)](http://godoc.org/github.com/ollien/xtrace)\n[![Build Status](https://travis-ci.com/ollien/xtrace.svg?branch=master)](https://travis-ci.com/ollien/xtrace)\n\n[xerrors](https://godoc.org/golang.org/x/xerrors) is pretty awesome. It allows you to wrap your errors and provide more context. Sadly, one of the features of it that isn't really available until Go 1.13 is the ability to print out a stack trace. No longer!\n\n## Installation\n\n`go get -u github.com/ollien/xtrace`\n\n## Basic Usage\n\nThe following example will print a trace of all of the wrapped errors to stderr.\n```go\npackage main\n\nimport (\n\t\"errors\"\n\n\t\"github.com/ollien/xtrace\"\n\t\"golang.org/x/xerrors\"\n)\n\nfunc main() {\n\tbaseErr := errors.New(\"aw shucks, something broke\")\n\terr2 := xerrors.Errorf(\"things went wrong!: %w\", baseErr)\n\n\ttraceErr := xtrace.Trace(err2)\n\tif traceErr != nil {\n\t\tpanic(\"can not trace\")\n\t}\n\t// aw shucks, something broke\n\t// things went wrong!\n\t// github.com/ollien/xtrace.ExampleTracer_Format\n\t//    /home/nick/Documents/code/xtrace/example.go:12\n}\n```\n\nIf more customization is desired, one can use a Tracer. One of Tracer's key features is its compatibility with fmt.\n\n```go\n// ...\ntracer, err := xtrace.NewTracer(err2)\nif err != nil {\n\tpanic(\"can not make tracer\")\n}\n\nfmt.Printf(\"%v\", tracer)\n// aw shucks, something broke\n// things went wrong!\n```\n\nThat's nice, and we can see a trace of all of our errors, but xerrors provides much more for information for us. To get this information, all we have to do is change our format string to %+v.\n\n```go\n// ... (repeated from above)\n\nfmt.Printf(\"%+v\", tracer)\n// aw shucks, something broke\n// things went wrong!\n// github.com/ollien/xtrace.ExampleTracer_Format\n//    /home/nick/Documents/code/xtrace/example.go:18\n```\n\nIf you don't want to use `fmt` and just want to get this trace as a string, you can simply use `ReadNext` to get the next error in the trace. (Tracer also implements `io.Reader` if you prefer to use that.)\n\n```go\n// ... (repeated from above)\n\noutput, err := tracer.ReadNext()\nif err != nil {\n\tpanic(\"can not read from tracer\")\n}\n\nfmt.Println(output)\n// aw shucks, something broke\n```\n\nSee the docs for more usages.\n\n## Customization\n\nOutput customization is one of the explicit goals of xtrace. For instance, if you wish to flip the output of your trace so that the newest errors are on top (i.e. with the root cause at the bottom), all you have to do is the following.\n```go\ntracer, err := NewTracer(err, Ordering(NewestFirstOrdering))\n```\n\nYou can also set up custom formatters for your traces. There are several included (such as `NestedMessageFormatter` and `NilFormatter`). If you want, you can also write your own formatter by simply implementing the `TraceFormatter` interface. For instance, if you wanted to make sure that _everyone_ hears your errors, you can make all of them capitalized.\n\n```go\ntype capsFormatter struct{}\n\nfunc (formatter capsFormatter) FormatTrace(previous []string, message string) string {\n\treturn strings.ToUpper(message)\n}\n```\n\nYou can then set a Tracer's formatter by doing\n```go\ntracer, err := NewTracer(err, Formatter(capsFormatter{}))\n```\n\nIf you wish to combine your loud errors with newest-first ordering you can pass them both as arguments to `NewTracer`.\n\n```go\ntracer, err := NewTracer(err, Ordering(NewestFirstOrdering), Formatter(capsFormatter{}))\n```\n\nSee the docs for more details.\n\n\n# A note about Go 1.13+\n\nThis package _does_ work on Go 1.13+ with the new `errors` package. However, the solidified version of the new errors does not include the `Formatter` interface that `xerrors` did. While it is still possible for this package to work without it, the traces will contain the full contents of the error, including the wrapped content and notably, line numbers do not work. For instance\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\t\"errors\"\n\n\t\"github.com/ollien/xtrace\"\n)\n\nfunc main() {\n\tbaseErr := errors.New(\"aw shucks, something broke\")\n\terr2 := fmt.Errorf(\"things went wrong!: %w\", baseErr)\n\n\ttraceErr := xtrace.Trace(err2)\n\tif traceErr != nil {\n\t\tpanic(\"can not trace\")\n\t}\n\t// aw shucks, something broke\n\t// things went wrong!: aw shucks, something broke\n}\n\n```\n\nThis makes the traces a bit redundant, and a bit more useless as they do not contain line numbers. This is certainly unfortunate, as one of the design goals of this package was to not need to use this package to wrap your errors, much like https://github.com/pkg/errors.\n\nAgain, this package will still work with the new `errors` package, but it cannot work as it once was intended to. A shame, truly. You can always still use `xerrors` if you're so inclined, though.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Follien%2Fxtrace","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Follien%2Fxtrace","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Follien%2Fxtrace/lists"}