From 8c1ad7d0c6dce95cdfd3348021f0e70f74445bfc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rafael=20Weing=C3=A4rtner?= Date: Thu, 27 Apr 2023 16:20:55 -0300 Subject: [PATCH] Create concepts definition page for CloudKitty Change-Id: I55f1f2e0f792943fed74240fa6eb474f14f6aec2 --- doc/source/common-index.rst | 4 + doc/source/concepts/index.rst | 145 ++++++++++++++++++++++++++++++++++ doc/source/index.rst | 6 ++ 3 files changed, 155 insertions(+) create mode 100644 doc/source/concepts/index.rst diff --git a/doc/source/common-index.rst b/doc/source/common-index.rst index f87a712e..7660240b 100644 --- a/doc/source/common-index.rst +++ b/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 ? =============================================== diff --git a/doc/source/concepts/index.rst b/doc/source/concepts/index.rst new file mode 100644 index 00000000..45eb0527 --- /dev/null +++ b/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 + diff --git a/doc/source/index.rst b/doc/source/index.rst index d5ebb57d..a305beaf 100644 --- a/doc/source/index.rst +++ b/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