summaryrefslogtreecommitdiffstats
path: root/source/rainerscript/functions/rs-percentile_observe.rst
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--source/rainerscript/functions/rs-percentile_observe.rst33
1 files changed, 33 insertions, 0 deletions
diff --git a/source/rainerscript/functions/rs-percentile_observe.rst b/source/rainerscript/functions/rs-percentile_observe.rst
new file mode 100644
index 0000000..40bc81f
--- /dev/null
+++ b/source/rainerscript/functions/rs-percentile_observe.rst
@@ -0,0 +1,33 @@
+********************
+percentile_observe()
+********************
+
+Purpose
+=======
+
+percentile_observe(bucket_name_literal_string, stats_name_literal_string, value)
+
+Adds an observation, identified by the ``bucket_name_literal_string``
+and ``stats_name_literal_string``, to the observation set.
+
+Periodically, on an **impstats** reporting interval, percentile and summary metrics are generated
+based on the statistics collected.
+
+Except for special circumstances (such as memory allocation failing etc),
+observe calls may fail due to stat-name cardinality being under-estimated.
+Bucket is configured to support a maximum cardinality (to prevent abuse)
+and it rejects observe-operation if it encounters a new(previously unseen)
+stat-name(``str``) when full.
+
+**Read more about it here** :doc:`Percentile Stats<../../configuration/percentile_stats>`
+
+
+Example
+=======
+
+In the following example, the ``$msg_count`` value is being recorded as a ``msg_per_host`` statistic in the ``host_statistics`` bucket.
+
+
+.. code-block:: none
+
+ percentile_observe("host_statistics", "msg_per_host", $msg_count)