[libvirt] [PATCH] Add docs about cgroups layout and usage

[Eric Blake]

On 05/03/2013 10:49 AM, Daniel P. Berrange wrote:
> From: "Daniel P. Berrange" <berrange at redhat.com>
> 
> Describe the new cgroups layout, how to customize placement
> of guests and what virsh commands are used to access the
> parameters.
> 
> Signed-off-by: Daniel P. Berrange <berrange at redhat.com>
> ---
>  docs/cgroups.html.in | 285 +++++++++++++++++++++++++++++++++++++++++++++++++++
>  docs/sitemap.html.in |   4 +
>  2 files changed, 289 insertions(+)
>  create mode 100644 docs/cgroups.html.in

> +
> +    <p>
> +      The QEMU and LXC drivers make use of the Linux "Control Groups" facility
> +      for applying resource management to their virtual machines & containers.

s/&/and/ - '&' looks too informal.

> +
> +    <p>
> +      The default cgroups layout ensures that, when there is contention for
> +      CPU time, it is shared equally between system services, user sessions
> +      and virtual machines / containers. This prevents virtual machines from
> +      locking the administrator out of the host, or impacting execution of
> +      system services. ConverselyWhen there is no contention from

s/ConverselyWhen/Conversely, when/

> +    <p>
> +      Since libvirt aims to provide an API which is portable across
> +      hypervisors, the concept of cgroups is not exposed directly
> +      in the API or XML configuration. It is considered to be an
> +      internal implementation detail. Instead libvirt provides a
> +      set of APIs for applying resource controls, which are then
> +      mapped to corresponding cgroup tunables

Yay - I already know that I will be pointing people to this page on IRC.

> +    </p>
> +
> +    <h3>Scheduler tuning</h3>
> +
> +    <p>
> +     Parameters from the "cpu" controller are exposed via the
> +     <code>schedinfo</code> command in virsh.

I think it is also worth mentioning which portions of the XML hold the
information (a link to right section of formatdomain.html) and which
APIs are being used, rather than just saying virsh exposes it.  But that
can be a followup patch - getting this out there now and improving it
later is acceptable, since anything is better than the current lack of docs.

> +
> +    <p>
> +      Prior to libvirt 1.0.5, the cgroups layout created by libvirt was different
> +      from that described above, and did not allow for administrator customization.
> +      Libvirt used a fixed, 3-level hiearchy <code>libvirt/{qemu,lxc}/$VMNAME</code>

s/hiearchy/hierarchy/

> +      which was rooted at the point in the hiearchy where libvirtd itself was

and again

> +      located. So if libvirtd was placed at <code>/system/libvirtd.service</code>
> +      by systemd, the groups for each virtual machine / container would be located
> +      at <code>/system/libvirtd.service/libvirt/{qemu,lxc}/$VMNAME</code>. In addition
> +      to this, the QEMU drivers further child groups for each vCPU thread and the
> +      emulator thread(s). This leads to a hiearchy that looked like

and again

> +    <p>
> +      Although current releases are much improved, historically the use of deep
> +      hiearchies has had a significant negative impact on the kernel scalability.

and again.

ACK with typos fixed.

-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 621 bytes
Desc: OpenPGP digital signature
URL: <http://listman.redhat.com/archives/libvir-list/attachments/20130503/c5d4e23e/attachment-0001.sig>