Trace

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.
  • 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.

Important

  • API Management request tracing can no longer be enabled by setting the Ocp-Apim-Trace header in a request and using the value of the Ocp-Apim-Trace-Location header in the response to retrieve the trace.
  • To improve security, tracing is now enabled at the level of an individual API by obtaining a time-limited token using the API Management REST API, and passing the token in a request to the gateway. For details, see later in this tutorial.
  • Take care when enabling tracing, as it can expose sensitive information in the trace data. Ensure that you have appropriate security measures in place to protect the trace data.

Note

Currently, tracing of API requests 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>

For more information about working with policies, see: