diff --git a/doc/source/measurements.rst b/doc/source/measurements.rst
index 9a45a012e..6dc964b95 100644
--- a/doc/source/measurements.rst
+++ b/doc/source/measurements.rst
@@ -187,3 +187,17 @@ If you plan on adding meters, please follow the convention bellow:
    For example do not use <type>.image but image:<type>, where type is your variable name.
 
 3. If you have any hesitation, come and ask in #openstack-metering
+
+
+User-defined sample metadata (nova only)
+=========================================
+
+Users are allowed to add additional metadata to samples of nova meter.
+These additional metadata are stored in 'resource_metadata.user_metadata.*' of the sample
+To do so, users should add nova user metadata prefixed with 'metering.':
+
+::
+    $ nova boot --meta metering.custom_metadata=a_value my_vm
+
+Note: The name of the metadata shouldn't exceed 256 characters otherwise it will be cut off.
+Also, if it has '.', this will be replaced by a '_' in ceilometer.