granicus.if.org Git - icinga2/blob - doc/19-script-debugger.md

   1 # <a id="script-debugger"></a> Script Debugger
   2
   3 You can run the Icinga 2 daemon with the `-X` (`--script-debugger`)
   4 parameter to enable the script debugger:
   5
   6     # icinga2 daemon -X
   7
   8 When an exception occurs or the [debugger](17-language-reference.md#breakpoints)
   9 keyword is encountered in a user script, Icinga 2 launches a console that
  10 allows the user to debug the script.
  11
  12 Here is a list of common errors which can be diagnosed with the script debugger:
  13
  14 * Configuration errors (apply)
  15 * Errors in user-defined functions
  16
  17 ## <a id="script-debugger-config-errors"></a> Debugging Configuration Errors
  18
  19 The following example illustrates the problem of a service [apply rule](3-monitoring-basics.md#using-apply-for)
  20 which expects a dictionary value for `config`, but the host custom attribute only
  21 provides a string value:
  22
  23     object Host "script-debugger-host" {
  24       check_command = "icinga"
  25
  26       vars.http_vhosts["example.org"] = "192.168.1.100" // a string value
  27     }
  28
  29     apply Service for (http_vhost => config in host.vars.http_vhosts) {
  30       import "generic-service"
  31
  32       vars += config // expects a dictionary
  33
  34       check_command = "http"
  35     }
  36
  37 The error message on config validation will warn about the wrong value type,
  38 but does not provide any context which objects are affected.
  39
  40 Enable the script debugger and run the config validation:
  41
  42     # icinga2 daemon -C -X
  43
  44     Breakpoint encountered in /etc/icinga2/conf.d/services.conf: 59:67-65:1
  45     Exception: Error: Error while evaluating expression: Cannot convert value of type 'String' to an object.
  46     Location:
  47     /etc/icinga2/conf.d/services.conf(62):   check_command = "http"
  48     /etc/icinga2/conf.d/services.conf(63):
  49     /etc/icinga2/conf.d/services.conf(64):   vars += config
  50                                              ^^^^^^^^^^^^^^
  51     /etc/icinga2/conf.d/services.conf(65): }
  52     /etc/icinga2/conf.d/services.conf(66):
  53     You can inspect expressions (such as variables) by entering them at the prompt.
  54     To leave the debugger and continue the program use "$continue".
  55     <1> =>
  56
  57 You can print the variables `vars` and `config` to get an idea about
  58 their values:
  59
  60     <1> => vars
  61     null
  62     <2> => config
  63     "192.168.1.100"
  64     <3> =>
  65
  66 The `vars` attribute has to be a dictionary. Trying to set this attribute to a string caused
  67 the error in our configuration example.
  68
  69 In order to determine the name of the host where the value of the `config` variable came from
  70 you can inspect attributes of the service object:
  71
  72     <3> => host_name
  73     "script-debugger-host-01"
  74     <4> => name
  75     "http"
  76
  77 Additionally you can view the service object attributes by printing the value of `this`.
  78
  79 ## <a id="script-debugger-breakpoints"></a> Using Breakpoints
  80
  81 In order to halt execution in a script you can use the `debugger` keyword:
  82
  83     object Host "script-debugger-host-02" {
  84       check_command = "dummy"
  85       check_interval = 5s
  86
  87       vars.dummy_text = {{
  88         var text = "Hello from " + macro("$name$")
  89         debugger
  90         return text
  91       }}
  92     }
  93
  94 Icinga 2 will spawn a debugger console every time the function is executed:
  95
  96     # icinga2 daemon -X
  97     ...
  98     Breakpoint encountered in /etc/icinga2/tests/script-debugger.conf: 7:5-7:12
  99     You can inspect expressions (such as variables) by entering them at the prompt.
 100     To leave the debugger and continue the program use "$continue".
 101     <1> => text
 102     "Hello from script-debugger-host-02"
 103     <2> => $continue
 104
 105