Changes related to the new trace policy

Author: Miao Jiang

articles/api-management/api-management-advanced-policies.md

@@ -34,7 +34,7 @@ This topic provides a reference for the following API Management policies. For i
 -   [Set request method](#SetRequestMethod) - Allows you to change the HTTP method for a request.
 -   [Set status code](#SetStatus) - Changes the HTTP status code to the specified value.
 -   [Set variable](api-management-advanced-policies.md#set-variable) - Persists a value in a named [context](api-management-policy-expressions.md#ContextVariables) variable for later access.
--   [Trace](#Trace) - Adds a string into the [API Inspector](https://azure.microsoft.com/documentation/articles/api-management-howto-api-inspector/) output.
+-   [Trace](#Trace) - Adds custom traces into the [API Inspector](https://azure.microsoft.com/documentation/articles/api-management-howto-api-inspector/) output, Application Insights telemetries, and Diagnostic Logs.
 -   [Wait](#Wait) - Waits for enclosed [Send request](api-management-advanced-policies.md#SendRequest), [Get value from cache](api-management-caching-policies.md#GetFromCacheByKey), or [Control flow](api-management-advanced-policies.md#choose) policies to complete before proceeding.
 
 ## <a name="choose"></a> Control flow
@@ -909,29 +909,49 @@ Expressions used in the `set-variable` policy must return one of the following b
 
 ## <a name="Trace"></a> Trace
 
-The `trace` policy adds a string into the [API Inspector](https://azure.microsoft.com/documentation/articles/api-management-howto-api-inspector/) output. The policy will execute only when tracing is triggered, i.e. `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 associated with the admin account.
+The `trace` policy adds a custom trace into the API Inspector output, Application Insights telemetries, and/or Diagnostic Logs. 
+
+* The policy adds a custom trace to the [API Inspector](https://azure.microsoft.com/documentation/articles/api-management-howto-api-inspector/) output when tracing is triggered, i.e. `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](https://docs.microsoft.com/azure/azure-monitor/app/data-model-trace-telemetry) telemetry in Application Insights, when [Application Insights integration](https://docs.microsoft.com/azure/api-management/api-management-howto-app-insights) is enabled and the `severity` level specified in the policy is at or higher than the `verbosity` level specified in the diagnostic setting. 
+* The policy adds a property in the log entry when [Diagnostic Logs](https://docs.microsoft.com/en-us/azure/api-management/api-management-howto-use-azure-monitor#diagnostic-logs) is enabled and the severity level specified in the policy is at or higher than the verbosity level specified in the diagnostic setting.  
+
 
 ### Policy statement
 
 ```xml
 
-<trace source="arbitrary string literal">
-    <!-- string expression or literal -->
+<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>
 
 ```
 
+### <a name="traceExample"></a> Example
+
+```xml
+<trace source="PetStore API" severity="verbose">
+    <message>@((string)context.Variables["clientConnectionID"])</message>
+    <metadata name="Operation Name" value="New-Order"/>
+</trace>
+```
+
 ### Elements
 
 | Element | Description   | Required |
 | ------- | ------------- | -------- |
 | trace   | Root element. | Yes      |
+| message | A string or expression to be logged. | Yes |
+| metadata | Adds a custom property to the Application Insights [Trace](https://docs.microsoft.com/en-us/azure/azure-monitor/app/data-model-trace-telemetry) telemetry. | No |
 
 ### Attributes
 
 | Attribute | Description                                                                             | Required | Default |
 | --------- | --------------------------------------------------------------------------------------- | -------- | ------- |
 | source    | String literal meaningful to the trace viewer and specifying the source of the message. | Yes      | N/A     |
+| severity    | Specifies the severity level of the trace. Allowed values are `verbose`, `information`, `error` (from lowest to highest). | No      | Verbose     |
+| name    | Name of the property. | Yes      | N/A     |
+| value    | Value of the property. | Yes      | N/A     |
 
 ### Usage
 

articles/api-management/api-management-howto-app-insights.md

@@ -75,7 +75,8 @@ Before you can use Azure Application Insights, you first need to create an insta
 | Sampling (%)                        | decimal                           | Values from 0 to 100 (percent). <br/> Specifies what percentage of requests will be logged to Azure Application Insights. 0% sampling means zero requests logged, while 100% sampling means all requests logged. <br/> This setting is used for reducing performance implications of logging requests to Azure Application Insights (see the section below). |
 | Always log errors                   | boolean                           | If this setting is selected, all failures will be logged to Azure Application Insights, regardless of the **Sampling** setting.                                                                                                                                                                                                                  |
 | Basic Options: Headers              | list                              | Specifies the headers that will be logged to Azure Application Insights for requests and responses.  Default: no headers are logged.                                                                                                                                                                                                             |
-| Basic Options: First bytes of body  | integer                           | Specifies how many first bytes of the body are logged to Azure Application Insights for requests and responses.  Default: body is not logged.                                                                                                                                                                                              |
+| Basic Options: First bytes of body  | integer                           | Specifies how many first bytes of the body are logged to Azure Application Insights for requests and responses.  Default: body is not logged.                                                                                                                                                                                                    |
+| Advanced Options: Verbosity         |                                   | Specifies the verbosity level. Only custom traces with higher severity level will be logged. Default: Information.                                                                                                                                                                                                                               |
 | Advanced Options: Frontend Request  |                                   | Specifies whether and how *frontend requests* will be logged to Azure Application Insights. *Frontend request* is a request incoming to the Azure API Management service.                                                                                                                                                                        |
 | Advanced Options: Frontend Response |                                   | Specifies whether and how *frontend responses* will be logged to Azure Application Insights. *Frontend response* is a response outgoing from the Azure API Management service.                                                                                                                                                                   |
 | Advanced Options: Backend Request   |                                   | Specifies whether and how *backend requests* will be logged to Azure Application Insights. *Backend request* is a request outgoing from the Azure API Management service.                                                                                                                                                                        |

articles/api-management/api-management-policies.md

@@ -45,7 +45,7 @@ This section provides a reference for the following API Management policies. For
     -   [Set variable](api-management-advanced-policies.md#set-variable) - Persist a value in a named context variable for later access.  
     -   [Set request method](api-management-advanced-policies.md#SetRequestMethod) - Allows you to change the HTTP method for a request.  
     -   [Set status code](api-management-advanced-policies.md#SetStatus) - Changes the HTTP status code to the specified value.  
-    -   [Trace](api-management-advanced-policies.md#Trace) - Adds a string into the [API Inspector](https://azure.microsoft.com/documentation/articles/api-management-howto-api-inspector/) output.  
+    -   [Trace](api-management-advanced-policies.md#Trace) - Adds custom traces into the [API Inspector](https://azure.microsoft.com/documentation/articles/api-management-howto-api-inspector/) output, Application Insights telemetries, and Diagnostic Logs.  
     -   [Wait](api-management-advanced-policies.md#Wait) - Waits for enclosed [Send request](api-management-advanced-policies.md#SendRequest), [Get value from cache](api-management-caching-policies.md#GetFromCacheByKey), or [Control flow](api-management-advanced-policies.md#choose) policies to complete before proceeding.  
 -   [Authentication policies](api-management-authentication-policies.md#AuthenticationPolicies)  
     -   [Authenticate with Basic](api-management-authentication-policies.md#Basic) - Authenticate with a backend service using Basic authentication.