Create concepts definition page for CloudKitty

Change-Id: I55f1f2e0f792943fed74240fa6eb474f14f6aec2

doc/source/common-index.rst

@@ -10,6 +10,9 @@ CloudKitty allows to do metric-based rating: it polls endpoints in order to
 retrieve measures and metadata about specific metrics, applies rating rules to
 the collected data and pushes the rated data to its storage backend.
 
+More details about concepts, expressions, and jargons can be found in the
+`documentation of CloudKitty concepts`_.
+
 CloudKitty is highly modular, which makes it easy to add new features.
 
 .. only:: html
@@ -20,6 +23,7 @@ CloudKitty is highly modular, which makes it easy to add new features.
       a look at the `developer documentation`_ .
 
 .. _developer documentation: developer/index.html
+.. _documentation of CloudKitty concepts: concepts/index.html
 
 What can be done with CloudKitty ? What can't ?
 ===============================================

doc/source/concepts/index.rst

@@ -0,0 +1,145 @@
+CloudKitty Concepts
+======================
+
+This page provides the definitions for the concepts used in CloudKitty.
+It is recommended that you get familiar with them.
+
+
+Rating
+------
+It is the process of assigning a `value` to the consumption of computing
+resources. CloudKitty uses the concepts of services, which are rated.
+Therefore, one can configure services to be collected/monitored, and
+then through its processes, we can assign monetary values to the
+service consumption.
+
+The `value` assigned can be used to represent a monetary value in any
+currency. However, CloudKitty has no native module to execute conversions
+and apply any currency rate. The process to map/link a `value` to a real
+monetary charge is up to operators when configuring CloudKitty.
+
+Modules
+-------
+
+Modules define the rating processes that are enabled. To get to know more about
+the rating modules, one should check `rating modules`_ .
+
+.. _rating modules: ../user/rating/index.html
+
+
+Services
+--------
+
+Services define the metrics that are collected in a storage backend, and that
+are then rated by CloudKitty. Services need to be defined via API to be
+processed later by the rating modules, and configured in the collectors to be
+captured. Services are configured to be collected in the ``metrics.yml`` file.
+More information about service creation can be found at the `service
+configuration page`_.
+
+.. _service configuration page: ../admin/configuration/configuration.html
+
+
+Groups
+------
+
+Groups define sets of services that can be manipulated together. Groups are
+directly linked to rating rules, and not to services or fields.
+Therefore, if we want to group a set of rules to list them together
+or delete them, we can create a group and add them to the group, but
+in the end the resources are going to be charged based on the
+services, fields and rating rules.
+
+Fields
+------
+
+Fields define the attributes that are retrieved together with the service
+collection that can be used to activate a rating rule.
+
+
+PyScripts
+---------
+It is an alternative method of writing rating rule. When writing a PyScript,
+one will be able to handle the complete processing of the rating.
+Therefore, there is no need to create services, fields, and groups
+in CloudKitty. The PyScript logic should take care of all that.
+
+Rating rules
+------------
+Rating rules are the expressions used to create a charge (assign a value to
+a computing resource consumption). Rating rules can be created with
+PyScripts or with the use of fields, services and groups with hashmap
+rating rules.
+
+If we have a hashmap mapping configuration for a service and another
+hashmap map configuration for a field that belongs to the same service,
+the user is going to be charged twice, one for service and another for
+the field that activated a rating rule that is linked to the service.
+
+Rating type
+-----------
+Rating type is the expression used to determine a service definition in the
+collection backend. For instance, one can use the following syntax
+in the ``metrics.yml`` file. The entry
+``dynamic_pollster.compute.services.instance.status`` is the definition
+for rating types. In the example shown here, there are two rating
+types being defined, one called ``instance-usage-hours`` and the other
+called ``instance-operating-system-license``. The rating types are
+configured in CloudKitty API as services. If they are not configured,
+they will not be rated by rating rules defined with hashmap. Therefore,
+they would be collected, and persisted with value (price) as zero.
+
+..  code-block:: yaml
+
+    metrics:
+      dynamic_pollster.compute.services.instance.status:
+        - unit: instance
+          alt_name: instance-usage-hours
+          description: "compute"
+          groupby:
+            - id
+            - display_name
+            - flavor_id
+            - flavor_name
+            - user_id
+            - project_id
+            - revision_start
+            - availability_zone
+          metadata:
+            - image_ref
+            - flavor_vcpus
+            - flavor_ram
+            - operating_system_name
+            - operating_system_distro
+            - operating_system_type
+            - operating_system_version
+            - mssql_version
+          extra_args:
+            aggregation_method: max
+            resource_type: instance
+            use_all_resource_revisions: false
+        - unit: license-hours
+          alt_name: "instance-operating-system-license"
+          description: "license"
+          groupby:
+            - id
+            - display_name
+            - flavor_id
+            - flavor_name
+            - user_id
+            - project_id
+            - revision_start
+            - availability_zone
+            - operating_system_distro
+            - operating_system_name
+          metadata:
+            - image_ref
+            - flavor_vcpus
+            - flavor_ram
+            - operating_system_type
+            - operating_system_version
+          extra_args:
+            aggregation_method: max
+            resource_type: instance
+            use_all_resource_revisions: false
+

doc/source/index.rst

@@ -17,6 +17,12 @@ Documentation contents
    * - Documentation type
      - Table of contents
 
+   * - **Concepts**
+     - .. toctree::
+          :maxdepth: 3
+
+          concepts/index
+
    * - **End User**
      - .. toctree::
           :maxdepth: 3