search

papertrail / papertrail-cli

Command-line client for Papertrail hosted syslog & app log management service
http://papertrailapp.com/
MIT License
426 stars 46 forks source link

Update readme #33

Closed lmarburger closed 5 years ago

lmarburger commented 10 years ago

Basically, a complete rewrite of the README. @troy, @eric, and @leonsodhi, mind giving it a quick scan for technical accuracy?

troy commented 10 years ago

So I know what I'm looking for (beyond technical accuracy), what's the goal or goals?

lmarburger commented 10 years ago

Clarity. It's basically the exact same content just trimmed and reorganized.

leonsodhi commented 10 years ago

Looks good to me. 2 things that might be worth adding in:

troy commented 10 years ago

Looks great. Only suggestion is to mention or link to the system/group management tools in the intro, even if it's 4 words. They get used a lot and the CLI itself is already hard to find.

Agree with Leon's comment about the --help output for the reason he mentioned. Some users don't have Ruby and thus have more setup effort than we're all used to. I could also see other ways to provide the full help output, like in separate text file or linking to the source (if it's readable).

lmarburger commented 10 years ago

Thanks for the feedback. Added --help output and linked to the other tools upfront.

@leonsodhi are min/max times handled differently than times entered to the web UI?

lmarburger commented 10 years ago

Is there a reason for the More: https://papertrailapp.com/ footer? Is that to link people to the website if they're trying to do something the CLI can't?

lmarburger commented 10 years ago

e290350 reformats the help output to look a little more like vim --help and git --help.

$ papertrail --help
papertrail - command-line tail and search for Papertrail log management service

Usage: papertrail [-f] [-s system] [-g group] [-d seconds] [-c papertrail.yml]
                  [-j] [--min-time mintime] [--max-time maxtime] [query]

Arguments:
    -h, --help                       Show usage
    -f, --follow                     Continue running and print new events (off)
    -d, --delay SECONDS              Delay between refresh (2)
    -c, --configfile PATH            Path to config (~/.papertrail.yml)
    -s, --system SYSTEM              System to search
    -g, --group GROUP                Group to search
    -j, --json                       Output raw json data
        --min-time MIN               Earliest time to search from.
        --max-time MAX               Latest time to search from.

Examples:
    papertrail -f
    papertrail something
    papertrail 1.2.3 Failure
    papertrail -s ns1 "connection refused"
    papertrail -f "(www OR db) (nginx OR pgsql) -accepted"
    papertrail -f -g Production "(nginx OR pgsql) -accepted"
    papertrail -g Production --min-time 'yesterday at noon' --max-time 'today at 4am'

More: https://papertrailapp.com

$ vim --help
VIM - Vi IMproved 7.4 (2013 Aug 10, compiled Nov 25 2013 16:53:04)

usage: vim [arguments] [file ..]       edit specified file(s)
   or: vim [arguments] -               read text from stdin
   or: vim [arguments] -t tag          edit file where tag is defined
   or: vim [arguments] -q [errorfile]  edit file with first error

Arguments:
   --                   Only file names after this
   -g                   Run using GUI (like "gvim")
   -f  or  --nofork     Foreground: Don't fork when starting GUI
   -v                   Vi mode (like "vi")
   -e                   Ex mode (like "ex")
   -E                   Improved Ex mode
   -s                   Silent (batch) mode (only for "ex")
   -d                   Diff mode (like "vimdiff")
...

$ git --help
usage: git [--version] [--help] [-c name=value]
           [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path]
           [-p|--paginate|--no-pager] [--no-replace-objects] [--bare]
           [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>]
           <command> [<args>]

The most commonly used git commands are:
   add        Add file contents to the index
   bisect     Find by binary search the change that introduced a bug
   branch     List, create, or delete branches
...

'git help -a' and 'git help -g' lists available subcommands and some
concept guides. See 'git help <command>' or 'git help <concept>'
to read about a specific subcommand or concept.
leonsodhi commented 10 years ago

Woops, ignore my previous comments on --min-time & --max-time. They use the local TZ.

troy commented 10 years ago

I'm in favor for saying the zone anyway, even if it's just:

--min-time MIN                   Earliest time to search from (in <description> zone)

.. or somewhere else in the docs.

leonsodhi commented 10 years ago

Asked @eric and we think that "local TZ" = TZ of the local system based on what is set in the TZ environment variable

troy commented 10 years ago

@lmarburger 2 more, 1 of which I missed in the last release: