Debugging #

Debugging is configured via the $FLAT_DEBUG environment variable. Its value is composed of at most three parts separated by colons (:): topic:level:sink.

topic denotes a topic you’re interested in, for example flow, request or time. The default is * meaning “all topics”. Several comma-separated topic identifiers are also valid.

level specifies the log level. Valid values are verbose, debug, info, warning, deprecation, error and alert, with error being the default.

sink identifies the log sink. Valid values are inline, append and log. The default value is log. The values inline and append mostly make sense when debugging single requests via the Debug header, see below.

The empty string for all three parts is also valid with the same meaning as the default value *:error:log.

If the third part is missing, the default value for sink (log) is assumed. If both the second and third part are missing, the default values for level and sink are assumed (error:log).

Examples #

Request Debugging #

The default debugging configuration set via $FLAT_DEBUG may be varied for single requests by sending the desired parameters in the HTTP Debug header field, for example:

$ curl -H "Debug: request:info:append" localhost:8080

To use request debugging, you must enable it by setting the $FLAT_DEBUG_ALLOW_HEADER environment variable to true or by turning on password protection via the $FLAT_DEBUG_AUTH environment variable. If authorization is required, the password has to be appended as ;auth=… in the Debug header, for example:

$ curl -H "Debug: flow::append; auth=Pas5W0Rd" localhost:8080

Selective Action Debugging #

Using an action type, such as template, for debugging often yields a large amount of information. Therefore, the debugging topic can be further limited by using the debug attribute which is available on all actions.

<flow>
  <template>{"foo": 1}</template>
  <template debug="bar">{"bar": 2}</template>
</flow>

Given the flow above, debugging the template topic will log all template operations:

$ curl -H "Debug: template" localhost:8080

However, as we tagged the second template action with the debug topic bar we are able to debug it separately:

$ curl -H "Debug: bar" localhost:8080

An action can have multiple comma-separated topics in the debug attribute. Each topic can also be used in several actions, for example to combine related actions into one common debug topic.

Usually, you create your own topic names. However, you can also use FLAT’s built-in topics, such as request, to include additional output in the log:

<flow>
  <template debug="request" out="$url">{{ concat("http://", "example.com") }}</template>
  <request>
  {
    "url": {{ $url }}
  }
  </request>
</flow>

When debugging that flow with topic request, you will get information about the request and also see where its URL came from.

See also #