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.
  • 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 no longer supports subscriptions for tracing or the Ocp-Apim-Trace header.
  • To improve API security, tracing can now be 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 Enable tracing of an API.
  • 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

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: