anchor.diff:  ---
  -title: Using the CPU entitlement plugin
  +title: Using the CPU Entitlement Plugin
   owner: CLI
   ---
   
  -This topic describes how <%= vars.app_runtime_first %> admins can enable the CPU entitlement plugin to help them manage their CPU resources.
  +This topic describes how <%= vars.app_runtime_first %> administrators can use the CPU entitlement plugin to help them manage their CPU resources.
  +
   
   ## <a id='cpu-entitlement'></a> CPU Entitlement
   
  -If you wish to watch an overview of the topic, please see the following video: [CPU Entitlements in Cloud Foundry](https://www.youtube.com/watch?v=vV87xmxKLeA)
  +To watch an overview of the topic, see [CPU Entitlements in Cloud Foundry](https://www.youtube.com/watch?v=vV87xmxKLeA) on YouTube.
   
  -CPU entitlement describes the percentage of host CPU a particular application instance is ‘entitled’ to use. The CPU entitlement plugin will show that apps have a CPU performance of 100% when they are using exactly the CPU they are entitled. Apps will have a CPU performance of less than 100% when their usage is less than their entitlement and greater than 100% when they are above their entitlement.
  +CPU entitlement describes the percentage of host CPU a particular app instance is _entitled_ to use. The CPU entitlement plugin shows that apps have a CPU performance of 100% when they are using exactly the CPU they are entitled. Apps have a CPU performance of less than 100% when their usage is less than their entitlement and greater than 100% when they are above their entitlement.
   
  -In Cloud Foundry the amount of CPU an application is entitled to is proportional to its allocated memory. By default, an application with access to 256MB of memory on a 512MB machine has access to half of the memory on the machine and is also entitled to half of the CPU of that machine. 
  +In <%= vars.app_runtime_abbr %>, apps have CPU entitlements that are proportional to their allocated memory by default. For example, an app with access to 256MB of memory on a 512&nbsp;MB machine has access to half of the memory on the machine and is also entitled to half of the CPU of that machine.
   
  -An operator can change the exact mapping of memory to CPU by configuring the garden bosh release property called [`experimental_cpu_entitlement_per_share_in_percent`](https://github.com/cloudfoundry/garden-runc-release/blob/9d9826d08b72c0d8b7a7d968b1311047039be08c/jobs/garden/spec#L165-L167). This property changes the CPU percentage entitled to a container per CPU share. A value of 0.3 would mean that each application has access to 0.3% of the total CPU per share.
  +An operator can change the exact mapping of memory to CPU by configuring the Garden BOSH release property called `experimental_cpu_entitlement_per_share_in_percent`. This property changes the CPU percentage entitled to a container per CPU share. For example, a value of `0.3` would mean that each app has access to 0.3% of the total CPU per share.
   
  -By default the total shares available on a host is equal to the amount of memory on the host, an optimal value for `experimental_cpu_entitlement_per_share_in_percent` is 100% divided by the amount of total memory on the host. For example, a host with 1024MB of memory would have an optimal value of 100 / 1024, which is 0.0977% per share. An 256MB application would have access to 76.8% of the total CPU - in this case an operator has overcommitted on the amount of CPU available (assuming a single core machine).
  +By default, the total shares available on a host is equal to the amount of memory on the host, an optimal value for `experimental_cpu_entitlement_per_share_in_percent` is 100% divided by the amount of total memory on the host. For example, a host with 1024&nbsp;MB of memory would have an optimal value of `100 / 1024`, which is 0.0977% per share. An 256&nbsp;MB app would have access to 76.8% of the total CPU. In this case, if there is only a single core machine, an operator has overcommitted the amount of CPU available.
   
  -There are three possible states that emerge from how operators configure `experimental_cpu_entitlement_per_share_in_percent`:
  +The way you configure `experimental_cpu_entitlement_per_share_in_percent` can create three possible states for the apps in your <%= vars.app_runtime_abbr %> deployment:
   
  -1. undercommitted - applications’ CPU entitlements are guaranteed minimums, but some host CPU might not be used
  -2. optimal - applications’ CPU entitlements are guaranteed minimums
  -3. overcommitted - applications are not guaranteed to have access to their entitlement
  +* Undercommitted - apps' CPU entitlements are guaranteed minimums, but some host CPU might not be used
   
  -Below are a few examples of this value being configured optimally for machines with different total memory and number of CPU cores.
  +* Optimal - apps' CPU entitlements are guaranteed minimums
  +
  +* Overcommitted - apps are not guaranteed to have access to their entitlement
  +
  +The following table contains examples of optimal values for machines with different total memory and number of CPU cores:
   
   |         | 256M  | 1024M | 8192M |
   | ------- |:-----:|:-----:|:-----:|
  
positive.code: | 4 cores | 1.563 | 0.39  | 0.049 |
  | 8 cores | 3.125 | 0.781 | 0.098 |
  
  ## <a id='cpu-entitlement-plugin'></a> CPU Entitlement Plugin
  
  The metric `absolute_entitlement` shows an app's CPU usage relative to an its entitlement. 
  
  To retrieve `absolute_entitlement` metrics for all instances of an app:
  
  1. Install the CPU Entitlement Plugin from [cpu-entitlement-plugin](https://github.com/cloudfoundry/cpu-entitlement-plugin) in GitHub.
  
  2. In a terminal window, run:
  
      ```
      cf cpu-entitlement APP-NAME
  
negative.code:     &#35;2   2.51%       2.62%
      </pre>
  
  After you run the `cf cpu-entitlement` command, you see two values: `avg usage` and `curr usage`. The average usage is used to split the app into two groups, good and bad. Good apps have an average CPU usage that is below 100% of their CPU entitlements, and bad apps have an average CPU usage that is over 100% of their CPU entitlements. In the example above, all values for the average CPU usage are under 100% of their CPU entitlements.
  
  
  ## <a id='cpu-throttling'></a> Spare CPU Resources and Throttling
  
  If there are three cores on the Diego Cell to which your app is deployed, 300% CPU can be distributed between all the apps on the Diego Cell. This is the percentage that the `cf app` command displays. The metrics depend on factors such as the capacity of the Diego Cell and the total number of apps on it that are not visible to the user. This can make it difficult for users and operators to balance CPU resources.
  
  An app always receives 100% of its CPU entitlement, no matter what other apps are on the Diego Cell. If there are spare resources on the machine, an app can consume over 100% CPU.
  
  Let’s see how the spare resources are distributed on the Diego Cell when the `experimental_cpu_throttling` property is set to `false`. If an app consumes less than its entitlement most of the time and then needs CPU resources over its entitlement, it receives the maximum amount of CPU resources it needs from the spare CPU. but without the CPU entitlement feature free depends on the other apps running on the same Diego Cell. If the other apps constantly use high CPU, they restrict other apps to occasionally use more CPU when needed. Even though the other apps on the same Diego Cell usually use much more than their CPU entitlements, when an app that usually consumes less than its CPU entitlement needs extra CPU, the spare capacity is distributed evenly between that app and all the other apps. Because of this, that app can never spike over a certain amount of CPU. To occasionally provide the bandwidth, operators may overprovision resources for Diego Cells.
  
  When the `experimental_cpu_throttling` property is set to `false`, apps are allowed to temporarily exceed their entitlement again, but apps that have been using less than their entitlement over a longer period of time are prioritized. Apps are never forced below their entitlement.
  
  Both good and bad apps always get their entitlement. If you are using the CPU Entitlement plugin, the difference is in how the spare CPU gets distributed between them. All spare CPU is given to the good app that needs it, and the bad apps are throttled to only the amount of CPU to which they are entitled.
  
  If the CPU spike of a good app is for a long period of time, it eventually becomes a bad app and therefore is throttled to 100% if a different good app needs the CPU. This way, resources get distributed more fairly between apps.
  