{"id":13530054,"url":"https://github.com/juan-leon/lowcharts","last_synced_at":"2025-04-01T17:31:47.989Z","repository":{"id":38393538,"uuid":"359171406","full_name":"juan-leon/lowcharts","owner":"juan-leon","description":"Tool to draw low-resolution graphs in terminal","archived":false,"fork":false,"pushed_at":"2024-09-11T14:09:37.000Z","size":429,"stargazers_count":214,"open_issues_count":8,"forks_count":5,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-03-05T12:46:17.202Z","etag":null,"topics":["analysis","command-line","log","plot","shell","statistics","stats","troubleshooting"],"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/juan-leon.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","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":"2021-04-18T14:50:09.000Z","updated_at":"2025-02-24T07:43:18.000Z","dependencies_parsed_at":"2023-02-09T23:00:24.449Z","dependency_job_id":"2b531ea2-4529-4e49-8a56-eb5bffb050f2","html_url":"https://github.com/juan-leon/lowcharts","commit_stats":{"total_commits":125,"total_committers":6,"mean_commits":"20.833333333333332","dds":0.28,"last_synced_commit":"257e467477f227b3ed2f61d69e8afec3cbb40ce7"},"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/juan-leon%2Flowcharts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/juan-leon%2Flowcharts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/juan-leon%2Flowcharts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/juan-leon%2Flowcharts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/juan-leon","download_url":"https://codeload.github.com/juan-leon/lowcharts/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246680354,"owners_count":20816684,"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":["analysis","command-line","log","plot","shell","statistics","stats","troubleshooting"],"created_at":"2024-08-01T07:00:42.682Z","updated_at":"2025-04-01T17:31:47.520Z","avatar_url":"https://github.com/juan-leon.png","language":"Rust","funding_links":[],"categories":["Rust","Graphics","Command-Line Productivity","\u003ca name=\"data-management\"\u003e\u003c/a\u003eData management"],"sub_categories":["Image Conversion"],"readme":"# lowcharts\nTool to draw low-resolution graphs in terminal.\n\n[![Rust](https://github.com/juan-leon/lowcharts/actions/workflows/test.yml/badge.svg)](https://github.com/juan-leon/lowcharts/actions/workflows/test.yml)\n[![codecov](https://codecov.io/gh/juan-leon/lowcharts/branch/main/graph/badge.svg?token=FNTO8M149T)](https://codecov.io/gh/juan-leon/lowcharts)\n[![dependency status](https://deps.rs/repo/github/juan-leon/lowcharts/status.svg)](https://deps.rs/repo/github/juan-leon/lowcharts)\n[![Release](https://img.shields.io/github/release/juan-leon/lowcharts.svg)](https://github.com/juan-leon/lowcharts/releases/latest)\n\n**lowcharts** is meant to be used in those scenarios where we have numerical\ndata in text files that we want to display in the terminal to do a basic\nanalysis.\n\nAn example would be the logs of a service (webserver, database, proxy, container\norchestration, etc.) where times (or sizes) of requests are logged.  In an ideal\nworld you would have those logs accessible via a kibana (or similar) or those\nmetrics exposed to a prometheus (or similar) and graphed in a grafana dashboard\n(or similar).  But sometimes we need to cope with non ideal worlds, and\ntroubleshoot a service with nothing more of what we can muster in a shell\nterminal.\n\n### Usage\n\nType `lowcharts --help`, or `lowcharts PLOT-TYPE --help` for a complete list of\noptions.\n\nCurrently six basic types of plots are supported:\n\n#### Bar chart for matches in the input\n\nSince `grep -c` does not aggregate counts per pattern, this is maybe my most frequent use case.\n\nThis chart is generated using `lowcharts matches --input database.log SELECT UPDATE DELETE INSERT DROP`:\n\n[![Simple bar chart with lowcharts](resources/matches-example.png)](resources/matches-example.png)\n\n#### Histogram for numerical inputs\n\nThis chart is generated using `python3 -c 'import random; [print(random.normalvariate(5, 5)) for _ in range(100000)]' | lowcharts hist`:\n\n[![Sample histogram with lowcharts](resources/histogram-example.png)](resources/histogram-example.png)\n\nThis was inspired by [data-hacks](https://github.com/bitly/data_hacks).\nHowever, for some big log files I found that project was a lot slower than what\nI would like, and I found that a rust-compiled binary was better suited to my\nneeds: easy to copy around in a hurry (no deps) and very fast.\n\n\nOptions for specifying ranges, chart sizes and input files are supported:\n\n```\nlowcharts hist --max 0.5 --intervals 10 --width 50 data.txt\nSamples = 50090; Min = 0.000; Max = 0.499\nAverage = 0.181; Variance = 0.023; STD = 0.154\neach ∎ represents a count of 484\n[0.000 .. 0.050] [14545] ∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎\n[0.050 .. 0.100] [ 6111] ∎∎∎∎∎∎∎∎∎∎∎∎\n[0.100 .. 0.150] [ 4911] ∎∎∎∎∎∎∎∎∎∎\n[0.150 .. 0.200] [ 4003] ∎∎∎∎∎∎∎∎\n[0.200 .. 0.250] [ 3745] ∎∎∎∎∎∎∎\n[0.250 .. 0.300] [ 3526] ∎∎∎∎∎∎∎\n[0.300 .. 0.350] [ 3424] ∎∎∎∎∎∎∎\n[0.350 .. 0.400] [ 3332] ∎∎∎∎∎∎\n[0.400 .. 0.450] [ 3215] ∎∎∎∎∎∎\n[0.450 .. 0.500] [ 3278] ∎∎∎∎∎∎\n```\n\nAbove examples assume input files with a number per line.  Options for figuring\nout where to look in the input file for values are supported by `regex` option.\nThis example logs the time spent by nginx for all of 200K http responses ()\n\n\n```\n$ cat nginx*.log | lowcharts hist --regex ' 200 \\d+ ([0-9.]+)' --intervals 10\nSamples = 25080; Min = 0.004; Max = 0.049\nAverage = 0.008; Variance = 0.000; STD = 0.006\neach ∎ represents a count of 228\n[0.004 .. 0.009] [20569] ∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎\n[0.009 .. 0.013] [ 1329] ∎∎∎∎∎\n[0.013 .. 0.018] [  807] ∎∎∎\n[0.018 .. 0.022] [ 1412] ∎∎∎∎∎∎\n[0.022 .. 0.027] [  363] ∎\n[0.027 .. 0.031] [   27]\n[0.031 .. 0.036] [  128]\n[0.036 .. 0.040] [   22]\n[0.040 .. 0.044] [  240] ∎\n[0.044 .. 0.049] [  183]\n```\n\nCommand supports a `--log-scale` flag to use a logarithmic scale.\n\n#### Time Histogram\n\nThis chart is generated using  `strace -tt ls -lR * 2\u003e\u00261 | lowcharts timehist --intervals 10`:\n\n[![Sample plot with lowcharts](resources/timehist-example.png)](resources/timehist-example.png)\n\nThings like `lowcharts timehist --regex ' 404 ' nginx.log` should work in a\nsimilar way, and would give you a glimpse of when and how many 404s are being\ntriggered in your server.\n\nThe idea is to depict the frequency of logs that match a regex (by default any\nlog that is read by the tool).  The sub-command can autodetect the most common\n(in my personal and biased experience) datetime/timestamp formats: rfc 3339, rfc\n2822, python `%(asctime)s`, golang default log format, nginx, rabbitmq, strace\n-t (or -tt, or -ttt), ltrace,... as long as the timestamp is present in the\nfirst line in the log and the format is consistent in all the lines that contain\ntimestamp.  It is ok to have lines with no timestamp.  The consistency is\nrequired because of performance reasons: the 1st log line is the only one that\ntriggers the heuristics needed to create an specialized datetime parser on the\nfly.\n\nHowever, if you have a format that lowcharts cannot autodetected, you can\nspecify it via command line flag.  For instance, `--format\n'%d-%b-%Y::%H:%M:%S'`.  Note that, as of today, you need to leave out the\ntimezone part of the format string (the autodetection works fine with\ntimezones).\n\n\n#### Split Time Histogram\n\nThis adds up the time histogram and bar chart in a single visualization.\n\nThis chart is generated using `strace -tt ls -lR 2\u003e\u00261 | lowcharts split-timehist open mmap close read write --intervals 10`:\n\n[![Sample plot with lowcharts](resources/split-timehist-example.png)](resources/split-timehist-example.png)\n\nThis graph depicts the relative frequency of search terms in time.\n\n#### Common terms histogram\n\nUseful for plotting most common terms in input lines.\n\nThis sample chart is generated using `strace ls -l 2\u003e\u00261 | lowcharts common-terms --lines 8 -R '(.*?)\\('`:\n\n[![Sample plot with lowcharts](resources/common-terms-example.png)](resources/common-terms-example.png)\n\nThe graph depicts the 8 syscalls most used by `ls -l` command, along with its\nnumber of uses and sorted.  In general, using `lowcharts common-terms` is a\nhandy substitute to commands of the form `awk ... | sort | uniq -c | sort -rn |\nhead`.\n\n#### X-Y Plot\n\nThis chart is generated using  `cat ram-usage | lowcharts plot --height 20 --width 50`:\n\n[![Sample plot with lowcharts](resources/plot-example.png)](resources/plot-example.png)\n\nNote that x axis is not labelled.  The tool splits the input data by chunks of a\nfixed size and then the chart display the averages of those chunks.  In other\nwords: grouping data by time is not (yet?) supported; you can see the evolution\nof a metric over time, but not the speed of that evolution.\n\nThere is regex support for this type of plots.\n\n### Installing\n\n#### Via release\n\nGo over https://github.com/juan-leon/lowcharts/releases/ and download the binary\nyou want.  Decompress the file and copy the binary to your path.\n\n#### Via local compilation\n\n```\n$ git clone https://github.com/juan-leon/lowcharts\n$ cd lowcharts\n$ cargo install --path .\n```\n\n#### Via AUR\n\nArch-Linux users can install the\n[lowcharts](https://aur.archlinux.org/packages/lowcharts),\n[lowcharts-bin](https://aur.archlinux.org/packages/lowcharts-bin) or\n[lowcharts-git](https://aur.archlinux.org/packages/lowcharts-git) AUR package.\n\n#### Via debian package\n\nIf you are using a debian based Linux distribution, you may download a debian\nfile from https://github.com/juan-leon/lowcharts/releases/ for your\narchitecture.  Then you can install it via `dpkg -i`.\n\n### Using it as a library\n\n`lowcharts` can be used as a library by any code that needs to display text\nbased charts.\n\n```toml\n[dependencies]\nlowcharts = \"*\"\n```\n\nExample:\n\n```rust\nuse lowcharts::plot;\n\nlet vec = \u0026[-1.0, -1.1, 2.0, 2.0, 2.1, -0.9, 11.0, 11.2, 1.9, 1.99];\n// Plot a histogram of the above vector, with 4 buckets and a precision\n// chosen by library\nlet options = plot::HistogramOptions { intervals: 4, ..Default::default() };\nlet histogram = plot::Histogram::new(vec, options);\nprint!(\"{}\", histogram);\n```\n\nYou can disable coloring by doing:\n\n```rust\n// use yansi::Paint;\nPaint::disable();\n```\n\nYou can find the documentation [here](https://docs.rs/lowcharts/latest/lowcharts/).\n\n### Contributing\n\nFeedback, ideas and pull requests are welcomed.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjuan-leon%2Flowcharts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjuan-leon%2Flowcharts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjuan-leon%2Flowcharts/lists"}