From 6e2100cb2c2bb4023cd4db846bd8d681b41e7655 Mon Sep 17 00:00:00 2001 From: Patrick Haun Date: Tue, 21 Nov 2023 11:40:02 +0100 Subject: [PATCH] use markdown --- README.md | 146 +++++++++++++++++++++++++++++++++++++++++++++++++++++ README.org | 137 ------------------------------------------------- 2 files changed, 146 insertions(+), 137 deletions(-) create mode 100644 README.md delete mode 100644 README.org diff --git a/README.md b/README.md new file mode 100644 index 0000000..6b7d41c --- /dev/null +++ b/README.md @@ -0,0 +1,146 @@ +![](./logo/fblog_small.png) + +# fblog + + +A small tool to view json log files. + +![](demo.png) + +## Print specific fields + +``` shell-script +fblog -a message -a "status > a" sample_nested.json.log +``` + +## Prefix Logs + +If your query docker or kubectl for multiple pods it will prefix the log +lines: `PODNAME | {"message": "test"}`. `fblog` can parse this and add +it to the message. Just use `-p`. + +## Filter + +To filter log messages it is possible to use lua. If you are unsure +which variables are available you can use `--print-lua` to see the code +generated by fblog. + +```bash +fblog -f 'level ~= "info"' # will print all message where the level is not info +fblog -f 'process == "play"' # will print all message where the process is play +fblog -f 'string.find(fu, "bow.*") ~= nil' # will print all messages where fu starts with bow +fblog -f 'process == "play"' # will print all message where the process is play +fblog -f 'process == "rust" and fu == "bower"' +fblog --no-implicit-filter-return-statement -f 'if 3 > 2 then return true else return false end' + +# not valid lua identifiers like log.level gets converted to log_level. +# Every character that is not _ or a letter will be converted to _ +fblog -d -f 'log_level == "WARN"' sample_elastic.log + +# nested fields are converted to lua records +fblog -d -f 'status.a == 100' sample_nested.json.log + +# array fields are converted to lua tables (index starts with 1) +fblog -d -f 'status.d[2] == "a"' sample_nested.json.log +``` + +## Customize + +`fblog` tries to detect the message, severity and timestamp of a log +entry. This behavior can be customized. See `--help` for more +information. + +You can customize fblog messages: Format output: + +``` shell-script +fblog -p --main-line-format "{{#if short_message}}{{ red short_message }}{{/if}}" sample.json.log +``` + +The following sanitized variables are provided by fblog: + +- fblog_timestamp +- fblog_level +- fblog_message +- fblog_prefix + +For the default formatting see `--help` + +Nested values are registered as objects. So you can use `nested.value` +to access nested values. + +handlebar helpers: + +- bold +- yellow +- red +- blue +- purple +- green +- color~rgb~ 0 0 0 +- uppercase +- level~style~ +- fixed~size~ 10 + +## NO_COLOR + +`fblog` disables color output if the `NO_COLOR` environment variable is +present. + +[no-color](https://no-color.org/) + +## Message placeholder substitution + +Placeholders in the message (`fblog_message`) can be substituted with +their corresponding values in a context object or array. To enable +substitutions, pass the `-s` flag or either set context key +(`-c context`) or placeholder format (`-F {key}`). + +Note that the placeholder format should be written like +`key`, where it would match a placeholder with the key +`key`. + +### Example + +Given the following log (referred to as `example.log`): + +``` json +{"message": "Found #{count} new items.", "extra_data": {"count": 556}, "level": "info"} +``` + +Running with the following arguments: + +``` bash +fblog -c extra_data -F '#{key}' example.log +``` + +Result: + +![](./res/placeholder-example1.svg) + +## Installation + +``` bash +cargo install fblog +``` + +Available in package managers: +[AUR](https://aur.archlinux.org/packages/fblog/), +[brew](https://formulae.brew.sh/formula/fblog) + +## Log tailing + +`fblog` does not support native log tailing but this is easily +achiveable. + +``` bash +tail -f file | fblog +``` + +Or with kubernetes tooling for example + +``` bash +kubectl logs -f ... | fblog +``` + +In general you can pipe any endless stream to fblog. + diff --git a/README.org b/README.org deleted file mode 100644 index f451988..0000000 --- a/README.org +++ /dev/null @@ -1,137 +0,0 @@ -[[./logo/fblog_small.png]] - -* fblog - - [[https://crates.io/crates/fblog][file:https://img.shields.io/crates/v/fblog.svg]] - [[https://github.com/brocode/fblog/blob/nested-values/.github/workflows/rust.yml][file:https://github.com/brocode/fblog/actions/workflows/rust.yml/badge.svg?branch=master]] - - A small tool to view json log files. - - [[file:demo.png]] - - - -** Print specific fields - - #+BEGIN_SRC shell-script - fblog -a message -a "status > a" sample_nested.json.log - #+END_SRC - -** Prefix Logs - - If your query docker or kubectl for multiple pods it will prefix - the log lines: ~PODNAME | {"message": "test"}~. ~fblog~ can parse this and add it to - the message. Just use ~-p~. - - -** Filter - To filter log messages it is possible to use lua. If you are unsure - which variables are available you can use ~--print-lua~ to see the - code generated by fblog. - - #+BEGIN_SRC shell-script - fblog -f 'level ~= "info"' # will print all message where the level is not info - fblog -f 'process == "play"' # will print all message where the process is play - fblog -f 'string.find(fu, "bow.*") ~= nil' # will print all messages where fu starts with bow - fblog -f 'process == "play"' # will print all message where the process is play - fblog -f 'process == "rust" and fu == "bower"' - fblog --no-implicit-filter-return-statement -f 'if 3 > 2 then return true else return false end' - - # not valid lua identifiers like log.level gets converted to log_level. - # Every character that is not _ or a letter will be converted to _ - fblog -d -f 'log_level == "WARN"' sample_elastic.log - - # nested fields are converted to lua records - fblog -d -f 'status.a == 100' sample_nested.json.log - - # array fields are converted to lua tables (index starts with 1) - fblog -d -f 'status.d[2] == "a"' sample_nested.json.log - #+END_SRC - -** Customize - ~fblog~ tries to detect the message, severity and timestamp of a log - entry. This behavior can be customized. See ~--help~ for more - information. - - You can customize fblog messages: - Format output: - #+BEGIN_SRC shell-script - fblog -p --main-line-format "{{#if short_message}}{{ red short_message }}{{/if}}" sample.json.log - #+END_SRC - - The following sanitized variables are provided by fblog: - - * fblog_timestamp - * fblog_level - * fblog_message - * fblog_prefix - - For the default formatting see ~--help~ - - Nested values are registered as objects. So you can use ~nested.value~ to access nested values. - - handlebar helpers: - - * bold - * yellow - * red - * blue - * purple - * green - * color_rgb 0 0 0 - * uppercase - * level_style - * fixed_size 10 - -** NO_COLOR - ~fblog~ disables color output if the ~NO_COLOR~ environment variable is present. - - [[https://no-color.org/][no-color]] - -** Message placeholder substitution - Placeholders in the message (~fblog_message~) can be substituted with their corresponding values in a context object or array. - To enable substitutions, pass the ~-s~ flag or either set context key (~-c context~) or placeholder format (~-F {key}~). - - Note that the placeholder format should be written like ~key~, where it would match a placeholder with the key ~key~. - -*** Example - Given the following log (referred to as ~example.log~): - #+BEGIN_SRC json - {"message": "Found #{count} new items.", "extra_data": {"count": 556}, "level": "info"} - #+END_SRC - - Running with the following arguments: - #+BEGIN_SRC bash - fblog -c extra_data -F '#{key}' example.log - #+END_SRC - - Result: - - [[./res/placeholder-example1.svg]] - -** Installation - #+BEGIN_SRC bash - cargo install fblog - #+END_SRC - - Available in package managers: [[https://aur.archlinux.org/packages/fblog/][AUR]], [[https://formulae.brew.sh/formula/fblog][brew]] - - -** Log tailing - ~fblog~ does not support native log tailing but this is easily achiveable. - - #+BEGIN_SRC bash - tail -f file | fblog - #+END_SRC - - Or with kubernetes tooling for example - - #+BEGIN_SRC bash - kubectl logs -f ... | fblog - #+END_SRC - - In general you can pipe any endless stream to fblog. - -** Discord - In the case you want to talk about new features or give us direct feedback, - you can join the [[https://rawkode.chat/][Discord]] (Thanks [[https://github.com/rawkode][@rawkode]]) in the channel ~#fblog~.