From 2b20f6355fbaff2b7263362c7d6f7ed36c6b54d8 Mon Sep 17 00:00:00 2001
From: Michael Friedrich <Michael.Friedrich@netways.de>
Date: Sun, 11 May 2014 15:31:29 +0200
Subject: [PATCH] Documentation: Explain how runtime macro evaluation order
 works.

Fixes #6010
---
 doc/3-monitoring-basics.md | 60 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)

diff --git a/doc/3-monitoring-basics.md b/doc/3-monitoring-basics.md
index b5c4995da..e301e49f5 100644
--- a/doc/3-monitoring-basics.md
+++ b/doc/3-monitoring-basics.md
@@ -984,6 +984,66 @@ These runtime macros reflect the current object state and may change over time w
 custom attributes are configured statically (but can be modified at runtime using
 external commands).
 
+### <a id="runtime-macro-evaluation-order"></a> Runtime Macro Evaluation Order
+
+Custom attributes can be accessed at [runtime](#runtime-custom-attributes) using their
+identifier omitting the `vars.` prefix.
+There are special cases when those custom attributes are not set and Icinga 2 provides
+a fallback to existing object attributes for example `host.address`.
+
+In the following example the `$address$` macro will be resolved with the value of `vars.address`.
+
+    object Host "localhost" {
+      import "generic-host"
+      check_command = "my-host-macro-test"
+      address = "127.0.0.1"
+      vars.address = "127.2.2.2"
+    }
+
+    object CheckCommand "my-host-macro-test" {
+      command = "echo \"address: $address$ host.address: $host.address$ host.vars.address: $host.vars.address$\""
+    }
+
+The check command output will look like
+
+    "address: 127.2.2.2 host.address: 127.0.0.1 host.vars.address: 127.2.2.2"
+
+If you alter the host object and remove the `vars.address` line, Icinga 2 will fail to look up `$address$` in the
+custom attributes dictionary and then look for the host object's attribute.
+
+The check command output will change to
+
+    "address: 127.0.0.1 host.address: 127.0.0.1 host.vars.address: "
+
+
+The same example can be defined for services overriding the `address` field based on a specific host custom attribute.
+
+    object Host "localhost" {
+      import "generic-host"
+      address = "127.0.0.1"
+      vars.macro_address = "127.3.3.3"
+    }
+
+    apply Service "my-macro-test" to Host {
+      import "generic-service"
+      check_command = "my-service-macro-test"
+      vars.address = "$host.vars.macro_address$"
+
+      assign where host.address
+    }
+
+    object CheckCommand "my-service-macro-test" {
+      command = "echo \"address: $address$ host.address: $host.address$ host.vars.macro_address: $host.vars.macro_address$ service.vars.address: $service.vars.address$\""
+    }
+
+When the service check is executed the output looks like
+
+    "address: 127.3.3.3 host.address: 127.0.0.1 host.vars.macro_address: 127.3.3.3 service.vars.address: 127.3.3.3"
+
+That way you can easily override existing macros being accessed by their short name like `$address$` and refrain
+from defining multiple check commands (one for `$address$` and one for `$host.vars.macro_address$`).
+
+
 ### <a id="host-runtime-macros"></a> Host Runtime Macros
 
 The following host custom attributes are available in all commands that are executed for