traffic-tag - API Gateway - Alibaba Cloud Documentation Center

You can use the traffic-tag plug-in to tag request traffic based on weight or specific request content by adding specific request headers. You can use the traffic-tag plug-in to configure complex-logic rules for traffic tagging.

Running attributes

Plug-in execution stage: default stage. Plug-in execution priority: 400.

Fields

This section describes the fields that you can configure for the plug-in.

Field	Type	Default value	Required	Description
`conditionGroups`	array of object	-	No	The content-based condition groups. For more information, see the conditionGroups configurations section in this topic.
`weightGroups`	array of object	-	No	The weight-based condition groups. For more information, see the weightGroups configurations section in this topic.
`defaultTagKey`	string	-	No	The default tag key. If no condition is matched, the default tag key is used. This field takes effect only if the defaultTagVal field is configured.
`defaultTagVal`	string	-	No	The default tag value. If no condition is matched, the default tag value is used. This field takes effect only if the defaultTagKey field is configured.

conditionGroups configurations

The following table describes the fields in the conditionGroups field.

Field	Type	Default value	Required	Description
`headerName`	string	-	Yes	The name of the HTTP header that you want to add or modify.
`headerValue`	string	-	Yes	The value of the HTTP header.
`logic`	string	-	Yes	The logical relationship among conditions, which can be `and` or `or`. The value must be in lowercase.
`conditions`	array of object	-	Yes	The tagging conditions.

The following table describes the fields in the conditions field.

Field	Type	Default value	Required	Description
`conditionType`	string	-	Yes	The condition type, which can be `header`, `parameter`, or `cookie`.
`key`	string	-	Yes	The condition keyword.
`operator`	string	-	Yes	The operator, which can be `equal`, `not_equal`, `prefix`, `in`, `not_in`, `regex`, or `percentage`.
`value`	array of string	-	Yes	The condition value. You can configure multiple values only if the operator is `in` or `not_in`.

Note

If the operator is regex, the regular expression engine RE2 is used. For more information, see RE2 official documentation.

weightGroups configurations

The following table describes the fields in the weightGroups field.

Field	Type	Default value	Required	Description
`headerName`	string	-	Yes	The name of the HTTP header that you want to add or modify.
`headerValue`	string	-	Yes	The value of the HTTP header.
`weight`	integer	-	Yes	The traffic weight in percentage.

Operators

Operator	Description
`equal`	If a value is exactly the same as the specified value, a condition is met.
`not_equal`	If a value differs from the specified value, a condition is met.
`prefix`	If a value is prefixed with the specified value, a condition is met.
`in`	If a value is included in the specified list, a condition is met.
`not_in`	If a value is excluded from the specified list, a condition is met.
`regex`	If a value complies with the regular expression rules, a condition is met.
`percentage`	If the inequality `hash(get(key)) % 100 < value` is true, a condition is true.

Note

The percentage operator and weight field differ in the following aspects:

percentage: used in a conditional expression to determine whether to perform an operation based on a specified percentage and key-value pair. For a key-value pair, the results of multiple matches are idempotent. If a condition is hit, the condition will be hit in subsequent matches.
weight: used to define the weight for routing traffic to different paths. If traffic is tagged based on weight, the weight field determines the percentage of traffic that is routed to a path. Unlike the percentage operator, the weight field does not define a fixed comparison basis, and traffic is randomly distributed based on weight. A request may be routed to different paths in different matches.

If you use the percentage operator, the system determines whether a request meets specified percentage conditions. If you use the weight field, the system distributes traffic in a static and random manner.

Configuration examples

Example 1: content-based matching

In the following sample code, if the header role of a request is user, viewer, or editor and foo=bar is specified in the request, the header x-mse-tag: gray is added to the request. If no condition is matched for a request, the header x-mse-tag: base is added to the request, as defined in the configurations of the defaultTagKey and defaultTagVal fields.

defaultTagKey: x-mse-tag
defaultTagVal: base
conditionGroups:
  - headerName: x-mse-tag
    headerValue: gray
    logic: and
    conditions:
      - conditionType: header
        key: role
        operator: in
        value:
          - user
          - viewer
          - editor
      - conditionType: parameter
        key: foo
        operator: equal
        value:
        - bar

Example 2: weight-based matching

In the following sample code, a request has a 30% chance of being added with the request header x-mse-tag: gray, another 30% chance of being added with the request header x-mse-tag: blue, and a 40% chance of being added with no request header.

# The total weight is 100. The weight value 40, which is not configured, indicates that no header is added.
weightGroups:
  - headerName: x-mse-tag
    headerValue: gray
    weight: 30
  - headerName: x-mse-tag
    headerValue: blue
    weight: 30