Skip to content

Commit 2c8b2ce

Browse files
AuHauAuHau
authored
docs: readme (#4)
1 parent 08a49e7 commit 2c8b2ce

File tree

3 files changed

+446
-22
lines changed

3 files changed

+446
-22
lines changed

‎README.md‎

Lines changed: 139 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,140 @@
11
# loggy
2-
Small logging utility swiss-knife
2+
---
3+
4+
[![Go Report Card](https://goreportcard.com/badge/github.com/auhau/loggy)](https://goreportcard.com/report/github.com/auhau/loggy)
5+
[![Build Status](https://img.shields.io/endpoint.svg?url=https%3A%2F%2Factions-badge.atrox.dev%2Fauhau%2Floggy%2Fbadge&style=flat&label=build)](https://actions-badge.atrox.dev/auhau/loggy/goto)
6+
7+
> Swiss knife for logs
8+
9+
## Installation
10+
11+
### Automatic installation script
12+
13+
```shell
14+
$ curl -sSL https://raw.githubusercontent.com/auhau/loggy/master/install.sh | bash
15+
```
16+
17+
### Ubuntu / Debian / Raspbian / CentOS
18+
19+
`deb` and `rpm` packages are build. Get the one for your OS
20+
from [latest release](https://github.com/auhau/loggy/releases/latest) page and run `sudo dpkg -i <package>.deb` or
21+
`sudo rpm -i <package>.rpm`.
22+
23+
### Gophers
24+
25+
If you've already got a Go development environment set up, you can grab it like this:
26+
27+
```shell
28+
$ go get github.com/auhau/loggy
29+
```
30+
31+
### Homebrew
32+
33+
```shell
34+
$ brew tap auhau/loggy
35+
$ brew install loggy
36+
```
37+
38+
### Scoop
39+
40+
```
41+
scoop bucket add org https://github.com/auhau/scoop.git
42+
scoop install org/loggy
43+
```
44+
45+
### Manual
46+
47+
Download on to your `$PATH` loggy binary for your operating system and architecture
48+
from [latest release](https://github.com/auhau/loggy/releases/latest) page.
49+
50+
## Usage
51+
52+
See `loggy --help` for this usage:
53+
54+
```
55+
By default loggy reads from STDIN or you can specify file path to read the logs from specific file.
56+
57+
Configuration
58+
-------------
59+
All options that can be passed using CLI flags can be configured using config file or environment variables.
60+
loggy looks for a config file ".loggy.toml" in current working directory and in $HOME folder.
61+
Moreover you can use environment variables with "LOGGY_" prefix, where for example flag "--pattern" would be "LOGGY_PATTERN" env. variable.
62+
The order of precedence is: $HOME config > CWD config > --config config > Env. variables > CLI flags.
63+
64+
Parsing pattern
65+
---------------
66+
The logs are parsed using parsing pattern that you have to configure in order to use filters. The lines are tokenized using space character so you have to define section of the line. Internally regex is used for parsing, but the input pattern is escaped by default for special characters so you don't have to worry about that. You define parameters using syntax "<name:type>", where name is the name of parameter that you can refer to in filters and type is predefined type used to correctly find and parse the parameter.
67+
68+
Supported types:
69+
- "string" defines string containing non-whitespace characters: [^\s]+
70+
- "integer" defines a integer: [0-9]+
71+
- "rest" collects the rest of the line: .*
72+
73+
Example log and bellow its parsing pattern:
74+
[2022-09-11T15:04:22](authorization) DEBUG 200 We have received login information
75+
[<timestamp:string>](<component:string>) <level:string> <code:integer> <message:rest>
76+
77+
Pattern names
78+
-------------
79+
In your config file you can create a [patterns] section where you can predefine your patterns using <name>="<pattern>" syntax and then use --pattern-name/-n flag to use it.
80+
81+
Filter
82+
------
83+
In order to use filter for the logs you have to define parsing pattern in which you define parameters that are extracted from the log lines. Then you can write filter expressions that will be applied on the logs. Filter has to return bool otherwise error will be shown.
84+
85+
loggy uses internally "govaluate" which has very rich set ofC-like artithmetic/string expressions that you can use for your filters. Brief overview:
86+
- modifiers: + - / * & | ^ ** % >> <<
87+
- comparators: > >= < <= == != =~ !~
88+
- logical ops: || &&
89+
- numeric constants, as 64-bit floating point (12345.678)
90+
- string constants (single quotes: 'foobar')
91+
- date constants (single quotes, using any permutation of RFC3339, ISO8601, ruby date, or unix date; date parsing is automatically tried with any string constant)
92+
- boolean constants: true false
93+
- parenthesis to control order of evaluation ( )
94+
- arrays (anything separated by , within parenthesis: (1, 2, 'foo'))
95+
- prefixes: ! - ~
96+
- ternary conditional: ? :
97+
- null coalescence: ??
98+
99+
For more details see: https://github.com/Knetic/govaluate/blob/master/MANUAL.md
100+
101+
Example of filter for the parsing pattern log above:
102+
level == "DEBUG" - display only debug messages
103+
code > 400 - display logs with code higher then 400
104+
105+
Keyboard shortcuts
106+
------------------
107+
Following keys are supported:
108+
- "/" for setting filter
109+
- "f" for toggling filter
110+
- "p" for setting parsing pattern input
111+
- "b" for scroll to bottom and follow new data
112+
- "h" for displaying help
113+
114+
Navigation:
115+
- "j", "k" or arrow keys for scrolling by one line
116+
- "g", "G" to move to top / bottom
117+
- "Ctrl-F", "page down" to move down by one page
118+
- "Ctrl-B", "page up" to move up by one page
119+
- "Ctrl-C" to exit loggy
120+
121+
Usage:
122+
loggy [path to log file] [flags]
123+
124+
Flags:
125+
-b, --buffer-size int number of lines that will be buffered (default 10000)
126+
--config string config file (default is $HOME/.loggy.yaml)
127+
-h, --help help for loggy
128+
-p, --pattern string parsing pattern see above for details
129+
-n, --pattern-name string use predefined pattern in config
130+
```
131+
132+
## Contribute
133+
134+
PRs are welcome!
135+
If you plan to make some bigger change then please discuss it previously in Issue so there would not be any
136+
misunderstanding and your work would get merged!
137+
138+
## License
139+
140+
[MIT](./LICENSE)

‎cmd/cmd.go‎

Lines changed: 84 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ import (
44
"fmt"
55
"github.com/auhau/loggy/store"
66
"github.com/auhau/loggy/ui"
7+
"github.com/chonla/format"
78
"io"
89
"os"
910

@@ -24,6 +25,73 @@ const (
2425
DEFAULT_BUFFER_SIZE = 10000
2526
)
2627

28+
var LONG_DESCRIPTION = format.Sprintf(`By default loggy reads from STDIN or you can specify file path to read the logs from specific file.
29+
30+
Configuration
31+
-------------
32+
All options that can be passed using CLI flags can be configured using config file or environment variables.
33+
loggy looks for a config file ".loggy.toml" in current working directory and in $HOME folder.
34+
Moreover you can use environment variables with "LOGGY_" prefix, where for example flag "--pattern" would be "LOGGY_PATTERN" env. variable.
35+
The order of precedence is: $HOME config > CWD config > --config config > Env. variables > CLI flags.
36+
37+
Parsing pattern
38+
---------------
39+
The logs are parsed using parsing pattern that you have to configure in order to use filters. The lines are tokenized using space character so you have to define section of the line. Internally regex is used for parsing, but the input pattern is escaped by default for special characters so you don't have to worry about that. You define parameters using syntax "<name:type>", where name is the name of parameter that you can refer to in filters and type is predefined type used to correctly find and parse the parameter.
40+
41+
Supported types:
42+
- "string" defines string containing non-whitespace characters: [^\s]+
43+
- "integer" defines a integer: [0-9]+
44+
- "rest" collects the rest of the line: .*
45+
46+
Example log and bellow its parsing pattern:
47+
[2022-09-11T15:04:22](authorization) DEBUG 200 We have received login information
48+
[<timestamp:string>](<component:string>) <level:string> <code:integer> <message:rest>
49+
50+
Pattern names
51+
-------------
52+
In your config file you can create a [patterns] section where you can predefine your patterns using <name>="<pattern>" syntax and then use --pattern-name/-n flag to use it.
53+
54+
Filter
55+
------
56+
In order to use filter for the logs you have to define parsing pattern in which you define parameters that are extracted from the log lines. Then you can write filter expressions that will be applied on the logs. Filter has to return bool otherwise error will be shown.
57+
58+
loggy uses internally "govaluate" which has very rich set ofC-like artithmetic/string expressions that you can use for your filters. Brief overview:
59+
- modifiers: + - / * & | ^ ** %% >> <<
60+
- comparators: > >= < <= == != =~ !~
61+
- logical ops: || &&
62+
- numeric constants, as 64-bit floating point (12345.678)
63+
- string constants (single quotes: 'foobar')
64+
- date constants (single quotes, using any permutation of RFC3339, ISO8601, ruby date, or unix date; date parsing is automatically tried with any string constant)
65+
- boolean constants: true false
66+
- parenthesis to control order of evaluation ( )
67+
- arrays (anything separated by , within parenthesis: (1, 2, 'foo'))
68+
- prefixes: ! - ~
69+
- ternary conditional: ? :
70+
- null coalescence: ??
71+
72+
For more details see: https://github.com/Knetic/govaluate/blob/master/MANUAL.md
73+
74+
Example of filter for the parsing pattern log above:
75+
level == "DEBUG" - display only debug messages
76+
code > 400 - display logs with code higher then 400
77+
78+
Keyboard shortcuts
79+
------------------
80+
Following keys are supported:
81+
- "%<filter>s" for setting filter
82+
- "%<toggleFilter>s" for toggling filter
83+
- "%<pattern>s" for setting parsing pattern input
84+
- "%<follow>s" for scroll to bottom and follow new data
85+
- "%<help>s" for displaying help
86+
87+
Navigation:
88+
- "j", "k" or arrow keys for scrolling by one line
89+
- "g", "G" to move to top / bottom
90+
- "Ctrl-F", "page down" to move down by one page
91+
- "Ctrl-B", "page up" to move up by one page
92+
- "Ctrl-C" to exit loggy
93+
`, ui.KEY_MAP)
94+
2795
var cfgFile string
2896

2997
// TODO: Add option to turn off Regex escaping
@@ -35,7 +103,7 @@ var cfgFile string
35103
var cmd = &cobra.Command{
36104
Use: "loggy [path to log file]",
37105
Short: "Swiss knife for logs",
38-
Long: `By default reads from STDIN or you can specify file path to read logs from`,
106+
Long: LONG_DESCRIPTION,
39107
Args: cobra.MaximumNArgs(1),
40108
Version: ui.Version,
41109
Run: func(cmd *cobra.Command, args []string) {
@@ -95,33 +163,28 @@ func init() {
95163

96164
// initConfig reads in config file and ENV variables if set.
97165
func initConfig() {
98-
if cfgFile != "" {
99-
// Use config file from the flag.
100-
viper.SetConfigFile(cfgFile)
101-
} else {
102-
// Find home directory.
103-
home, err := os.UserHomeDir()
104-
cobra.CheckErr(err)
166+
viper.SetConfigType("toml")
167+
viper.SetConfigName(".loggy")
105168

106-
// Get current directory.
107-
currentDirectory, err := os.Getwd()
108-
cobra.CheckErr(err)
169+
// Home directory config
170+
home, err := os.UserHomeDir()
171+
cobra.CheckErr(err)
172+
viper.AddConfigPath(home)
173+
_ = viper.ReadInConfig() // if no config is found we don't care
109174

110-
// Search config in home directory and CWD with name ".loggy.toml"
111-
viper.AddConfigPath(home)
112-
viper.AddConfigPath(currentDirectory)
113-
viper.SetConfigType("toml")
114-
viper.SetConfigName(".loggy")
175+
// Get current directory config
176+
viper.AddConfigPath(".")
177+
cobra.CheckErr(viper.MergeInConfig())
178+
179+
// Config file from the flag.
180+
if cfgFile != "" {
181+
viper.SetConfigFile(cfgFile)
182+
cobra.CheckErr(viper.MergeInConfig())
115183
}
116184

117185
viper.SetEnvPrefix("loggy")
118186
viper.AutomaticEnv() // read in environment variables that match
119187

120-
// If a config file is found, read it in.
121-
if err := viper.ReadInConfig(); err == nil {
122-
fmt.Fprintln(os.Stderr, "Using config file:", viper.ConfigFileUsed())
123-
}
124-
125188
cobra.CheckErr(viper.BindPFlags(cmd.Flags()))
126189
}
127190

0 commit comments

Comments
 (0)