diff options
| -rwxr-xr-x | tools/kvm/kvm_stat/kvm_stat | 161 |
1 files changed, 159 insertions, 2 deletions
diff --git a/tools/kvm/kvm_stat/kvm_stat b/tools/kvm/kvm_stat/kvm_stat index b4d50e8eb75a..581278c58488 100755 --- a/tools/kvm/kvm_stat/kvm_stat +++ b/tools/kvm/kvm_stat/kvm_stat @@ -10,6 +10,15 @@ # # This work is licensed under the terms of the GNU GPL, version 2. See # the COPYING file in the top-level directory. +"""The kvm_stat module outputs statistics about running KVM VMs + +Three different ways of output formatting are available: +- as a top-like text ui +- in a key -> value format +- in an all keys, all values format + +The data is sampled from the KVM's debugfs entries and its perf events. +""" import curses import sys @@ -217,8 +226,10 @@ IOCTL_NUMBERS = { } class Arch(object): - """Class that encapsulates global architecture specific data like - syscall and ioctl numbers. + """Encapsulates global architecture specific data. + + Contains the performance event open syscall and ioctl numbers, as + well as the VM exit reasons for the architecture it runs on. """ @staticmethod @@ -306,12 +317,22 @@ def parse_int_list(list_string): def get_online_cpus(): + """Returns a list of cpu id integers.""" with open('/sys/devices/system/cpu/online') as cpu_list: cpu_string = cpu_list.readline() return parse_int_list(cpu_string) def get_filters(): + """Returns a dict of trace events, their filter ids and + the values that can be filtered. + + Trace events can be filtered for special values by setting a + filter string via an ioctl. The string normally has the format + identifier==value. For each filter a new event will be created, to + be able to distinguish the events. + + """ filters = {} filters['kvm_userspace_exit'] = ('reason', USERSPACE_EXIT_REASONS) if ARCH.exit_reasons: @@ -322,6 +343,14 @@ libc = ctypes.CDLL('libc.so.6', use_errno=True) syscall = libc.syscall class perf_event_attr(ctypes.Structure): + """Struct that holds the necessary data to set up a trace event. + + For an extensive explanation see perf_event_open(2) and + include/uapi/linux/perf_event.h, struct perf_event_attr + + All fields that are not initialized in the constructor are 0. + + """ _fields_ = [('type', ctypes.c_uint32), ('size', ctypes.c_uint32), ('config', ctypes.c_uint64), @@ -342,6 +371,20 @@ class perf_event_attr(ctypes.Structure): self.read_format = PERF_FORMAT_GROUP def perf_event_open(attr, pid, cpu, group_fd, flags): + """Wrapper for the sys_perf_evt_open() syscall. + + Used to set up performance events, returns a file descriptor or -1 + on error. + + Attributes are: + - syscall number + - struct perf_event_attr * + - pid or -1 to monitor all pids + - cpu number or -1 to monitor all cpus + - The file descriptor of the group leader or -1 to create a group. + - flags + + """ return syscall(ARCH.sc_perf_evt_open, ctypes.pointer(attr), ctypes.c_int(pid), ctypes.c_int(cpu), ctypes.c_int(group_fd), ctypes.c_long(flags)) @@ -353,6 +396,8 @@ PATH_DEBUGFS_TRACING = '/sys/kernel/debug/tracing' PATH_DEBUGFS_KVM = '/sys/kernel/debug/kvm' class Group(object): + """Represents a perf event group.""" + def __init__(self): self.events = [] @@ -360,6 +405,22 @@ class Group(object): self.events.append(event) def read(self): + """Returns a dict with 'event name: value' for all events in the + group. + + Values are read by reading from the file descriptor of the + event that is the group leader. See perf_event_open(2) for + details. + + Read format for the used event configuration is: + struct read_format { + u64 nr; /* The number of events */ + struct { + u64 value; /* The value of the event */ + } values[nr]; + }; + + """ length = 8 * (1 + len(self.events)) read_format = 'xxxxxxxx' + 'Q' * len(self.events) return dict(zip([event.name for event in self.events], @@ -367,6 +428,7 @@ class Group(object): os.read(self.events[0].fd, length)))) class Event(object): + """Represents a performance event and manages its life cycle.""" def __init__(self, name, group, trace_cpu, trace_pid, trace_point, trace_filter, trace_set='kvm'): self.name = name @@ -375,10 +437,19 @@ class Event(object): trace_filter, trace_set) def __del__(self): + """Closes the event's file descriptor. + + As no python file object was created for the file descriptor, + python will not reference count the descriptor and will not + close it itself automatically, so we do it. + + """ if self.fd: os.close(self.fd) def setup_event_attribute(self, trace_set, trace_point): + """Returns an initialized ctype perf_event_attr struct.""" + id_path = os.path.join(PATH_DEBUGFS_TRACING, 'events', trace_set, trace_point, 'id') @@ -388,9 +459,19 @@ class Event(object): def setup_event(self, group, trace_cpu, trace_pid, trace_point, trace_filter, trace_set): + """Sets up the perf event in Linux. + + Issues the syscall to register the event in the kernel and + then sets the optional filter. + + """ + event_attr = self.setup_event_attribute(trace_set, trace_point) + # First event will be group leader. group_leader = -1 + + # All others have to pass the leader's descriptor instead. if group.events: group_leader = group.events[0].fd @@ -408,15 +489,33 @@ class Event(object): self.fd = fd def enable(self): + """Enables the trace event in the kernel. + + Enabling the group leader makes reading counters from it and the + events under it possible. + + """ fcntl.ioctl(self.fd, ARCH.ioctl_numbers['ENABLE'], 0) def disable(self): + """Disables the trace event in the kernel. + + Disabling the group leader makes reading all counters under it + impossible. + + """ fcntl.ioctl(self.fd, ARCH.ioctl_numbers['DISABLE'], 0) def reset(self): + """Resets the count of the trace event in the kernel.""" fcntl.ioctl(self.fd, ARCH.ioctl_numbers['RESET'], 0) class TracepointProvider(object): + """Data provider for the stats class. + + Manages the events/groups from which it acquires its data. + + """ def __init__(self): self.group_leaders = [] self.filters = get_filters() @@ -424,6 +523,20 @@ class TracepointProvider(object): self._pid = 0 def get_available_fields(self): + """Returns a list of available event's of format 'event name(filter + name)'. + + All available events have directories under + /sys/kernel/debug/tracing/events/ which export information + about the specific event. Therefore, listing the dirs gives us + a list of all available events. + + Some events like the vm exit reasons can be filtered for + specific values. To take account for that, the routine below + creates special fields with the following format: + event name(filter name) + + """ path = os.path.join(PATH_DEBUGFS_TRACING, 'events', 'kvm') fields = walkdir(path)[1] extra = [] @@ -436,6 +549,8 @@ class TracepointProvider(object): return fields def setup_traces(self): + """Creates all event and group objects needed to be able to retrieve + data.""" if self._pid > 0: # Fetch list of all threads of the monitored pid, as qemu # starts a thread for each vcpu. @@ -499,6 +614,7 @@ class TracepointProvider(object): @fields.setter def fields(self, fields): + """Enables/disables the (un)wanted events""" self._fields = fields for group in self.group_leaders: for index, event in enumerate(group.events): @@ -517,12 +633,16 @@ class TracepointProvider(object): @pid.setter def pid(self, pid): + """Changes the monitored pid by setting new traces.""" self._pid = pid + # The garbage collector will get rid of all Event/Group + # objects and open files after removing the references. self.group_leaders = [] self.setup_traces() self.fields = self._fields def read(self): + """Returns 'event name: current value' for all enabled events.""" ret = defaultdict(int) for group in self.group_leaders: for name, val in group.read().iteritems(): @@ -531,12 +651,19 @@ class TracepointProvider(object): return ret class DebugfsProvider(object): + """Provides data from the files that KVM creates in the kvm debugfs + folder.""" def __init__(self): self._fields = self.get_available_fields() self._pid = 0 self.do_read = True def get_available_fields(self): + """"Returns a list of available fields. + + The fields are all available KVM debugfs files + + """ return walkdir(PATH_DEBUGFS_KVM)[2] @property @@ -592,6 +719,12 @@ class DebugfsProvider(object): return 0 class Stats(object): + """Manages the data providers and the data they provide. + + It is used to set filters on the provider's data and collect all + provider data. + + """ def __init__(self, providers, pid, fields=None): self.providers = providers self._pid_filter = pid @@ -601,6 +734,7 @@ class Stats(object): self.update_provider_filters() def update_provider_filters(self): + """Propagates fields filters to providers.""" def wanted(key): if not self._fields_filter: return True @@ -615,6 +749,7 @@ class Stats(object): provider.fields = provider_fields def update_provider_pid(self): + """Propagates pid filters to providers.""" for provider in self.providers: provider.pid = self._pid_filter @@ -638,6 +773,8 @@ class Stats(object): self.update_provider_pid() def get(self): + """Returns a dict with field -> (value, delta to last value) of all + provider data.""" for provider in self.providers: new = provider.read() for key in provider.fields: @@ -653,6 +790,7 @@ LABEL_WIDTH = 40 NUMBER_WIDTH = 10 class Tui(object): + """Instruments curses to draw a nice text ui.""" def __init__(self, stats): self.stats = stats self.screen = None @@ -687,6 +825,7 @@ class Tui(object): curses.endwin() def update_drilldown(self): + """Sets or removes a filter that only allows fields without braces.""" if not self.stats.fields_filter: self.stats.fields_filter = r'^[^\(]*$' @@ -694,9 +833,11 @@ class Tui(object): self.stats.fields_filter = None def update_pid(self, pid): + """Propagates pid selection to stats object.""" self.stats.pid_filter = pid def refresh(self, sleeptime): + """Refreshes on-screen data.""" self.screen.erase() if self.stats.pid_filter > 0: self.screen.addstr(0, 0, 'kvm statistics - pid {0}' @@ -734,6 +875,11 @@ class Tui(object): self.screen.refresh() def show_filter_selection(self): + """Draws filter selection mask. + + Asks for a valid regex and sets the fields filter accordingly. + + """ while True: self.screen.erase() self.screen.addstr(0, 0, @@ -756,6 +902,11 @@ class Tui(object): continue def show_vm_selection(self): + """Draws PID selection mask. + + Asks for a pid until a valid pid or 0 has been entered. + + """ while True: self.screen.erase() self.screen.addstr(0, 0, @@ -787,6 +938,7 @@ class Tui(object): continue def show_stats(self): + """Refreshes the screen and processes user input.""" sleeptime = 0.25 while True: self.refresh(sleeptime) @@ -809,6 +961,7 @@ class Tui(object): continue def batch(stats): + """Prints statistics in a key, value format.""" s = stats.get() time.sleep(1) s = stats.get() @@ -817,6 +970,7 @@ def batch(stats): print '%-42s%10d%10d' % (key, values[0], values[1]) def log(stats): + """Prints statistics as reiterating key block, multiple value blocks.""" keys = sorted(stats.get().iterkeys()) def banner(): for k in keys: @@ -837,6 +991,7 @@ def log(stats): line += 1 def get_options(): + """Returns processed program arguments.""" description_text = """ This script displays various statistics about VMs running under KVM. The statistics are gathered from the KVM debugfs entries and / or the @@ -906,6 +1061,7 @@ Requirements: return options def get_providers(options): + """Returns a list of data providers depending on the passed options.""" providers = [] if options.tracepoints: @@ -918,6 +1074,7 @@ def get_providers(options): return providers def check_access(options): + """Exits if the current user can't access all needed directories.""" if not os.path.exists('/sys/kernel/debug'): sys.stderr.write('Please enable CONFIG_DEBUG_FS in your kernel.') sys.exit(1) |