{"id":19546011,"url":"https://github.com/hewlettpackard/woodchipper","last_synced_at":"2025-04-24T04:05:15.977Z","repository":{"id":53726871,"uuid":"189106114","full_name":"HewlettPackard/woodchipper","owner":"HewlettPackard","description":"An interactive command-line log processor","archived":false,"fork":false,"pushed_at":"2024-10-30T23:09:58.000Z","size":341,"stargazers_count":23,"open_issues_count":38,"forks_count":4,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-02-09T07:03:59.771Z","etag":null,"topics":["cli","kubernetes","logging","rust","terminal"],"latest_commit_sha":null,"homepage":"","language":"Rust","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/HewlettPackard.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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":"2019-05-28T21:30:22.000Z","updated_at":"2023-12-27T08:35:23.000Z","dependencies_parsed_at":"2024-11-11T03:42:45.148Z","dependency_job_id":"0da695a8-66d2-4a53-8ca6-4ec57361fbbe","html_url":"https://github.com/HewlettPackard/woodchipper","commit_stats":{"total_commits":64,"total_committers":3,"mean_commits":"21.333333333333332","dds":0.171875,"last_synced_commit":"6874ef05d98c9bf8702e2aba2245b64d49ee8dcc"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HewlettPackard%2Fwoodchipper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HewlettPackard%2Fwoodchipper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HewlettPackard%2Fwoodchipper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HewlettPackard%2Fwoodchipper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/HewlettPackard","download_url":"https://codeload.github.com/HewlettPackard/woodchipper/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240571029,"owners_count":19822413,"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":["cli","kubernetes","logging","rust","terminal"],"created_at":"2024-11-11T03:42:38.406Z","updated_at":"2025-02-24T22:45:36.685Z","avatar_url":"https://github.com/HewlettPackard.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# woodchipper\n\n[![CircleCI](https://circleci.com/gh/HewlettPackard/woodchipper.svg?style=svg)](https://circleci.com/gh/HewlettPackard/woodchipper)\n\nFollow, transform, and explore all your unwieldly microservice logs from the\nterminal.\n\n * Ingests logs in any format, in real-time\n * Converts all logs to one of several unified formats:\n    * formatted plain-text for sharing\n    * stylized and wrapped for easy reading\n    * JSON for machine processing\n * Interactive terminal interface adds painless searching, filtering, text\n   reflow, and clipboard support\n * Built-in Kubernetes support follows multiple pods and containers at\n   once\n * User-customizable output styles and custom log formats (see [customization])\n\n## Quick Start\n\n 1. Grab a pre-built binary from the [releases page][releases] or run:\n\n    ```bash\n    cargo install woodchipper\n    ```\n\n    See the [install page](./doc/install.md) for detailed instructions.\n\n 2. Follow some logs:\n    ```bash\n    tail -f /var/log/my-app.log | woodchipper\n    ```\n\n 3. Use the [`kubectl` plugin][plugin] wrapper script and watch some pods:\n\n    ```bash\n    kubectl woodchipper -n my-namespace app=my-app\n    ```\n\n## Usage\n\nPipe any logs to `woodchipper`:\n\n```bash\ncat my-log.txt | woodchipper\n```\n\nThis opens the interactive viewer by default. Use up, down, page up, page\ndown, home, and end to navigate.\n\nwoodchipper also follows any streaming output:\n```bash\n./some-long-running-script.sh | woodchipper\n```\n\nWhen piped, woodchipper automatically outputs nicely formatted plaintext,\nappropriate for sharing:\n\n```bash\n./some-hard-to-read-json-logs.sh | woodchipper | cat\n```\n\nAlternatively, if you'd just like to print the colorized logs to your terminal:\n```bash\n./logs.sh | woodchipper -r styled\n```\n\nIf you don't like the interactive viewer but still want a pager, try `less`:\n```bash\ncat logs.txt | woodchipper -r styled | less\n```\n\n(try `less -R` if your `less` doesn't pass through ANSI escapes by default)\n\n### Interactive Viewer\n\nThe interactive viewer provides an improved pager with regex searching and\nfiltering. It's enabled by default if woodchipper is attached to a tty.\n\nA number of keyboard shortcuts are available:\n\n * `up`, `down`: move the cursor one message at a time\n * `page up`, `page down`: scroll one screenful at a time\n * `home`, `end`: move to the start or end of all messages\n * `f`, `|`: add a filter to the stack\n   * a filter regex may be freely entered\n   * invalid filter regexes are highlighted in red\n   * matching messages are highlighted as you type\n   * `enter`: add the filter to the stack and remove all non-matching messages\n   * `esc`: cancel filter\n * `p`: pop the last filter from the stack\n * `/`, `ctrl-f`: search for a particular message; when in filter mode:\n   * a search regex may be freely entered\n   * invalid search regexes are highlighted in red\n   * all matching messages will be highlighted; the cursor will jump to the\n     nearest forward match as you type\n   * `enter`: next match\n   * `ctrl-p`: previous match\n   * `esc`: end search; if a result is highlighted, it will remain highlighted\n * `c`: copy the selected message to the clipboard as shareable plain text\n * `shift-c`: copy the current screen to the clipboard as shareable plain text\n * `q`: quit\n\nThe interactive viewer works best with terminal emulators that treat mouse wheel\ninput as up / down keypresses when in alternate screen mode. KDE's Konsole\nbehaves this way by default, and this may be enabled in iTerm2 in Preferences -\u003e\nAdvanced -\u003e Mouse -\u003e \"Scroll wheel sends arrow keys when in alternative screen\nmode\". An option to capture mouse events on all terminals may be added in the\nfuture, however doing so disables text selection and isn't ideal.\n\n### kubectl plugin\n\n\u003e *For `kubectl` 1.13+, [read more][kubectl-plugins]*\n\nTo make full use of the Kubernetes integration:\n\n * Ensure `kubectl` is available and configured on your `$PATH`\n * Install the [wrapper script][plugin] on your `$PATH`\n\nWoodchipper uses `kubectl proxy` to access the Kubernetes API, so it can\nconnect to your cluster if `kubectl` can.\n\nTo follow a pod named `my-pod-1234`, run:\n```bash\nkubectl woodchipper -n my-namespace my-pod-1234\n```\n\nAlternatively, if you don't want to use the kubectl plugin, this is equivalent:\n```bash\nwoodchipper --reader=kubernetes -n my-namespace my-pod-1234\n```\n\nWoodchipper matches pods continually using substrings, so a partial pod name\nwill follow pods even between restarts or deployment upgrades:\n```bash\nwoodchipper --reader=kubernetes -n my-namespace my-pod\n```\n\nMultiple substrings can be used:\n```bash\nkubectl woodchipper -n my-namespace my-pod my-other-pod\n```\n\nAlternatively, if you give it a label-like selector, it will perform a label\nquery:\n```bash\nkubectl woodchipper -n my-namespace app=my-app\n```\n\nNote that only one label selector may be used at a time.\n\nWoodchipper honors your configured `kubectl` default namespace, so you can\nleave off `-n my-namespace` if `kubectl` is configured to use it already.\nAlternatively, the `WD_NAMESPACE` environment variable can be set to override\nthe default.\n\n[kubectl-plugins]: https://kubernetes.io/docs/tasks/extend-kubectl/kubectl-plugins/\n\n## Supported Log Formats\n\nWoodchipper can parse, format, and stylize any of the following logs,\npotentially mixed together:\n\n * Several varieties of JSON logs, e.g. `{\"time\": \"...\", \"msg\": \"hello world\"}`\n * [logrus]-style key/value pair logs, e.g. `time=\"...\" msg=\"hello world\"`\n * [klog] logs for Kubernetes components\n * Plaintext logs with inferred timestamps and log levels\n * User-specified custom formats with the [regex parser][regex]\n\n## Similar Projects\n\n * [stern] has similar Kubernetes tailing features\n * [logrus] has built-in pretty printing when a TTY is attached\n * [slog] provides structured pretty printing\n * [less] supports paging, searching, and input following\n\n## Contributing\n\nBug reports, feature requests, and pull requests are welcome! Be sure to read\nthough the [code of conduct] for some pointers to get started.\n\nNote that - as mentioned in the code of conduct - code contributions must\nindicate that you accept the [Developer Certificate of Origin][dco],\nessentially indicating you have rights to the code you're contributing and\nthat you agree to the project's license (MIT). With the Git CLI, simply pass\n`-s` to `git commit`:\n\n```bash\ngit commit -s [...]\n```\n\n... and Git will automatically append the required `Signed-off-by: ...` to the\nend of your commit message.\n\nAdditionally, the [design documentation][design] may be a helpful resource for\nunderstanding how woodchipper works.\n\n[customization]: ./doc/customization.md\n[plugin]: ./misc/kubectl-woodchipper\n[releases]: https://github.com/HewlettPackard/woodchipper/releases/latest\n[klog]: https://github.com/kubernetes/klog\n[regex]: ./doc/customization.md#log-formats\n[stern]: https://github.com/wercker/stern\n[logrus]: https://github.com/sirupsen/logrus\n[slog]: https://github.com/slog-rs/slog\n[less]: https://www.gnu.org/software/less/\n[code of conduct]: ./CODE_OF_CONDUCT.md\n[dco]: https://developercertificate.org/\n[design]: ./doc/design/design.md\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhewlettpackard%2Fwoodchipper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhewlettpackard%2Fwoodchipper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhewlettpackard%2Fwoodchipper/lists"}