Tracing Policy

Policy Name

Tracing

Summary

Override global tracing configuration

Category

Troubleshooting

First Flex Gateway version available

1.10.0

Returned Status Codes

No return codes exist for this policy

Summary

The Tracing policy enables you to override the global distributed tracing parameters for an API.

Before You Begin

Distributed tracing is disabled by default. After you have enabled distributed tracing with a Flex Gateway global configuration, you can use this policy to override the global distributed tracing parameters for an API.

For details on how to enable distributed tracing, see:

Configuring Policy Parameters

Flex Gateway Local Mode

In Local Mode, you apply the policy to your API via declarative configuration files. Refer to the following policy definition and table of parameters:

- policyRef:
    name: tracing-flex
  config:
    sampling:
      client: number // REQUIRED
      random: number // REQUIRED
      overall: number // REQUIRED
    spanName: <string> // OPTIONAL
    labels: <array> // OPTIONAL, default: []
      - name: <string> // REQUIRED
        type: <string> // REQUIRED
        keyName: <string> // REQUIRED
        defaultValue: <string> // REQUIRED

Parameter Required or Optional Default Value Description

Parameter	Required or Optional	Default Value	Description
`sampling.client`	Required	100	The target percentage of requests that are force traced if the `x-client-trace-id` header is set.
`sampling.random`	Required	100	The target percentage of requests that are randomly selected for trace generation, if not requested by the client or not forced.
`sampling.overall`	Required	100	The target percentage of requests that are traced after all other sampling checks have been applied, such as client-directed, force tracing, and random sampling.
`spanName`	Optional	N/A	The name of the span. If no span name is configured, the API name is used.
`labels`	Optional	Empty array	Array of labels that are added to the trace to be used as span attributes in the trace data.
`labels.name`	Required	N/A	The name of the label, used as a span attribute name.
`labels.type`	Required	N/A	The type of the label specifies where the value for the label is taken from. Supported values are `literal`, `environment`, and `requestHeader`.
`labels.keyName`	Required	N/A	The key name of the label.
`labels.defaultValue`	Required	N/A	The default value of the label.

sampling.client

Required

100

The target percentage of requests that are force traced if the x-client-trace-id header is set.

sampling.random

Required

100

The target percentage of requests that are randomly selected for trace generation, if not requested by the client or not forced.

sampling.overall

Required

100

The target percentage of requests that are traced after all other sampling checks have been applied, such as client-directed, force tracing, and random sampling.

spanName

Optional

N/A

The name of the span. If no span name is configured, the API name is used.

labels

Optional

Empty array

Array of labels that are added to the trace to be used as span attributes in the trace data.

labels.name

Required

N/A

The name of the label, used as a span attribute name.

labels.type

Required

N/A

The type of the label specifies where the value for the label is taken from. Supported values are literal, environment, and requestHeader.

labels.keyName

Required

N/A

The key name of the label.

labels.defaultValue

Required

N/A

The default value of the label.

Resource Configuration Example

- policyRef:
    name: tracing-flex
  config:
    sampling:
      client: 100
      random: 100
      overall: 100
    spanName: flightsAPI
    labels:
      - name: c-env-tag
        type: environment
        keyName: FLEX_NAME
        defaultValue: DEFAULT_VAL
      - name: c-header-tag
        type: requestHeader
        keyName: :method
        defaultValue: DEFAULT_METHOD
      - name: c-literal-tag
        type: literal
        defaultValue: the-tag

Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy to your API instance from the UI, the following parameters are displayed:

Element Description Required

Element	Description	Required
Client Sampling	The target percentage of requests that are force traced if the `x-client-trace-id` header is set.	Yes
Random Sampling	The target percentage of requests that are randomly selected for trace generation, if not requested by the client or not forced.	Yes
Overall Sampling	The target percentage of requests that are traced after all other sampling checks have been applied, such as client-directed, force tracing, and random sampling.	Yes
Span name	The name of the span. If no span name is configured, the API name is used.	No
Labels	Array of labels that are added to the trace to be used as span attributes in the trace data.	Optional
Label Name	The name of the label, used as a span attribute name.	Yes
Label Type	The type of the label specifies where the value for the label is taken from. Supported values are `literal`, `environment`, and `requestHeader`.	Yes
Label Key Name	The key used to retrieve the value, such as an environment variable or request header name.	Yes
Label Default Value	Default value to use if the key is not found or the retrieved value is empty.	Yes

Client Sampling

The target percentage of requests that are force traced if the x-client-trace-id header is set.

Yes

Random Sampling

The target percentage of requests that are randomly selected for trace generation, if not requested by the client or not forced.

Yes

Overall Sampling

The target percentage of requests that are traced after all other sampling checks have been applied, such as client-directed, force tracing, and random sampling.

Yes

Span name

The name of the span. If no span name is configured, the API name is used.

Labels

Array of labels that are added to the trace to be used as span attributes in the trace data.

Optional

Label Name

The name of the label, used as a span attribute name.

Yes

Label Type

The type of the label specifies where the value for the label is taken from. Supported values are literal, environment, and requestHeader.

Yes

Label Key Name

The key used to retrieve the value, such as an environment variable or request header name.

Yes

Label Default Value

Default value to use if the key is not found or the retrieved value is empty.

Yes