Merge pull request #275093 from dlepow/dpaudit

[APIM] Developer portal audit logs

Author: denrea

articles/api-management/TOC.yml

@@ -393,6 +393,8 @@
       href: api-management-howto-oauth2.md
     - name: Integrate Application Insights
       href: developer-portal-integrate-application-insights.md
+    - name: Log developer portal usage
+      href: developer-portal-enable-usage-logs.md  
     - name: Integrate Google Tag Manager
       href: developer-portal-integrate-google-tag-manager.md
   - name: Self-host the developer portal
@@ -615,8 +617,10 @@
   - name: Azure Policy built-ins
     displayName: samples, policies, definitions
     href: ./policy-reference.md
-  - name: Resource log schema
+  - name: Gateway log schema
     href: gateway-log-schema-reference.md
+  - name: Developer portal audit log schema
+    href: developer-portal-audit-log-schema-reference.md
   - name: Event Grid events schema
     href: ../event-grid/event-schema-api-management.md?toc=/azure/api-management/toc.json&bc=/azure/api-management/breadcrumb/toc.json
   - name: Virtual network configuration

articles/api-management/developer-portal-audit-log-schema-reference.md

@@ -0,0 +1,57 @@
+---
+title: Reference - Azure API Management developer portal audit log
+description: Schema reference for the Azure API Management DeveloperPortalAuditLogs log. Entries include properties that are logged for requests to the developer portal. 
+services: api-management
+author: dlepow
+
+ms.service: api-management
+ms.custom: mvc
+ms.topic: reference
+ms.date: 05/14/2024
+ms.author: danlep
+---
+# Reference: Developer portal audit log schema
+
+[!INCLUDE [api-management-availability-premium-dev-standard-basic](../../includes/api-management-availability-premium-dev-standard-basic.md)]
+
+This article provides a schema reference for the Azure API Management DeveloperPortalAuditLogs resource log. 
+
+To enable collection of the resource log in API Management, see [Enable logging of developer portal usage](developer-portal-enable-usage-logs.md).
+
+## DeveloperPortalAuditLogs schema
+
+The following fields are logged for each request to the developer portal.
+
+| Field  | Type | Description |
+| ------------- | ------------- | ------------- |
+| Sku | string | Pricing tier |
+| DeploymentVersion | string | API Management code base version |
+| Level | int | Log level as number from 1 - 5.<br/><br/> `1 - 2`: errors<br/> `3`: warnings<br/> `4 - 5`: tracing logs|
+| resourceId | string | Azure Resource Manager resource identifier<br/><br/>Example: `/SUBSCRIPTIONS/MYSUBSCRIPTION/RESOURCEGROUPS/MYRESOURCEGROUP/PROVIDERS/MICROSOFT.APIMANAGEMENT/SERVICE/MYAPIMSERVICE`|
+| category | string | `DeveloperPortalAuditLogs`|
+| resultType | string | Result type, either `Succeeded` or `Failed`|
+| operationName | string | `Microsoft.ApiManagement/CustomerDevPortalAuditDiagnosticLogs` |
+| eventTime | string | Date and time in UTC of an event<br/><br/> Example: `2024-05-13T09:15:26.012166Z`|
+| apimClient | string | Value taken from `X-Ms-Apim-Client` HTTP header sent on each request by developer portal webpage. Each part is separated by `|` character. Contains information about service type, domain name, API used, and user authorization status<br/><br/>Example: `dev-portal|myapimservice123.developer.azure-api.net|getApis-unauthorized`|
+| activityId | string | Unique log GUID|
+| properties | dynamic \| object | Object representing additional log information|
+
+### Properties
+
+| Field name  | Type  | Description  | 
+| ------------- | ------------- | ------------- |
+| hashedUserId  | string \| null  | Hashed user ID or `null` if the request is anonymous  | 
+| timestamp  | string  | Date and time in UTC when the request was made<br/><br/> Example: `2024-05-13T09:15:26.4496706Z`  | 
+| requestPath  | string  | HTTP request URL path<br/><br/>Example: `/apis` or `/tags`  | 
+| requestMethod  | string  | HTTP request method  | 
+| userAgent  | string  | Browser's user agent string taken from HTTP request header. Identifies browser, browser version, and operating system.<br/><br/>Example: `Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36`  | 
+| responseCode  | int  | HTTP response code  | 
+| region  | string  | Azure region name<br/><br/>Example: `Brazil South`  | 
+| serviceName  | string  | Name of the API Management service   | 
+
+
+## Related content
+
+* [ApiManagementGatewayLogs schema reference](gateway-log-schema-reference.md)
+* Learn more about [Common and service-specific schema for Azure Resource Logs](../azure-monitor/essentials/resource-logs-schema.md)
+

articles/api-management/developer-portal-enable-usage-logs.md

@@ -0,0 +1,65 @@
+---
+title: Enable usage logs - Developer portal - Azure API Management
+description: Enable logs to monitor usage of the developer portal in Azure API Management. Usage data includes views of API and product details.
+services: api-management
+author: dlepow
+
+ms.service: api-management
+ms.custom: 
+ms.topic: how-to
+ms.date: 05/23/2024
+ms.author: danlep
+---
+
+# Enable logging of developer portal usage in Azure API Management
+
+[!INCLUDE [api-management-availability-premium-dev-standard-basic](../../includes/api-management-availability-premium-dev-standard-basic.md)]
+
+This article shows you how to enable Azure Monitor logs for auditing and troubleshooting usage of the API Management [developer portal](developer-portal-overview.md). When enabled through a diagnostic setting, the logs collect information about the requests that are received and processed by the developer portal.
+
+Developer portal usage logs include data about activity in the developer portal, including:
+
+* User authentication actions, such as sign-in and sign-out
+* Views of API details, API operation details, and products
+* API testing in the interactive test console 
+
+> [!NOTE]
+> Developer portal usage logs in API Management are currently in preview.
+
+## Enable diagnostic setting for developer portal logs
+
+To configure a diagnostic setting for developer portal usage logs:
+
+1. In the [Azure portal](https://portal.azure.com), navigate to your API Management instance.
+1. In the left menu, under **Monitoring**, select **Diagnostic settings** > **+ Add diagnostic setting**.
+
+    :::image type="content" source="media/developer-portal-enable-usage-logs/monitoring-menu.png" alt-text="Screenshot of adding a diagnostic setting in the portal.":::
+1. On the **Diagnostic setting** blade, enter or select details for the setting:
+    1. **Diagnostic setting name**: Enter a descriptive name.
+    1. **Category groups**: Optionally make a selection for your scenario. 
+    1. Under **Categories**: Select **Logs related to Developer Portal usage**. Optionally select other categories as needed.
+    1. Under **Destination details**, select one or more options and specify details for the destination. For example, archive logs to a storage account or stream them to an event hub. [Learn more](../azure-monitor/essentials/diagnostic-settings.md)
+        > [!NOTE]
+        > Currently, the **Send to Log Analytics workspace** destination isn't supported for developer portal usage logs.
+
+    1. Select **Save**. 
+ 
+## View diagnostic log data
+
+Depending on the log destination you choose, it can take a few minutes for data to appear. 
+
+If you send logs to a storage account, you can access the data in the Azure portal and download it for analysis.
+
+1. In the [Azure portal](https://portal.azure.com), navigate to the storage account destination.
+1. In the left menu, select **Storage Browser**.
+1. Under **Blob containers**, select **insights-logs-developerportalauditlogs**.
+1. Navigate to the container for the logs in your API Management instance. The logs are partitioned in intervals of 1 hour.
+1. To retrieve the data for further analysis, select **Download**.
+
+       
+## Related content
+
+* [Overview of log queries in Azure Monitor](../azure-monitor/logs/log-query-overview.md).
+
+* [Developer portal audit log schema reference](developer-portal-audit-log-schema-reference.md). 
+

articles/api-management/developer-portal-overview.md

@@ -259,6 +259,7 @@ Learn more about the developer portal:
 
 - [Access and customize the managed developer portal](api-management-howto-developer-portal-customize.md)
 - [Extend functionality of the managed developer portal](developer-portal-extend-custom-functionality.md)
+- [Enable logging of developer portal usage](developer-portal-enable-usage-logs.md)
 - [Set up self-hosted version of the portal](developer-portal-self-host.md)
 
 Browse other resources:

articles/api-management/gateway-log-schema-reference.md

@@ -1,16 +1,16 @@
 ---
-title: Reference - Azure API Management resource log
-description: Schema reference for the Azure API Management GatewayLogs resource log
+title: Reference - Azure API Management gateway log
+description: Schema reference for the Azure API Management GatewayLogs log. Entries include properties that are logged for each API request. 
 services: api-management
 author: dlepow
 
 ms.service: api-management
 ms.custom: mvc
 ms.topic: tutorial
-ms.date: 10/14/2020
+ms.date: 05/14/2024
 ms.author: danlep
 ---
-# Reference: API Management resource log schema
+# Reference: Gateway log schema
 
 [!INCLUDE [api-management-availability-all-tiers](../../includes/api-management-availability-all-tiers.md)]
 
@@ -70,4 +70,4 @@ The following properties are logged for each API request.
 
 * For information about monitoring APIs in API Management, see [Monitor published APIs](api-management-howto-use-azure-monitor.md)
 * Learn more about [Common and service-specific schema for Azure Resource Logs](../azure-monitor/essentials/resource-logs-schema.md)
-
+* [DeveloperPortalAuditLogs schema reference](developer-portal-audit-log-schema-reference.md)