{"id":13878940,"url":"https://github.com/mdub/green_log","last_synced_at":"2025-05-06T20:09:41.687Z","repository":{"id":39693401,"uuid":"228172448","full_name":"mdub/green_log","owner":"mdub","description":"a logging library","archived":false,"fork":false,"pushed_at":"2023-03-16T12:24:26.000Z","size":116,"stargazers_count":8,"open_issues_count":1,"forks_count":1,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-31T02:33:38.415Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Ruby","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/mdub.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}},"created_at":"2019-12-15T11:22:30.000Z","updated_at":"2023-03-16T11:08:00.000Z","dependencies_parsed_at":"2024-01-13T20:56:24.087Z","dependency_job_id":"397bc27b-2b52-464c-af8f-df1dd672d1af","html_url":"https://github.com/mdub/green_log","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mdub%2Fgreen_log","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mdub%2Fgreen_log/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mdub%2Fgreen_log/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mdub%2Fgreen_log/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mdub","download_url":"https://codeload.github.com/mdub/green_log/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249664070,"owners_count":21308084,"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-08-06T08:02:04.829Z","updated_at":"2025-04-19T09:31:01.627Z","avatar_url":"https://github.com/mdub.png","language":"Ruby","funding_links":[],"categories":["Ruby"],"sub_categories":[],"readme":"# GreenLog\n\n[![Gem Version](https://badge.fury.io/rb/green_log.svg)](http://badge.fury.io/rb/green_log)\n[![Build Status](https://github.com/mdub/green_log/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/mdub/green_log/actions/workflows/ci.yml)\n\nGreenLog is a logging library for Ruby applications.  It:\n\n- focuses on [structured logging](https://www.thoughtworks.com/radar/techniques/structured-logging) - treating log entries as data\n- is optimised for use in modern \"cloud-native\" applications\n- can be used in place of Ruby's stdlib `Logger`\n\n## Design approach\n\nGreenLog:\n\n- [avoids global state](doc/adr/0002-avoid-global-configuration.md)\n- avoids mutable objects\n- explicitly [decouples log entry generation and handling](doc/adr/0003-decouple-generation-and-handling.md)\n- uses [an approach similar to Rack middleware](doc/adr/0004-use-stacked-handlers-to-solve-many-problems.md) for flexible log processing\n- uses [lock-free IO](doc/adr/0006-use-lock-free-io.md) for performance\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'green_log'\n```\n\nAnd then execute:\n\n    $ bundle\n\n## Usage\n\n### tl;dr\n\n```ruby\nrequire 'green_log'\n\nlogger = GreenLog::Logger.build\n\nlogger.info(\"Stuff happened\")\n# outputs: I -- Stuff happened\n```\n\n### Basic logging\n\nGreenLog implements all the expected logging shortcuts:\n\n```ruby\nlogger.debug(\"Nitty gritty detail\")\n# outputs: D -- Nitty gritty detail\nlogger.info(\"Huh, interesting.\")\n# outputs: I -- Huh, interesting.\nlogger.warn(\"Careful now.\")\n# outputs: W -- Careful now.\nlogger.error(\"Oh, that's really not good!\")\n# outputs: E -- Oh, that's really not good!\nlogger.fatal(\"Byeeee ...\")\n# outputs: F -- Byeeee ...\n```\n\n### Adding context\n\n`Logger#with_context` adds detail about the _source_ of log messages.\n\n```ruby\nlogger = GreenLog::Logger.build.with_context(pid: Process.pid, thread: Thread.current.object_id)\nlogger.info(\"Hello\")\n# outputs: I [pid=13545 thread=70260187418160] -- Hello\n```\n\nIt can be chained to inject additional context:\n\n```ruby\nlogger.with_context(request: 16273).info(\"Handled\")\n# outputs: I [pid=13545 thread=70260187418160 request=16273] -- Handled\n```\n\nContext can also be calculated dynamically, using a block:\n\n```ruby\nlogger = GreenLog::Logger.build.with_context do\n  {\n    request_id: Thread.current[:request_id]\n  }\nend\n# outputs: I [pid=13545 thread=70260187418160 request=16273] -- Handled\n```\n\n### Including data and exceptions\n\nA Hash of data can be included along with the log message:\n\n```ruby\nlogger = GreenLog::Logger.build\nlogger.info(\"New widget\", id: widget.id)\n# outputs: I -- New widget [id=12345]\n```\n\nAnd/or, you can attach an exception:\n\n```ruby\nbegin\n  Integer(\"abc\")\nrescue =\u003e e\n  logger.error(\"parse error\", e)\nend\n# outputs: E -- parse error\n#            ! ArgumentError: invalid value for Integer(): \"abc\"\n#              (irb):50:in `Integer'\n#              (irb):50:in `irb_binding'\n#              ...\n```\n\n### Alternate output format\n\nBy default GreenLog logs with a human-readable format; specify an alternate `format`\nclass if you want a different serialisation format. It comes bundled with a JSON writer, e.g.\n\n```ruby\nlogger = GreenLog::Logger.build(format: GreenLog::JsonWriter)\n# OR\nlogger = GreenLog::Logger.build(format: \"json\")\n\nlogger.info(\"Structured!\", foo: \"bar\")\n```\n\noutputs\n\n```json\n{\"severity\":\"INFO\",\"message\":\"Structured!\",\"data\":{\"foo\":\"bar\"},\"context\":{}}\n```\n\n### Alternate output destination\n\nLogs go to STDOUT by default; specify `dest` to override, e.g.\n\n```ruby\nlogger = GreenLog::Logger.build(dest: STDERR)\n```\n\n### Null logger\n\n`GreenLog::Logger.null` returns a \"null object\" Logger, which routes log entries to `/dev/null`.\n\n```ruby\nlogger = GreenLog::Logger.null\n```\n\n### Filtering by log severity\n\nBy default all log entries will result in output. You can add a severity-threshold to avoid emitting debug-level log messages, e.g.\n\n```ruby\nlogger = GreenLog::Logger.build(severity_threshold: :INFO)\n# OR\nlogger = GreenLog::Logger.build.with_severity_threshold(:INFO)\n\nlog.debug(\"Whatever\") # ignored\n```\n\n### Block form\n\nRather than passing arguments, you can provide a block to generate log messages:\n\n```ruby\nlogger.info do\n  \"generated message\"\nend\n# outputs: I -- generated message\n```\n\nThe block may be ignored, if a severity-threshold is in effect:\n\n```ruby\nlogger = GreenLog::Logger.build(severity_threshold: :INFO)\n\nlog.debug do\n  # not evaluated\nend\n```\n\n### Compatibility with stdlib Logger\n\nGreenLog includes a backward-compatibile adapter for code written to use Ruby's built-in [`Logger`](https://ruby-doc.org/stdlib-2.4.0/libdoc/logger/rdoc/Logger.html):\n\n```ruby\nrequire 'green_log/classic_logger'\n\nlegacy_logger = logger.to_classic_logger\nlegacy_logger.warn(\"Old skool\")\n# outputs: W -- Old skool\n```\n\n### Rack request-logging\n\nGreenLog bundles a Rack middleware - an alternative to [`Rack::CommonLogger`](https://www.rubydoc.info/gems/rack/Rack/CommonLogger) - that generates structured HTTP access logs:\n\n```ruby\nrequire \"green_log\"\nrequire \"green_log/rack/request_logging\"\n\nlogger = GreenLog::Logger.build(format: \"json\")\nuse GreenLog::Rack::RequestLogging, logger\n```\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/mdub/green_log.\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmdub%2Fgreen_log","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmdub%2Fgreen_log","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmdub%2Fgreen_log/lists"}