Metadata-Version: 2.0
Name: bonfire
Version: 1.0.0rc1
Summary: CLI for querying graylog logging server
Home-page: https://github.com/blue-yonder/bonfire
Author: Malte Harder
Author-email: malte.harder@blue-yonder.com
License: new BSD
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Topic :: Utilities
Classifier: Programming Language :: Python
Requires-Dist: click (>=3.3)
Requires-Dist: keyring (>=9)
Requires-Dist: parsedatetime (<3,>=1.4)
Requires-Dist: python-dateutil (<3,>=2.4.1)
Requires-Dist: requests (<3.0,>=2.4.3)
Requires-Dist: arrow (>=0.13.0)
Requires-Dist: termcolor (==1.1.0)
Requires-Dist: six (>=1.9.0)

=======
bonfire
=======

Bonfire is a command line interface to query Graylog searches via the REST API. It tries to emulate the feeling of using tail on a local file.

Usage
=====

Examples::

    > bonfire -h logserver -u jdoe -@ "10 minutes ago" "*"
    ...

    > bonfire -h logserver -u jdoe -f "source:localhost AND level:2"
    ...

Bonfire usage::

    Usage: bonfire [OPTIONS] [QUERY]

      Bonfire - An interactive graylog cli client

    Options:
      --node TEXT                     Label of a preconfigured graylog node
      -h, --host TEXT                 Your graylog node's host
      -s, --tls                       Use HTTPS
      --port INTEGER                  Your graylog port (default: 12900)
      --endpoint TEXT                 Your graylog API endpoint e.g /api (default:
                                      /)
      -u, --username TEXT             Your graylog username
      -p, --password TEXT             Your graylog password (default: prompt)
      -k, --keyring / -nk, --no-keyring
                                      Use keyring to store/retrieve password
      -@, --search-from TEXT          Query range from
      -#, --search-to TEXT            Query range to (default: now)
      -t, --tail                      Show the last n lines for the query
                                      (default)
      -d, --dump                      Print the query result as a csv
      -f, --follow                    Poll the logging server for new logs
                                      matching the query (sets search from to now,
                                      limit to None)
      -l, --interval INTEGER          Polling interval in ms (default: 1000)
      -n, --limit INTEGER             Limit the number of results (default: 10)
      -a, --latency INTEGER           Latency of polling queries (default: 2)
      -r, --stream TEXT               Stream ID of the stream to query (default:
                                      no stream filter)
      -e, --field TEXT                Fields to include in the query result
      -x, --template-option TEXT      Template options for the stored query
      -s, --sort TEXT                 Field used for sorting (default: timestamp)
      --asc / --desc                  Sort ascending / descending
      --help                          Show this message and exit.

Configuration
=============

Bonfire can be configured. It will look for a ``~/.bonfire.cfg`` or a ``bonfire.cfg`` (in the current directory). The
configuration file can specify API nodes. If no host is specified a node with the name ``default`` will be used. You can
also configure queries which can be referenced by starting your query with a colon::

    [node:default]
    host=1.2.3.4
    port=12900
    endpoint=/
    username=jdoe

    [node:dev]
    host=4.3.2.1
    port=9000
    endpoint=/api
    username=jdoe
    password=H4rrH4rrB0bba

    [query:example]
    query=facility:*foo* AND source:*bar*
    from=2015-03-01 15:00:00
    limit=100
    fields=message,name,facility,source

Now you can run queries via such as::

    > bonfire --node=dev :example
    ... runs the example query on the node dev

    > bonfire :example
    ... runs the example query on the default node

Query Templates
---------------

Options
=======

Queries
=======

Testing
=======

Cf. the travis script for running tests. Make sure you disable proxies / set
noproxy if you're using a proxy, to be able to reach the test dummy server
(called ``dummyserver``), e.g.::

> env no_proxy=dummyhost python setup.py test

Known Bugs
==========

* bonfire expects graylog's timezone to be UTC.

Development
===========
Once you want to release a new version, do the following:

* bring your git tree in order, cut the release, and tag it with the desired
  version
* install necessary pip packages:
  > python3 -m pip install –-user –-upgrade setuptools wheel twine
* bundle your release:
  > python3 setup.py sdist bdist_wheel
* publish it:
  > python3 -m twine upload dist/*

Note that if you have several different versions in dist, you might want to
specify which one you want to publish.

Release Notes
=============

* v0.0.7: Issues fixes, TLS and Proxy support
    * Adds support for proxies
    * Adds support for https urls
    * Add timestamps to the dump format
* v0.0.6: Documentation fix
    * Change of README.rst
* v0.0.5: Clean up
    * Removed terminal UI ideas
    * Added first tests
    * Fixed date and time handling with timezones
    * Added python3 compatibility
* v0.0.4: Extended documentation & stream access
    * Use the first stream the user has access to if no stream is specified and the user has no global search rights
* v0.0.3: Small fixes
    * Use accept header in GET requests.
    * Fix bug when querying specific fields
* v0.0.1: Initial release
    * Limited feature set.


