route_upstream

This escaper chooses the next escaper from rules that match the upstream host or address.

There is no path selection support for this escaper.

The following common keys are supported:

Selection order is fixed by the runtime:

  • For IP upstreams: exact_match then subnet_match then default_next

  • For domain upstreams: exact_match then suffix_match then regex_match then default_next

Rules duplicated across different next escapers are rejected during config loading.

exact_match

optional, type: seq | map

If the host part of the upstream address exactly matches a configured rule, the corresponding escaper is selected.

For seq format:

Each rule is in map format, with two keys:

  • next

    required, type: metric node name

    Set the next escaper.

  • hosts

    optional, type: seq, alias: host

    Each element should be host.

    A host must not appear in rules for different next escapers.

Example:

- next: deny
  hosts:
    - example.net
- next: allow
  hosts:
    - 192.168.1.1

For map format:

Each key is the next escaper name, and each value has the same format as hosts in the sequence form.

Example:

deny:
  - example.net
allow:
  - 192.168.1.1

Changed in version 1.11.5: support map format

Example

default_next: direct
exact_match:
  deny:
    - blocked.example.net
suffix_match:
  internal:
    - corp.example.net
suffix_match:
  canary:
    - s1.example.net
regex_match:
  debug:
    - suffix: corp.example.net
      regex: '^test[0-9]+$'

subnet_match

optional, type: seq | map

If the host is an IP address and matches multiple subnets, the longest-prefix match is used.

For seq format:

Each rule is in map format, with two keys:

  • next

    required, type: metric node name

    Set the next escaper.

  • subnets

    optional, type: seq, alias: subnet

    Each element should be ip network str.

    A subnet must not appear in rules for different next escapers.

Example:

- next: deny
  subnets:
    - 192.168.0.0/16
- next: allow
  subnets:
    - 192.168.0.0/24

For map format:

Each key is the next escaper name, and each value has the same format as subnets in the sequence form.

Example:

deny:
  - 192.168.0.0/16
allow:
  - 192.168.0.0/24

Changed in version 1.11.5: support map format

suffix_match

optional, type: seq | map, alias: child_match

If the upstream domain ends with the suffix domain (a child of that domain), the corresponding escaper is selected.

For seq format:

Each rule is in map format, with two keys:

  • next

    required, type: metric node name

    Set the next escaper.

  • domains

    optional, type: seq, alias: domain

    Each element should be domain.

    A domain must not appear in rules for different next escapers.

Example:

- next: deny
  domains:
    - example.net
- next: allow
  domains:
    - test.example.net

For map format:

Each key is the next escaper name, and each value has the same format as domains in the sequence form.

Example:

deny:
  - example.net
allow:
  - test.example.net

Changed in version 1.11.5: support map format

Changed in version 1.13.3: suffix_match now matches by domain hierarchy instead of string suffix

regex_match

optional, type: seq | map

If the upstream domain matches one of the configured regular expressions, the corresponding escaper is selected.

For seq format:

Each rule is in map format, with two keys:

  • next

    required, type: metric node name

    Set the next escaper.

  • rules

    optional, type: seq, alias: rule

    Each element should be a map or regex str.

    The following keys are used in the map format:

    • suffix | parent

      optional, type: domain

      Parent domain to strip off, including the trailing ., before applying the regex. If omitted, the full domain is matched.

      Changed in version added: suffix key since version 1.13.3

    • regex

      required, type: regex str

      Regular expression to apply.

    A rule must not appear in rules for different next escapers.

Example:

- next: deny
  rules:
    - suffix: example.net
      regex: abc.*  # only match the sub part
- next: allow
  rules:
    - suffix: example.net
      regex: tes.+ # only match the sub part
    - .*[.]example[.]org  # match the full domain
# test.example.net will match `allow`

For map format:

Each key is the next escaper name, and each value has the same format as rules in the sequence form.

Example:

deny:
  - suffix: example.net
    regex: abc.*  # only match the sub part
allow:
  - suffix: example.net
    regex: tes.+ # only match the sub part
  - .*[.]example[.]org  # match the full domain
# test.example.net will match `allow`

Added in version 1.11.5.