Edit

Trace

  • Article

APPLIES TO: All API Management tiers

The trace policy adds a custom trace into the request tracing output in the test console, Application Insights telemetries, and/or resource logs.

  • The policy adds a custom trace to the request tracing output in the test console when tracing is triggered, that is, Ocp-Apim-Trace request header is present and set to true and Ocp-Apim-Subscription-Key request header is present and holds a valid key that allows tracing.
  • The policy creates a Trace telemetry in Application Insights, when Application Insights integration is enabled and the severity specified in the policy is equal to or greater than the verbosity specified in the diagnostic setting.
  • The policy adds a property in the log entry when resource logs are enabled and the severity level specified in the policy is at or higher than the verbosity level specified in the diagnostic setting.
  • The policy is not affected by Application Insights sampling. All invocations of the policy will be logged.

Warning

  • Only allow tracing on subscriptions intended for debugging purposes. Sharing subscription keys with tracing allowed with unauthorized users could lead to disclosure of sensitive information contained in tracing logs such as keys, access tokens, passwords, internal hostnames, and IP addresses.
  • In the test console, API Management automatically disables tracing 1 hour after it's enabled on a subscription.

Note

Currently, API request tracing isn't supported in the Basic v2 and Standard v2 tiers.

Note

Set the policy's elements and child elements in the order provided in the policy statement. Learn more about how to set or edit API Management policies.

Policy statement

<trace source="arbitrary string literal" severity="verbose | information | error">
    <message>String literal or expressions</message>
    <metadata name="string literal or expressions" value="string literal or expressions"/>
</trace>

Attributes

Attribute Description Required Default
source String literal meaningful to the trace viewer and specifying the source of the message. Policy expressions aren't allowed. Yes N/A
severity Specifies the severity level of the trace. Allowed values are verbose, information, error (from lowest to highest). Policy expressions aren't allowed. No verbose

Elements

Name Description Required
message A string or expression to be logged. Policy expressions are allowed. Yes
metadata Adds a custom property to the Application Insights Trace telemetry. No

metadata attributes

Attribute Description Required Default
name Name of the property. Yes N/A
value Value of the property. Yes N/A

Usage

Example

<trace source="PetStore API" severity="verbose">
    <message>@((string)context.Variables["clientConnectionID"])</message>
    <metadata name="Operation Name" value="New-Order"/>
</trace>

Related content

For more information about working with policies, see: