Add /v3/info/usage_summary endpoint

This endpoint allows admin-like users to see a rolled-up summary of
usage across the whole platform. It calculates the number of started
process instances and the total memory usage of started process
instances and running tasks.

[finishes #169070596]

Co-authored-by: Reid Mitchell <rmitchell@pivotal.io>
Co-authored-by: Teal Stannard <tstannard@pivotal.io>
Co-authored-by: Mona Mohebbi <mmohebbi@pivotal.io>

Author: 3 people

app/controllers/v3/application_controller.rb

@@ -37,15 +37,19 @@ def service_unavailable!(message)
   def resource_not_found!(resource)
     raise CloudController::Errors::NotFound.new_from_details('ResourceNotFound', "#{resource.to_s.humanize} not found")
   end
+
+  def not_found!
+    raise CloudController::Errors::NotFound.new_from_details('NotFound')
+  end
 end
 
 class ApplicationController < ActionController::Base
   include VCAP::CloudController
   include V3ErrorsHelper
   include VCAP::CloudController::ParamsHashifier
 
-  ANONYMOUSLY_AVAILABLE = ['not_found', 'internal_error', 'bad_request'].map(&:freeze).freeze
-  UNSCOPED_PAGES = ['not_found', 'internal_error', 'bad_request', 'v3_root'].map(&:freeze).freeze
+  ANONYMOUSLY_AVAILABLE = ['not_found', 'internal_error', 'bad_request', 'v3_info'].map(&:freeze).freeze
+  UNSCOPED_PAGES = ['not_found', 'internal_error', 'bad_request', 'v3_root', 'v3_info'].map(&:freeze).freeze
   READ_SCOPE_HTTP_METHODS = ['GET', 'HEAD'].map(&:freeze).freeze
   YAML_CONTENT_TYPE = 'application/x-yaml'.freeze
 

app/controllers/v3/info_controller.rb

@@ -1,7 +1,9 @@
+require 'fetchers/global_usage_summary_fetcher'
 require 'presenters/v3/info_presenter'
+require 'presenters/v3/info_usage_summary_presenter'
 
-class InfoController < ActionController::Base
-  def show
+class InfoController < ApplicationController
+  def v3_info
     info = Info.new
     config = VCAP::CloudController::Config.config
 
@@ -16,6 +18,14 @@ def show
 
     render status: :ok, json: VCAP::CloudController::Presenters::V3::InfoPresenter.new(info)
   end
+
+  def show_usage_summary
+    not_found! unless permission_queryer.can_read_globally?
+
+    summary = VCAP::CloudController::GlobalUsageSummaryFetcher.summary
+
+    render status: :ok, json: VCAP::CloudController::Presenters::V3::InfoUsageSummaryPresenter.new(summary)
+  end
 end
 
 class Info

app/fetchers/global_usage_summary_fetcher.rb

@@ -0,0 +1,32 @@
+module VCAP::CloudController
+  class GlobalUsageSummaryFetcher
+    class << self
+      def summary
+        summary = Summary.new
+
+        summary.started_instances = ProcessModel.
+                                    dataset.
+                                    where(state: ProcessModel::STARTED).
+                                    sum(:instances) || 0
+
+        running_task_memory = TaskModel.
+                              dataset.
+                              where(state: TaskModel::RUNNING_STATE).
+                              sum(:memory_in_mb) || 0
+
+        started_app_memory = ProcessModel.
+                             dataset.
+                             where(state: ProcessModel::STARTED).
+                             sum(Sequel.*(:memory, :instances)) || 0
+
+        summary.memory_in_mb = running_task_memory + started_app_memory
+
+        summary
+      end
+
+      class Summary
+        attr_accessor :started_instances, :memory_in_mb
+      end
+    end
+  end
+end

app/presenters/v3/info_usage_summary_presenter.rb

@@ -0,0 +1,29 @@
+require 'presenters/v3/base_presenter'
+require 'presenters/mixins/metadata_presentation_helpers'
+require 'presenters/helpers/censorship'
+
+module VCAP::CloudController::Presenters::V3
+  class InfoUsageSummaryPresenter < BasePresenter
+    def to_hash
+      {
+        usage_summary: {
+          started_instances: usage_summary.started_instances,
+          memory_in_mb: usage_summary.memory_in_mb
+        },
+        links: {
+          self: { href: build_self }
+        }
+      }
+    end
+
+    private
+
+    def usage_summary
+      @resource
+    end
+
+    def build_self
+      url_builder.build_url(path: '/v3/info/usage_summary')
+    end
+  end
+end

config/routes.rb

@@ -312,7 +312,8 @@
   delete '/roles/:guid', to: 'roles#destroy'
 
   # info
-  get '/info', to: 'info#show'
+  get '/info', to: 'info#v3_info'
+  get '/info/usage_summary', to: 'info#show_usage_summary'
 
   namespace :internal do
     patch '/builds/:guid', to: 'builds#update'

docs/v3/source/includes/api_resources/_info.erb

@@ -35,3 +35,15 @@
   }
 }
 <% end %>
+
+<% content_for :info_usage_summary do %>
+{
+  "usage_summary": {
+    "started_instances": 294,
+    "memory_in_mb": 123945
+  },
+  "links": {
+    "self": { "href": "http://api.example.com/v3/info/usage_summary" }
+  }
+}
+<% end %>

docs/v3/source/includes/resources/info/_get.md.erb

@@ -32,7 +32,8 @@ Content-Type: application/json
 ```
 
 #### Definition
-`GET /v3/info` <br>
+
+`GET /v3/info`
 
 #### Authentication
 

docs/v3/source/includes/resources/info/_get_usage_summary.md.erb

@@ -0,0 +1,42 @@
+### Get platform usage summary
+
+```
+Example Request
+```
+
+```shell
+curl "https://api.example.org/v3/info/usage_summary" \
+  -X GET
+```
+
+```
+Example Response
+```
+
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+<%= yield_content :info_usage_summary %>
+```
+
+This endpoint retrieves a high-level summary of usage across the entire Cloud Foundry installation.
+
+#### Definition
+
+`GET /v3/info/usage_summary`
+
+#### Usage summary object
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| **started_instances** | _integer_ | Total number of process instances in the `STARTED` state. |
+| **memory_in_mb** | _integer_ | Sum of memory usage of all tasks in the `RUNNING` state and all process instances in the `STARTED` state. |
+
+#### Permitted roles
+
+ |
+--- | ---
+Admin |
+Admin Read-Only |
+Global Auditor |

docs/v3/source/index.md

@@ -142,6 +142,7 @@ includes:
   - resources/feature_flags/update
   - resources/info/header
   - resources/info/get
+  - resources/info/get_usage_summary
   - resources/isolation_segments/header
   - resources/isolation_segments/object
   - resources/isolation_segments/create

lib/cloud_controller/global_usage_calculator.rb

@@ -0,0 +1,11 @@
+module VCAP::CloudController
+  class GlobalUsageCalculator
+    def self.instance_usage
+      ProcessModel.dataset.where(state: ProcessModel::STARTED).sum(:instances) || 0
+    end
+
+    def self.memory_usage
+      0
+    end
+  end
+end