mesos git commit: Added doc for cgroups/cpu isolator.

[ji...@apache.org]

Repository: mesos
Updated Branches:
  refs/heads/master 730585532 -> 8186f032d


Added doc for cgroups/cpu isolator.

Review: https://reviews.apache.org/r/62962/


Project: http://git-wip-us.apache.org/repos/asf/mesos/repo
Commit: http://git-wip-us.apache.org/repos/asf/mesos/commit/8186f032
Tree: http://git-wip-us.apache.org/repos/asf/mesos/tree/8186f032
Diff: http://git-wip-us.apache.org/repos/asf/mesos/diff/8186f032

Branch: refs/heads/master
Commit: 8186f032d43ff5d969eb0117921c67e6d32420cd
Parents: 7305855
Author: Ilya Pronin <ip...@twopensource.com>
Authored: Thu Oct 12 17:45:35 2017 -0700
Committer: Jie Yu <yu...@gmail.com>
Committed: Thu Oct 12 17:45:43 2017 -0700

----------------------------------------------------------------------
 docs/isolators/cgroups-cpu.md | 106 +++++++++++++++++++++++++++++++++++++
 docs/mesos-containerizer.md   |   2 +-
 2 files changed, 107 insertions(+), 1 deletion(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/mesos/blob/8186f032/docs/isolators/cgroups-cpu.md
----------------------------------------------------------------------
diff --git a/docs/isolators/cgroups-cpu.md b/docs/isolators/cgroups-cpu.md
new file mode 100644
index 0000000..ce29a89
--- /dev/null
+++ b/docs/isolators/cgroups-cpu.md
@@ -0,0 +1,106 @@
+---
+title: Apache Mesos - Cgroups 'cpu' Subsystem Support in Mesos Containerizer
+layout: documentation
+---
+
+# Cgroups 'cpu' and 'cpuacct' Subsystems Support in Mesos Containerizer
+
+The `cgroups/cpu` isolator allows operators to provide CPU isolation
+and CPU usage accounting for containers within a Mesos cluster. To
+enable the `cgroups/cpu` isolator, append `cgroups/cpu` to the
+`--isolation` flag when starting the Mesos agent.
+
+## Subsystems
+
+The isolator enables `cpu` and `cpuacct` subsystems for Linux cgroups
+and assigns `cpu` and `cpuacct` cgroups to each container launched by
+Mesos Containerizer.
+
+Cgroups `cpu` subsystem provides 2 mechanisms of limiting the amount
+of CPU time used by cgroups: [CFS shares](https://github.com/torvalds/linux/blob/master/Documentation/scheduler/sched-design-CFS.txt)
+and [CFS bandwidth](https://github.com/torvalds/linux/blob/master/Documentation/scheduler/sched-bwc.txt)
+control. The first one can guarantee some minimum number of CPU
+“shares” to a cgroup when the system is under heavy load. It, however,
+does not limit the amount of CPU time available to a cgroup when the
+system is not busy. This mechanism is always enabled when you turn on
+this isolator.
+
+The second mechanism introduces a way to define the upper limit of CPU
+time used by a cgroup within every scheduling period. Additionally it
+exports bandwidth statistics in `cpu.stat` file. CFS bandwidth
+mechanism can be enabled with `--cgroups_enable_cfs` agent flag.
+
+Cgroups `cpuacct` subsystem provides accounting for CPU usage by
+cgroup’s tasks. Currently it only provides statistics in
+`cpuacct.stat` that show time spent by tasks of the cgroup in user
+mode and kernel mode respectively
+
+Additionally the isolator provides accounting for the number of
+processes and threads inside a container based on the information from
+`cgroups.procs` and `tasks` files.
+
+## Effects on application when using CFS Bandwidth Limiting
+
+CPU usage is monitored during a scheduling period, which is currently
+set to 100ms. A task can use its requested CPU time before that period
+ends. For example, if a task is allocated 1 CPUs, it can use 2 CPU
+cores for 50ms thus consuming 100ms of CPU time, and be throttled for
+the remaining 50ms. Applications that are latency sensitive may suffer
+from effectively being stalled for 50ms.
+
+## Statistics
+
+This isolator exports several valuable per-container CPU usage metrics
+that are available from agent's `monitor/statistics`
+[endpoint](../endpoints/slave/monitor/statistics.md).
+
+  * `processes` - number of processes in the cgroup;
+  * `threads` - number of threads in the cgroup;
+  * `cpus_user_time_secs` - time spent by tasks of the cgroup in user
+    mode;
+  * `cpus_system_time_secs` - time spent by tasks of the cgroup in
+    kernel mode;
+  * `cpus_nr_periods` - number of enforcement intervals that have
+    elapsed;
+  * `cpus_nr_throttled` - number of times the cgroup has been
+    throttled;
+  * `cpus_throttled_time` - total time for which tasks in the cgroup
+    have been throttled.
+
+## Configuration
+
+<table class="table table-striped">
+  <thead>
+    <tr>
+      <th>Flag</th>
+      <th>Explanation</th>
+    </tr>
+  </thead>
+  <tr>
+    <td>
+      --[no]-cgroups_cpu_enable_pids_and_tids_count
+    </td>
+    <td>
+Cgroups feature flag to enable counting of processes and threads
+inside a container. (default: false)
+  </td>
+  </tr>
+  <tr>
+    <td>
+      --[no]-cgroups_enable_cfs
+    </td>
+    <td>
+Cgroups feature flag to enable hard limits on CPU resources via the
+CFS bandwidth limiting subfeature. (default: false)
+    </td>
+  </tr>
+  <tr>
+    <td>
+      --[no-]revocable_cpu_low_priority
+    </td>
+    <td>
+Run containers with revocable CPU at a lower priority than normal
+containers (non-revocable CPU). (default: true)
+    </td>
+  </tr>
+</table>

http://git-wip-us.apache.org/repos/asf/mesos/blob/8186f032/docs/mesos-containerizer.md
----------------------------------------------------------------------
diff --git a/docs/mesos-containerizer.md b/docs/mesos-containerizer.md
index 68ed273..4c82474 100644
--- a/docs/mesos-containerizer.md
+++ b/docs/mesos-containerizer.md
@@ -29,7 +29,7 @@ Mesos supports the following built-in isolators.
 - [environment\_secret](secrets.md#environment-based-secrets)
 - appc/runtime
 - cgroups/blkio
-- cgroups/cpu
+- [cgroups/cpu](isolators/cgroups-cpu.md)
 - cgroups/cpuset
 - cgroups/devices
 - cgroups/hugetlb