{"id":17041667,"url":"https://github.com/xlab/suplog","last_synced_at":"2025-04-12T14:33:15.451Z","repository":{"id":57507094,"uuid":"233653070","full_name":"xlab/suplog","owner":"xlab","description":"Supercharged Go logging based on Logrus","archived":false,"fork":false,"pushed_at":"2022-09-28T17:10:00.000Z","size":239,"stargazers_count":5,"open_issues_count":0,"forks_count":4,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-26T09:11:08.744Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xlab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-01-13T17:28:07.000Z","updated_at":"2023-06-26T11:20:22.000Z","dependencies_parsed_at":"2022-09-19T05:30:16.459Z","dependency_job_id":null,"html_url":"https://github.com/xlab/suplog","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xlab%2Fsuplog","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xlab%2Fsuplog/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xlab%2Fsuplog/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xlab%2Fsuplog/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xlab","download_url":"https://codeload.github.com/xlab/suplog/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248581361,"owners_count":21128155,"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-14T09:13:08.981Z","updated_at":"2025-04-12T14:33:15.429Z","avatar_url":"https://github.com/xlab.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Suplog [![GoDoc](https://godoc.org/github.com/xlab/suplog?status.svg)](https://godoc.org/github.com/xlab/suplog)\n\nA supercharged logging framework based upon [github.com/sirupsen/logrus](https://github.com/sirupsen/logrus), which enables structured, leveled logging with hooks support. Hooks are middleware modules for logging that can augment message being logged or even send it to a remote server.\n\nThe key feature is an integrated stack tracing for any wrapped error (either from Go stdlib, or [github.com/pkg/errors](http://github.com/pkg/errors)).\n\n\u003cimg alt=\"Screenshot of suplog\" src=\"screenshot.png\" width=\"600px\" /\u003e\n\n## Init options\n\n```go\nNewLogger(wr io.Writer, formatter Formatter, hooks ...Hook) Logger\n```\n\nAvailable formatters:\n* `suplog.TextFormatter` — suplogs log entries as text lines for TTY or without TTY colors (`LOG_FORMATTER=text`)\n* `suplog.JSONFormatter` — suplogs all log entries as JSON objects (`LOG_FORMATTER=json`)\n\nAvailable hooks:\n* [github.com/xlab/suplog/hooks/debug](https://github.com/xlab/suplog/blob/master/hooks/debug/hook.go#L14)\n* [github.com/xlab/suplog/hooks/blob](https://github.com/xlab/suplog/blob/master/hooks/blob/hook.go#L14)\n* [github.com/xlab/suplog/hooks/bugsnag](https://github.com/xlab/suplog/blob/master/hooks/bugsnag/hook.go#L13)\n\n## Leveled Logging\n\nSuplog supports 7 levels: `Trace`, `Debug`, `Info`, `Warning`, `Error`, `Fatal` and `Panic`.\n\n```go\nlog.Trace(\"Something very low level.\")\nlog.Debug(\"Useful debugging information.\")\nlog.Info(\"Something noteworthy happened!\")\nlog.Warn(\"You should probably take a look at this.\")\nlog.Error(\"Something failed but I'm not quitting.\")\n// Calls os.Exit(1) after logging\nlog.Fatal(\"Bye.\")\n// Calls panic() after logging\nlog.Panic(\"I'm bailing.\")\n```\n\nYou can set the logging level on an Logger, then it will only log entries with that severity or anything above it:\n\n```go\n// Will log anything that is info or above (warn, error, fatal, panic). Default.\nlog.SetLevel(suplog.InfoLevel)\n```\n\nDifferent levels will produce log lines of different colors. Also, some hooks will trigger on specific levels. For example, a debug hook will add infomation about line for `Debug` log entries. Another hook that enables Bugsnag support will report all errors and warnings to an external service.\n\n## Structured Logging\n\nIn addition to log leveling, the new suplog package enables providing additional fields without altering the original message. By using this feature a developer can provide additional debug context.\n\n```go\nlog.WithFields(suplog.Fields{\n    \"module\": \"accounts\",\n    \"email\":  \"john@doe.com\"\n}).Error(\"account check failed\")\n```\n\nIn this case `email` field will be logged as a separate column that can be parsed and used as a filter. When using it with external services like Bugsnag, these fields will be reported in metadata tab and can be used for filtering too.\n\nSuplog fields can be joined and chained:\n\n```go\nfunc init() {\n    out = log.WithField(\"module\", \"fooer\")\n}\n\nfunc runningFoo() {\n    fooOut := log.WithField(\"action\", \"foo\")\n\n    for _, itemName := range items {\n        itemOut := fooOut.WithField(\"item\", itemName)\n        itemOut.Info(\"processing item!\")\n    }\n}\n```\n\nYou should use chaining to avoid duplication of field context in sub-routines!\n\nAn example of issuing a warning without changing the original error:\n\n```go\nlog.WithError(err).Warnln(\"something wrong happened\")\n```\n\n## Hooks\n\nDuring suplog initialisation it is possible to specify suplog hooks. Hooks are plugins that will pre-process log entries and do something useful. Below are several examples that are available to suplog users.\n\n### Debug\n\nDebug hook adds information about caller fn name and position is source code. By default applies only to `Debug` and `Trace` entries, but can be extended to any level.\n\n```go\nimport debugHook github.com/xlab/suplog/hooks/debug\n```\n\nOptions:\n\n```go\ntype HookOptions struct {\n    // AppVersion specifies version of the app currently running.\n    AppVersion string\n    // Levels enables this hook for all listed levels.\n    Levels []logrus.Level\n    // PathSegmentsLimit allows to trim amount of source code file path segments.\n    // Untrimmed: /Users/xlab/Documents/dev/go/src/github.com/xlab/suplog/default_test.go\n    // Trimmed (3): xlab/suplog/default_test.go\n    PathSegmentsLimit int\n}\n```\n\nIf not specified, AppVersion is set from **APP_VERSION** env variable. PathSegmentsLimit is set to 3 by default, which means the latest 3 path segments of the source path.\n\n### Bugsnag\n\nBugsnag hook implements integration with [Bugsnag.com](https://app.bugsnag.com) service for error tracing and monitoring. It will send any entry above warning level, including its meta data and stack trace.\n\n```go\nimport bugsnagHook github.com/xlab/suplog/hooks/bugsnag\n```\n\nOptions:\n\n```go\ntype HookOptions struct {\n    // Levels enables this hook for all listed levels.\n    Levels       []logrus.Level\n\n    Env               string\n    AppVersion        string\n    BugsnagAPIKey     string\n    BugsnagEnabledEnv []string\n    BugsnagPackages   []string\n}\n```\n\nBe default reporting is enabled for all levels above `Warning`.\n\nThe hook can be enabled in default suplogger by setting OS ENV variables:\n\n* APP_ENV (e.g. `test`, `staging` or `prod`)\n* APP_VERSION\n* LOG_BUGSNAG_KEY\n\n### Blob Uploads\n\nBlob hook allows to upload heavy blobs of data such as request and response HTML / JSON dumps into a remote log storage. This hook utilizes Amazon S3 interface, therefore is compatible with any S3-like API.\n\n```go\nimport blobHook github.com/xlab/suplog/hooks/blob\n```\n\nOptions:\n\n```go\ntype HookOptions struct {\n    Env               string\n    BlobStoreURL      string\n    BlobStoreAccount  string\n    BlobStoreKey      string\n    BlobStoreEndpoint string\n    BlobStoreRegion   string\n    BlobStoreBucket   string\n    BlobRetentionTTL  time.Duration\n    BlobEnabledEnv    map[string]bool\n}\n```\n\nBe default blob uploading is enabled for all levels.\n\nThe following OS ENV variables are mapped:\n\n* APP_ENV\n* LOG_BLOB_STORE_URL\n* LOG_BLOB_STORE_ACCOUNT\n* LOG_BLOB_STORE_KEY\n* LOG_BLOB_STORE_ENDPOINT\n* LOG_BLOB_STORE_REGION\n* LOG_BLOB_STORE_BUCKET\n\nHow to use:\n\n```go\nlog.WithField(\"blob\", testBlob).Infoln(\"test is running, trying to submit blob\")\n```\n\nWhere field name should be exactly `blob` and `testBlob` should be `[]byte`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxlab%2Fsuplog","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxlab%2Fsuplog","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxlab%2Fsuplog/lists"}