code.grnet.gr Git - aquarium/blob - doc/manual/source/devguide.rst

   1 Aquarium Development Guide
   2 ==========================
   3
   4 The development guide includes descriptions of the APIs and extention points
   5 offered by Aquarium. It also includes design and development setup information.
   6
   7 The accounting system
   8 ----------------------
   9
  10 The accounting subsystem deals with
  11 accepts usage events from other systems and translates
  12 them to accounting entries in the user's wallet.
  13
  14 Entities
  15 ^^^^^^^^
  16
  17 - *Raw Event*: A raw event is generated from an external source and are permanently appended in an immutable event log. A raw event carries information about changes in an external system that affect the status of a user's wallet. Raw events processed by the system are listed below.
  18 - *AccountingEvent*: An accounting event is the result of processing one or more raw events, and is the only input to the accounting system. An accounting event associates the
  19 - *AccountingEntry*: An accounting entry is the result of processing one accounting event and is what gets stored to the user's wallet.
  20 - *Resource*: A resource represents an entity that can be charged for its usage. The currently charged resources are: Time of VM usage, bytes uploaded and downloaded and bytes used for storage
  21 - *PriceList*: A price list contains information of the cost of a resource. A specific pricelist is only applied within a specified time frame.
  22 - *Policy*: A policy specifies the way the charge calculation is done. It can be vary depending on resource usage, time of raw event or other information.
  23 - *Agreement*: An agreement associates pricelists with policies and users.
  24
  25
  26 Common syntax
  27 ^^^^^^^^^^^^^
  28
  29 Implicit variables
  30 ~~~~~~~~~~~~~~~~~~
  31
  32 Implicit variables are placeholders that are assigned a value at evaluation
  33 time. Variables are always bound to a resource declaration within a policy.
  34 The following implicit values are supported:
  35
  36 - ``price``: Denotes the price for the designated resource in the applicable agreement
  37 - ``volume``: Denotes the runtime usage of the designated resource
  38
  39 Operators
  40 ~~~~~~~~~
  41
  42 - Conditionals: ``if...then...elsif...else...end`` Conditional decisions.
  43 - Comparison: ``gt, lt``: ``>`` and ``<``
  44
  45 Time frames
  46 ~~~~~~~~~~~
  47
  48 Time frames allow the specification of applicability periods for policies,
  49 pricelists and agreements. A timeframe is by default continuous and has a
  50 starting point; if there is no ending point, the timeframe is considered open
  51 and its ending point is the time at the time of evaluation.
  52
  53 A time frame definition can contain repeating time ranges that dissect it and
  54 consequently constrain the applicability of the time frame to the defined
  55 ranges only. A range always has a start and end point. A range is repeated
  56 within a timeframe, until the timeframe end point is reached. In case a
  57 repeating range ends later than the containing timeframe, the ending time is
  58 adjusted to match that of the timeframe.
  59
  60 The definition of the starting and ending point of a time range is done in a
  61 syntax reminisent of the `cron <http://en.wikipedia.org/wiki/Cron>`_ format.
  62
  63 .. code-block:: yaml
  64
  65   applicable:
  66     from:                            # Milliseconds since the epoch
  67     to:                              # [opt] Milliseconds since the epoch
  68     repeat:                          # [opt] Defines a repetion list
  69       - every:                       # [opt] A repetion entry
  70         start: "min hr dom moy dow"  # 5-elem cron string
  71         end:   "min hr dom moy dow"  # 5-elem cron string
  72
  73 The following declaration defines a timeframe starting at the designated
  74 timestamp and ending at the time of evaluation.
  75
  76 .. code-block:: yaml
  77
  78   applicable:
  79     from: 1293703200  #(30/12/2010 10:00)
  80
  81 The following declaration defines a timeframe of one year, within which the
  82 applicability of the specified policy, agreement or pricelist is constrained to
  83 time ranges from 12:00 Mon to 14:00 Fri  (first ``every`` definition)
  84 and 15:00 Sat to 15:00 Sun.
  85
  86 .. code-block:: yaml
  87
  88   applicable:
  89     from: 1293703200  #(30/12/2010 10:00)
  90     to:   1325239200  #(30/12/2011 10:00)
  91     repeat:
  92       - every:
  93         start: "00 12 * * Mon"
  94         end:   "00 14 * * Fri"
  95       - every:
  96         start: "00 15 * * Sat"
  97         end:   "00 15 * * Sun"
  98
  99
 100 .. toctree::
 101
 102   debitdsl
 103   creditdsl
 104
 105
 106 Document Revisions
 107 ^^^^^^^^^^^^^^^^^^
 108
 109 ==================    ================================
 110 Revision              Description
 111 ==================    ================================
 112 0.1 (Nov 2, 2011)     Initial release. Credit and debit policy descriptions
 113 ==================    ================================
 114
 115