cgrp util release 1.0.1, initial commit

.gitignore

@@ -0,0 +1,6 @@
+build/*
+cgrputil.egg-info/*
+venv/*
+dist/*
+build.txt
+test.py

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Rushikesh Butley
+
+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.

README.md

@@ -0,0 +1,70 @@
+# cgrputil
+[![image](https://img.shields.io/pypi/v/py-package-template.svg)](https://pypi.org/project/cgrputil/)
+[![Downloads](https://pepy.tech/badge/cgrputil)](https://pepy.tech/project/cgrputil)
+
+**cgrputil** is python library to calculate cpu utilisation of code over specific time interval inside docker container. 
+
+Usage of the library can vary, Eg. Think about the use case where you want to know how much specific function consume a cpu over specific time and on the basis of that you want to bill the client or draw charts to understand the growing trend of function.
+
+I was struggling with the same problem, & searched all over internet. But i didnt get anything solid,
+& all of the docs, the repos i viewed, code i read, almost pointed to docker repo which had calculation formula.
+So seeing the problem & number of resources available for such typical problem i decided to create the library.
+I wanted solution which is very easy to use and focus on giving end result, so i tried it making as simple as i could.
+I hope this helps :) .
+
+## Installation
+
+Use the package manager [pip](https://pip.pypa.io/en/stable/) to install cgrputil.
+
+```bash
+pip install cgrputil
+```
+
+## Usage
+
+```python
+import cgrputil
+
+'''
+Class instantiation expects default param, which will be return in case of any failure 
+while reading, calculating cpu usage. We suggest to send this value as maxm number of 
+cores allocated to container.
+This value can be pass in two ways either passing it while class instantiation, which is in 
+example below i.e 3 or setting it inside env variable `RES_CPU_LIMIT`. 
+Library will fist check for the value pass and then for the env variable, on of them is mandatory
+else exception will be raised.
+'''
+cpu = cgrputil.cpuutilisation(3)
+
+
+#From this point, it will calculate the cpu utilisation
+cpu.start_time()
+
+activity_you_want_to_calculate_cpu_usage()
+
+#Until this point cpu usage will be calculated 
+cpu.end_time()
+
+'''
+This will return the aprox cpu cores used while executing in between start time and end time.
+Return format is float. So if it returns 2.3 that means above function have consumed 2.3 cores
+out of all the cores available on the host or you can say 2.3 cores out of 3 
+cores (3 assuming maximum cores allocated to container).
+
+Function returns two values, first is list of errs or exception occured while calculating cpu usage.
+Second the actual usage value. If the errs list is not empty it will most likely to return the 
+default value passed while initiating the class. Ex. cpu = cgrputil.cpuutilisation(3) which is 3 here.
+'''
+errs, cores_used = cpu.get_core_utilisation()
+if errs is not None:
+    for err in errs:
+        print(err)
+    print('Utilisation : ', cores_used)        
+else:
+    print('Utilisation : ', cores_used)  
+```
+
+## Contributing
+Pull requests are welcome. For any changes, please open an issue first to discuss what you would like to change.
+
+Please make sure to update tests as appropriate.

cgrputil/__init__.py

@@ -0,0 +1,6 @@
+'''
+Cgrputil is the library for people, who wants to calculate the cpu utilisation
+of container for period of time without taking heachache ;).
+More in README.md on how to use it effectively.
+'''
+from .cgrputil import *

cgrputil/cgrputil.py

@@ -0,0 +1,144 @@
+import os
+import traceback
+import time
+
+CGRP_CPU_LIMIT = 'RES_CPU_LIMIT'
+
+class cpuutilisation:
+    def __init__(self, cpu_limit=None):
+        '''
+        Initate the object for calculating cpu utilisation.
+        If it fails to calculate, in any case it will return value pass
+        while initiating the class or it will try to get value from env variable
+        RES_CPU_LIMIT. One of them is mandatory.
+        '''    
+        self.cgrp_init_cycles, self.cgrp_end_cycles = 0, 0
+        self.sys_init_cycles, self.sys_end_cycles = 0, 0
+        self.no_of_host_cores = 0
+        self.errors = []
+        if cpu_limit is not None:
+            self.cgrp_cpu_limit = cpu_limit
+        else:
+            try:
+                self.cgrp_cpu_limit = os.environ[CGRP_CPU_LIMIT]
+            except Exception as e:
+                raise Exception('No cpu limit specified while initiating class or set in env variable {}'.format(e))
+    def get_no_of_cores_host(self):
+        '''
+        Get total number of cores on host machine
+        '''
+        cpu_info = '/proc/cpuinfo'
+        try:
+            with open(cpu_info, 'r') as cpus:
+                lscpu = cpus.readlines()
+                cores = 0
+                for cpu in lscpu:
+                    if 'processor' in cpu: #count as  core if processor exists in line
+                        cores += 1
+                return int(cores)    
+        except Exception as e:
+            err = 'Unable to read number of Cores from System :- {}'.format(e)
+            self.errors.append(err)
+            # print(err)
+            # traceback.print_exc()
+    def get_cpu_usage_cgrp(self):
+        '''
+        Read the cpu cycles of cgroup, 
+        '''
+        file = '/sys/fs/cgroup/cpu,cpuacct/cpuacct.usage_percpu'
+        try:
+            with open(file, 'r') as usage_percpu:
+                all_cores = usage_percpu.readlines()[0].split()
+                total_cgrpcpu_cycles = 0
+                for core in all_cores: total_cgrpcpu_cycles += int(core)            
+                return total_cgrpcpu_cycles           
+        except Exception as e:
+            err = 'Exception occured while get per cpu cgrp usage :- {}'.format(e)
+            self.errors.append(err)
+            #print(err)
+            # traceback.print_exc()
+
+    def get_cpu_usage_host(self):
+        '''
+        Read the cpu cycles from of host.
+        '''
+        try:
+            sys_stat = '/proc/stat'
+            with open(sys_stat, 'r') as sys:
+                stat = sys.readlines()[0].split() #system wide cpu usage all cores
+                system_stat = 0
+                for x in stat[1:]:
+                    system_stat += int(x)
+                return int(system_stat)
+        except Exception as e:
+            err = 'Exception occured duing getting system usage cycle :- {}'.format(e)
+            self.errors.append(err)
+            # print(err)
+            # traceback.print_exc()
+    def get_core_utilisation(self):
+        '''
+            > If it fails to calculate the usage, it return the default value defined in
+              passed while initiating the class, core_utilisation else value from env variable 'RES_CPU_LIMIT'.
+        Calculates the delta of cpu usage between start time & end time.
+        returns the Float value. If total cores in system are 10 and it returns
+        2.3 that means, function have used 2.3 cores on an average, which translates
+        to around 2300m in terms, if one checks in docker stats. 
+        '''
+        try:
+            self.no_of_host_cores = self.get_no_of_cores_host()
+            cores_used = float((self.cgrp_end_cycles - self.cgrp_init_cycles)/(self.sys_end_cycles - self.sys_init_cycles) * self.no_of_host_cores * 100)/1000000000
+            return None, float('{:.2f}'.format(cores_used))
+        except Exception as e:
+            err = 'Issue occured in cpu utilisation calculation, due to previous errors returning default maximum value set:- {}'.format(self.cgrp_cpu_limit)
+            self.errors.append(err)
+            # print(err)
+            # print('Core utilisation Calculation error, values passed :- {}'.format(vars(cpuutilisation(self.cgrp_cpu_limit))))
+            # traceback.print_exc()
+            return self.errors, float(self.cgrp_cpu_limit)
+
+    def start_time(self):
+        '''
+        Get the start of cgroup cycles and system cycles at point, when this function is called.
+        Example Usage:
+        Initate the core class, with default limit if it fails to calculate. Ex. 3
+        core = cpuutilisation(3)
+        Call this function before the start of function, you want to calculate cpu usage for
+        core.start_time()
+        actual_function_call_here_for_which_cpu_util_need_to_be_calculated()
+        '''           
+        self.cgrp_init_cycles = self.get_cpu_usage_cgrp()
+        self.sys_init_cycles = self.get_cpu_usage_host() 
+
+    def end_time(self):
+        '''
+        Get the end of cgroup cycles and system cycles at point, when this function is called.
+        Example Usage:
+        Call this at the end of 
+        actual_function_call_here_for_which_cpu_util_need_to_be_calculated()
+        core.end_time()
+        Initate the core class, with default limit if it fails to calculate. Ex. 3
+        core = cpuutilisation(3)
+        Call this function before the start of function, you want to calculate cpu usage for
+        core.start_time()
+        actual_function_call_here_for_which_cpu_util_need_to_be_calculated()
+        core.end_time()
+        '''  
+
+        self.cgrp_end_cycles = self.get_cpu_usage_cgrp()
+        self.sys_end_cycles = self.get_cpu_usage_host() 
+
+def main():
+    core = cpuutilisation(3)
+    core.start_time()
+    time.sleep(3)
+    #execute function here 
+    core.end_time()
+    errs, cores = core.get_core_utilisation()
+    if errs is not None:
+        for err in errs:
+            print(err)
+        print('\n Utilisation : ', cores)        
+    else:
+        print('Utilisation : ', cores)        
+if __name__ == "__main__":
+    main()

setup.py

@@ -0,0 +1,33 @@
+import setuptools
+
+with open("README.md", "r") as fh:
+    long_description = fh.read()
+
+setuptools.setup(
+    name="cgrputil", 
+    version="1.0.1",
+    author="Rushikesh Butley",
+    author_email="rushikeshbutley@gmail.com",
+    description="Package to calculate cpu utilisation in cgroups",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    url="https://github.com/rushi47/cgrputil",
+    packages=setuptools.find_packages(),
+    license="MIT",
+    classifiers=[
+        "Environment :: Console",
+        "Environment :: Other Environment",
+        "Environment :: Plugins",
+        "Intended Audience :: Developers",
+        "Intended Audience :: System Administrators",
+        "Operating System :: POSIX :: Linux",
+        "Operating System :: Unix",
+        "Programming Language :: Python :: 2.7",
+        "Programming Language :: Python :: 3",
+        "Topic :: System", 
+    ],
+    python_requires='>=2.7',
+    data_files=[('LICENSE', ['LICENSE']),
+                ('README', ['README.md']),
+                ]
+)