kwent/pypertrail

Python wrapper library and CLI for papertrail API

pypertrail

Python wrapper library and CLI for papertrail API.

Installation

Install using pip:

$ pip install pypertrail

Requirements

• Python 2.6, 2.7, 3.3, 3.4, or 3.5
• A Papertrail account

Library

Accounts

import os
from pypertrail.accounts import Account

accounts = Account(os.environ['PAPERTRAIL_API_TOKEN'])

# List account usage
accounts.list()

Archives

import os
from pypertrail.archives import Archive

archives = Archive(os.environ['PAPERTRAIL_API_TOKEN'])

# List archive information
archives.list()

Groups

import os
from pypertrail.groups import Group

groups = Group(os.environ['PAPERTRAIL_API_TOKEN'])

# List groups
groups.list()

# Show a group
groups.show(group_id)

# Update a group
groups.update(group_id)

# Delete a group
groups.delete(group_id)

Saved searches

import os
from pypertrail.saved_searches import SavedSearch

saved_searches = SavedSearch(os.environ['PAPERTRAIL_API_TOKEN'])

# List saved_searches
saved_searches.list()

# Show a saved search
saved_searches.show(saved_search_id)

# Create a saved search
payload = {'name':'my_query', 'query':'sshd'}
saved_searches.create(payload)

# Update a saved search
payload = {'search[query]':'another_query'}
saved_searches.update(payload)

# Delete a saved search
saved_searches.delete(saved_search_id)

Search

import os
from pypertrail.search import Search

search = Search(os.environ['PAPERTRAIL_API_TOKEN'])

# Search events
search.events("sshd")

Systems

import os
from pypertrail.systems import System

systems = Search(os.environ['PAPERTRAIL_API_TOKEN'])

# List systems
systems.list()

# Show a system
systems.show(system_id)

# Create a system
payload = {'system[name]':'foo', 'system[hostname]':'bar', 'destination_port':46865}
systems.create(payload)

# Update a system
payload = {'system[name]':'another_name'}
systems.update(system_id, payload)

# Delete a system
systems.delete(system_id)

# Join a group
payload = {'group_id':10}
systems.join_group(system_id, payload)

# Leave a group
payload = {'group_id':10}
systems.leave_group(system_id, payload)

Users

import os
from pypertrail.users import User

users = User(os.environ['PAPERTRAIL_API_TOKEN'])

# List users
users.list()

# Invite a user
payload = {'email':'contact@quent.in', 'read_only':'true'}
users.invite(payload)

# Delete a user
users.delete(user_id)

CLI

CLI Authentication

Via environment variables:

$ export PAPERTRAIL_API_TOKEN=my_token
$ pypertrail users list

Via implicit ~/.pypertrail.yml:

$ echo "token: my_token" > ~/.pypertrail.yml
$ pypertrail users list

Via (--conf/-c) option:

$ echo "token: my_token" > /path/to/config
$ pypertrail --conf /path/to/config users list

Via (--token/-t) option:

$ pypertrail --token my_token users list

Subcommands

Usage: pypertrail.py [OPTIONS] COMMAND [ARGS]...

Options:
  -d, --debug       Debug mode.
  -p, --pretty      Prettify JSON output.
  -t, --token TEXT  Papertrail API token.
  -c, --conf TEXT   Path to config (~/.pypertrail.yml).
  --version         Show the version and exit.
  -h, --help        Show this message and exit.

Commands:
  accounts
  archives
  groups
  saved_searches
  search
  systems
  users

Accounts

Usage: papertrail.py accounts [OPTIONS] COMMAND [ARGS]...

Options:
  -h, --help  Show this message and exit.

Commands:
  list  List account usage

Examples:

$ pypertrail --pretty accounts list

Archives

Usage: papertrail.py archives [OPTIONS] COMMAND [ARGS]...

Options:
  -h, --help  Show this message and exit.

Commands:
  list  List archive information

Examples:

$ pypertrail --pretty archives list

Saved searches

Usage: cli.py saved_searches [OPTIONS] COMMAND [ARGS]...

Options:
  -h, --help  Show this message and exit.

Commands:
  create  Create a saved search
  delete  Delete a saved search
  list    List saved_searches
  show    Show a saved search
  update  Update a saved search

Examples:

$ pypertrail saved_searches create --payload '{"search[name]":"foo", "search[query]":"bar"}'
$ pypertrail saved_searches delete 1
$ pypertrail saved_searches list
$ pypertrail saved_searches show 1
$ pypertrail saved_searches update 1 --payload '{"search[query]":"another_query"}'

Groups

Usage: papertrail.py groups [OPTIONS] COMMAND [ARGS]...

Options:
-h, --help  Show this message and exit.

Commands:
delete  Delete a group
list    List groups
show    Show a group
update  Update a group

Examples:

$ pypertrail groups delete 1
$ pypertrail groups list
$ pypertrail groups show 1
$ pypertrail groups update 1 --payload '{"group[name]":"another_name"}'

Search

Usage: papertrail.py search events [OPTIONS]

  Search events

Options:
  -q, --query TEXT                Terms to query.
  -s, --system INTEGER            System to search.
  -g, --group INTEGER             Group to search.
  -e, --min-time INTEGER          Earliest time to search from.
  -l, --max-time INTEGER          Latest time to search from.
  -f, --follow                    Continue running and printing new events
                                  (off).
  -d, --delay INTEGER             Delay between refresh (5).
  -j, --json                      Output raw JSON data (off).
  -c, --color [program|system|all|off]
                                  Attribute(s) to colorize based on (program).
  -h, --help                      Show this message and exit.

Examples:

$ pypertrail search events
$ pypertrail search events --follow
$ pypertrail search events --follow --color program
$ pypertrail search events --follow --query sshd
$ pypertrail search events --follow --json

Systems

Usage: papertrail.py systems [OPTIONS] COMMAND [ARGS]...

Options:
  -h, --help  Show this message and exit.

Commands:
  create       Create a saved search
  delete       Delete a system
  join_group   Join a group
  leave_group  Leave a group
  list         List systems
  show         Show a system
  update       Update a system

Examples:

$ pypertrail systems create --payload '{"system[name]":"foo", "system[hostname]":"bar", "destination_port":46865}'
$ pypertrail systems delete 1
$ pypertrail systems join_group 1 --payload '{"group_id":10}'
$ pypertrail systems leave_group 1 --payload '{"group_id":10}'
$ pypertrail systems list
$ pypertrail systems show 1
$ pypertrail systems update 1 --payload '{"system[name]":"another_name"}'

Users

Usage: papertrail.py users [OPTIONS] COMMAND [ARGS]...

Options:
  -h, --help  Show this message and exit.

Commands:
  delete  Delete a user
  invite  Invite a user
  list    List users

Examples:

$ pypertrail users delete 1
$ pypertrail users invite --payload '{"email":"contact@quent.in", "read_only":true}'
$ pypertrail users list

Documentation

• https://pypertrail.readthedocs.io
• http://help.papertrailapp.com/kb/how-it-works/http-api

History

View the changelog

Authors

• Quentin Rousseau

License

Copyright (c) 2016 Quentin Rousseau <contact@quent.in>

Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use,
copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following
conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.