Supermann. Release 3.0.0

Transcription

1 Supermann Release May 27, 2015

2

3 Contents 1 Usage What Supermann does supermann-from-file Installation Requirements Changelog Version Licence 9 5 Authors supermann package supermann.metrics package Python Module Index 17 i

4 ii

5 Supermann monitors processes running under Supervisor and sends metrics to Riemann. Source on GitHub Documentation on Read the Docs Packages on PyPI Contents 1

6 2 Contents

7 CHAPTER 1 Usage Supermann runs as a Supervisor event listener, and will send metrics every time an event is received. The only configuration Supermann needs is the host and port for a Riemann instance, which can be provided as arguments or by the RIEMANN_HOST and RIEMANN_PORT environment variables. Basic usage is as follows, though Supermann will not start if not run under Supervisor: supermann [--log-level=level] HOST PORT A Supervisor configuration file for Supermann should look something like this: [eventlistener:supermann] command=supermann-from-file /etc/supermann.args events=process_state,tick_5 This loads Supermann s arguments from /etc/supermann.args, which would contain a host and port for a Riemann server - localhost:5555 is used as the default if no host or port are specified: riemann.example.com What Supermann does Supermann will collect and send information about the system and the processes running under Supervisor each time an event is received. Listening for the TICK_5 and PROCESS_STATE events will collect and send information every 5 seconds, and when a program changes state. See the Supervisor event documentation for more information. Supermann is designed to bail out when an error is encountered, allowing Supervisor to restart it - it is recommended that you do not set autorestart=false in the Supervisor configuration for the event listener. Logs are sent to STDERR for collection by Supervisor - the log level can be controlled with the --log-level argument. The logs can be read with supervisorctl tail supermann stderr or finding the log in Supervisor s log directory. 1.2 supermann-from-file An issue with modifying the configuration of a Supervisord event listener (link) means that the command used to start an event listener process can t be changed while Supervisord is running. Supermann 2 allowed files to be named directly as an argument that more arguments would be read from. Supermann 3 instead provides the supermann-from-file entry point, which loads a file containing arguments that will be passed to the main supermann command. 3

8 The easiest way to upgrade between versions is to rename the eventlistener:supermann section in the Supervisord configuration, and to then run supervisorctl update. This will remove the old supermann instance, and start a new instance with the new command. The supermann-from-file command reads a set of arguments from a file and starts Supermann with those arguments, so that Supermann s configuration can be changed without restarting Supervisord. 4 Chapter 1. Usage

9 CHAPTER 2 Installation Supermann can be installed with pip install supermann. It s recommended to install it in the same Python environment as Supervisor. Supervisor can also be installed with pip, or can be installed from your distributions package manager. Once Supermann is installed, add an eventlistener section to the Supervisor configuration (/etc/supervisord.conf by default) and restart Supervisor. 2.1 Requirements click blinker protobuf psutil riemann-client supervisor The psutil package uses C extensions, and installing the package from source or with a python package manager (such as pip) will require build tools. Alternatively, it can be installed from your distribution s repositories (python-psutil on Debian and CentOS). Superman currently uses a very old version of psutil so as to remain compatible with CentOS. Supermann is developed and tested on Python 2.6. There are no plans to release it for Python 3, as Google s protobuf library (and therefore riemann-client) are only compatible with Python 2. 5

10 6 Chapter 2. Installation

11 CHAPTER 3 Changelog 3.1 Version Upgraded to most recent version of psutil (2.1.1) Replaced or changed various metrics Replaced argparse with click and made improvements to CLI argument syntax with supermann-from-file Removed --memmon option and memory monitoring plugin Added documentation on Read the Docs Many other minor fixes and improvements 7

12 8 Chapter 3. Changelog

13 CHAPTER 4 Licence Supermann is licensed under the MIT Licence. The protocol buffer definition is sourced from the Riemann Java client, which is licensed under the Apache Licence. 9

14 10 Chapter 4. Licence

15 CHAPTER 5 Authors Supermann was written by Sam Clements, while working at DataSift. 5.1 supermann package supermann.cli Command line entry points to supermann using click supermann.cli.main The main entry point - see supermann --help for more information. supermann.cli.from_file An alternate entry point - see supermann-from-file --help for more information. Used as a workaround for an issue with Supervisor supermann.core The Supermann core class supermann.core.supermann(host=none, port=none) Bases: object Manages the components that make up a Supermann instance. Manages a the Supervisor and Riemann clients, and distributes events to the supermann.signals.event and supermann.signals.process signals. connect(signal, reciver) Connects a signal that will recive messages from this instance Parameters signal (blinker.signal) Listen for events from this signal reciver A function that will recive events connect_event(reciver) Conects a reciver to event using connect() connect_process(reciver) Conects a reciver to process using connect() 11

16 emit_processes(event) Emit a signal for each Supervisor child process A new cache is created from the processes emitted in this cycle, which drops processes that no longer exist from the cache. Parameters event An event received from Supervisor exception_handler(*exc_info) Used as a global exception handler to ensure errors are logged run() Runs forever, ensuring Riemann is disconnected properly Returns the Supermann instance the method was called on with_all_recivers() Adds all recivers to the Supermann instance Returns the Supermann instance the method was called on supermann.signals Blinker signals used for sending end receiving events supermann.supervisor Supervisor interface for Supermann class supermann.supervisor.event(headers, payload) Bases: object An event recived from Supervisor headers payload class supermann.supervisor.eventlistener(stdin=<open file <stdin>, mode r >, stdout=<open file <stdout>, mode w >, reserve_stdin=true, Bases: object reserve_stdout=true) A simple Supervisor event listener Listens for events from Supervisor and yields Event objects STDIN and STDOUT are referenced by the object, so that they are easy to test, and so the references in sys can be disabled. fail() ok() Parameters stdin (file) A file-like object that can be used as STDIN stdout (file) A file-like object that can be used as STDOUT reserve_stdin (bool) Set sys.stdin to None reserve_stdout (bool) Set sys.stdout to None 12 Chapter 5. Authors

17 static parse(line) Parses a Supervisor header or payload Parameters line (str) A line from a Supervisor message Returns A dictionary containing the header or payload ready() Writes and flushes the READY symbol to stdout result(result) Writes and flushes a result message to stdout Parameters result (str) OK or FAIL wait() Waits for an event from Supervisor, then reads and returns it Returns An Event containing the headers and payload class supermann.supervisor.supervisor Bases: object Contains the Supervisor event listener and XML-RPC interface rpc Returns the supervisor namespace of the XML-RPC interface run_forever() Yields events from Supervisor, managing the OK and READY signals Returns A stream of :py:class:.event s supermann.utils Utility functions used in other parts of Supermann supermann.utils.configure_logging(level=20, format=u %(asctime)s %(levelname)-8s [%(name)s] %(message)s, log=u ) This configures a logger to output to the console Parameters level (int or str) The log level to set format (str) The logging format to use log (str) The log to configure, defaulting to the root logger supermann.utils.fullname(obj) Returns the qualified name of an object s class Parameters obj An object to inspect Returns The name of the objects class supermann.utils.getlogger(obj) Returns a logger using the full name of the given object Parameters obj An object to inspect Returns A logger object using the fullname() of the object 5.1. supermann package 13

18 5.2 supermann.metrics package supermann.metrics.process Metrics reported for each process running under Supervisor supermann.metrics.process.cpu(sender, process, data) CPU utilisation as a percentage and total CPU time in seconds process:{name}:cpu:percent process:{name}:cpu:absolute supermann.metrics.process.fds(sender, process, data) Number of file descriptors a process is using it s hard limit process:{name}:fds:absolute process:{name}:fds:percent supermann.metrics.process.get_nofile_limit(pid) Returns the NOFILE limit for a given PID Parameters pid (int) The PID of the process Returns (int) The NOFILE limit supermann.metrics.process.io(sender, process, data) Bytes read and written by a process process:{name}:io:read:bytes process:{name}:io:write:bytes supermann.metrics.process.mem(sender, process, data) Total virtual memory, total RSS memory, RSS utilisation as percentage process:{name}:mem:virt:absolute process:{name}:mem:rss:absolute process:{name}:mem:rss:percent supermann.metrics.process.running_process(function) Decorates a signals.process reciver to only run if the process exists supermann.metrics.process.state(sender, process, data) The process state that Supervisor reports process:{name}:state supermann.metrics.process.uptime(sender, process, data) The time in seconds Supervisor reports the process has been running process:{name}:uptime supermann.metrics.system Metrics reported for the entire system supermann.metrics.system.cpu(self, event) CPU utilisation as a percentage system:cpu:percent 14 Chapter 5. Authors

19 supermann.metrics.system.load(self, event) Load averages system:load:1min system:load:5min system:load:15min supermann.metrics.system.load_scaled(self, event) Load averages system:load_scaled:1min supermann.metrics.system.mem(self, event) Memory utilisation - total, free, cached, buffers system:mem:percent system:mem:total system:mem:free system:mem:cached system:mem:buffers supermann.metrics.system.swap(self, event) Swap utilisation system:swap:percent system:swap:absolute supermann.metrics.system.uptime(self, event) System uptime (uses /proc/uptime) system:uptime 5.2. supermann.metrics package 15

20 16 Chapter 5. Authors

21 Python Module Index s supermann.cli, 11 supermann.core, 11 supermann.metrics.process, 14 supermann.metrics.system, 14 supermann.signals, 12 supermann.supervisor, 12 supermann.utils, 13 17

22 18 Python Module Index

23 Index C configure_logging() (in module supermann.utils), 13 connect() (supermann.core.supermann method), 11 connect_event() (supermann.core.supermann method), 11 connect_process() (supermann.core.supermann method), 11 cpu() (in module supermann.metrics.process), 14 cpu() (in module supermann.metrics.system), 14 E emit_processes() (supermann.core.supermann method), 11 Event (class in supermann.supervisor), 12 EventListener (class in supermann.supervisor), 12 exception_handler() (supermann.core.supermann method), 12 F fail() (supermann.supervisor.eventlistener method), 12 fds() (in module supermann.metrics.process), 14 from_file (in module supermann.cli), 11 fullname() (in module supermann.utils), 13 G get_nofile_limit() (in module supermann.metrics.process), 14 getlogger() (in module supermann.utils), 13 H headers (supermann.supervisor.event attribute), 12 I io() (in module supermann.metrics.process), 14 L load() (in module supermann.metrics.system), 15 load_scaled() (in module supermann.metrics.system), 15 M main (in module supermann.cli), 11 mem() (in module supermann.metrics.process), 14 mem() (in module supermann.metrics.system), 15 O ok() (supermann.supervisor.eventlistener method), 12 P parse() (supermann.supervisor.eventlistener static method), 12 payload (supermann.supervisor.event attribute), 12 R ready() (supermann.supervisor.eventlistener method), 13 result() (supermann.supervisor.eventlistener method), 13 rpc (supermann.supervisor.supervisor attribute), 13 run() (supermann.core.supermann method), 12 run_forever() (supermann.supervisor.supervisor method), 13 running_process() (in module supermann.metrics.process), 14 S state() (in module supermann.metrics.process), 14 Supermann (class in supermann.core), 11 supermann.cli (module), 11 supermann.core (module), 11 supermann.metrics.process (module), 14 supermann.metrics.system (module), 14 supermann.signals (module), 12 supermann.supervisor (module), 12 supermann.utils (module), 13 Supervisor (class in supermann.supervisor), 13 swap() (in module supermann.metrics.system), 15 U uptime() (in module supermann.metrics.process), 14 uptime() (in module supermann.metrics.system), 15 19

24 W wait() (supermann.supervisor.eventlistener method), 13 with_all_recivers() (supermann.core.supermann method), Index