Merge pull request #218209 from dominicbetts/central-export-audit

IoT Central: add audit logs to data export

Author: PMEds28

articles/iot-central/core/howto-export-to-azure-data-explorer.md

@@ -194,6 +194,8 @@ To create the Azure Data Explorer destination in IoT Central on the **Data expor
 
 [!INCLUDE [iot-central-data-export-device-template](../../../includes/iot-central-data-export-device-template.md)]
 
+[!INCLUDE [iot-central-data-export-audit-logs](../../../includes/iot-central-data-export-audit-logs.md)]
+
 ## Next steps
 
 Now that you know how to export to Azure Data Explorer, a suggested next step is to learn [Export to Webhook](howto-export-to-webhook.md).

articles/iot-central/core/howto-export-to-blob-storage.md

@@ -266,6 +266,30 @@ The following example shows an exported device lifecycle message received in Azu
 }
 ```
 
+[!INCLUDE [iot-central-data-export-audit-logs](../../../includes/iot-central-data-export-audit-logs.md)]
+
+The following example shows an exported audit log message received in Azure Blob Storage:
+
+```json
+{
+  "actor": {
+    "id": "test-audit",
+    "type": "apiToken"
+    },
+  "applicationId": "570c2d7b-1111-2222-abcd-000000000000",
+  "enqueuedTime": "2022-07-25T21:54:40.000Z",
+  "enrichments": {},
+  "messageSource": "audit",
+  "messageType": "created",
+  "resource": {
+    "displayName": "Sensor 1",
+    "id": "sensor",
+    "type": "device"    
+  },
+  "schema": "default@v1"
+}
+```
+
 ## Next steps
 
 Now that you know how to export to Blob Storage, a suggested next step is to learn [Export to Service Bus](howto-export-to-service-bus.md).

articles/iot-central/core/howto-export-to-event-hubs.md

@@ -125,6 +125,8 @@ To create the Event Hubs destination in IoT Central on the **Data export** page:
 
 [!INCLUDE [iot-central-data-export-device-template](../../../includes/iot-central-data-export-device-template.md)]
 
+[!INCLUDE [iot-central-data-export-audit-logs](../../../includes/iot-central-data-export-audit-logs.md)]
+
 For Event Hubs, IoT Central exports new messages data to your event hub or Service Bus queue or topic in near real time. In the user properties (also referred to as application properties) of each message, the `iotcentral-device-id`, `iotcentral-application-id`, `iotcentral-message-source`, and `iotcentral-message-type` are included automatically.
 
 ## Next steps

articles/iot-central/core/howto-export-to-service-bus.md

@@ -129,6 +129,8 @@ To create the Service Bus destination in IoT Central on the **Data export** page
 
 [!INCLUDE [iot-central-data-export-device-template](../../../includes/iot-central-data-export-device-template.md)]
 
+[!INCLUDE [iot-central-data-export-audit-logs](../../../includes/iot-central-data-export-audit-logs.md)]
+
 For Service Bus, IoT Central exports new messages data to your event hub or Service Bus queue or topic in near real time. In the user properties (also referred to as application properties) of each message, the `iotcentral-device-id`, `iotcentral-application-id`, `iotcentral-message-source`, and `iotcentral-message-type` are included automatically.
 
 ## Next steps

articles/iot-central/core/howto-export-to-webhook.md

@@ -48,4 +48,6 @@ To create the Azure Data Explorer destination in IoT Central on the **Data expor
 
 [!INCLUDE [iot-central-data-export-device-lifecycle](../../../includes/iot-central-data-export-device-lifecycle.md)]
 
-[!INCLUDE [iot-central-data-export-device-template](../../../includes/iot-central-data-export-device-template.md)]
+[!INCLUDE [iot-central-data-export-device-template](../../../includes/iot-central-data-export-device-template.md)]
+
+[!INCLUDE [iot-central-data-export-audit-logs](../../../includes/iot-central-data-export-audit-logs.md)]

articles/iot-central/core/howto-use-audit-logs.md

@@ -19,6 +19,7 @@ This article describes how to use audit logs to track who made what changes at w
 - Filter the audit log.
 - Customize the audit log.
 - Manage access to the audit log.
+- Export the audit log records.
 
 The audit log records information about who made a change, information about the modified entity, the action that made change, and when the change was made. The log tracks changes made through the UI, programatically with the REST API, and through the CLI.
 
@@ -76,6 +77,12 @@ The built-in **App Administrator** role has access to the audit logs by default.
 > [!IMPORTANT]
 > Any user granted permission to view the audit log can see all log entries even if they don't have permission to view or modify the entities listed in the log. Therefore, any user who can view the log can view the identity of and changes made to any modified entity.
 
+## Export logs
+
+You can export the audit log records to various destinations for long-term storage, detailed analysis, or integration with other logs. For more information, see [Export IoT data](howto-export-to-event-hubs.md).
+
+To send audit logs to [Log Analytics in Azure Monitor](../../azure-monitor/logs/log-analytics-overview.md), use IoT Central data export to send the audit logs to Event Hubs, and then use an Azure Function to add the audit log data to Log Analytics.
+
 ## Next steps
 
 Now that you've learned how to manage users and roles in your IoT Central application, the suggested next step is to learn how to [Manage IoT Central organizations](howto-create-organizations.md).

includes/iot-central-data-export-audit-logs.md

@@ -0,0 +1,26 @@
+---
+ title: include file
+ description: include file
+ services: iot-central
+ author: dominicbetts
+ ms.service: iot-central
+ ms.topic: include
+ ms.date: 11/14/2022
+ ms.author: dobett
+ ms.custom: include file
+---
+
+### Audit log format
+
+Each audit log message represents a user-initiated change to an auditable entity inside the IoT Central application. Information in the exported message includes:
+
+- `actor`: Information about the user who modified the entity.
+- `applicationId`: The ID of the IoT Central application.
+- `messageSource`: The source for the message - `audit`.
+- `messageType`: The type of change that occurred. One of: `updated`, `created`, `deleted`.
+- `updated`: Only present if `messageType` is `updated`. Provides more detail about the update.
+- `resource`: Details of the modified entity.
+- `schema`: The name and version of the payload schema.
+- `deviceId`:  The ID of the device that was changed.
+- `enqueuedTime`: The time at which this change occurred in IoT Central.
+- `enrichments`: Any enrichments set up on the export.

includes/iot-central-data-export-setup.md

@@ -34,6 +34,7 @@ Now that you have a destination to export your data to, set up data export in yo
     | Device connectivity | Export device connected and disconnected events. | [Device connectivity message format](#device-connectivity-changes-format) |
     | Device lifecycle | Export device registered, deleted, provisioned, enabled, disabled, displayNameChanged, and deviceTemplateChanged events. | [Device lifecycle changes message format](#device-lifecycle-changes-format) |
     | Device template lifecycle | Export published device template changes including created, updated, and deleted. | [Device template lifecycle changes message format](#device-template-lifecycle-changes-format) |
+    | Audit logs | Logs of user-initiated updates to entities in the application. To learn more, see [Use audit logs to track activity in your IoT Central application](../articles/iot-central/core/howto-use-audit-logs.md) | [Audit log message format](#audit-log-format) |
 
 1. Optionally, add filters to reduce the amount of data exported. There are different types of filter available for each data export type:
     <a name="DataExportFilters"></a>
@@ -45,6 +46,7 @@ Now that you have a destination to export your data to, set up data export in yo
     |Device connectivity|<ul><li>Filter by device name, device ID, device template, organizations, and if the device is simulated</li><li>Filter stream to only contain changes from devices with properties matching the filter conditions</li></ul>|
     |Device lifecycle|<ul><li>Filter by device name, device ID, device template, and if the device is provisioned, enabled, or simulated</li><li>Filter stream to only contain changes from devices with properties matching the filter conditions</li></ul>|
     |Device template lifecycle|<ul><li>Filter by device template</li></ul>|
+    |Audit logs|N/A|
 
 1. Optionally, enrich exported messages with extra key-value pair metadata. The following enrichments are available for the telemetry, property changes, device connectivity, and device lifecycle data export types:
 <a name="DataExportEnrichmnents"></a>

includes/iot-central-data-export.md

@@ -2,26 +2,26 @@
  title: include file
  description: include file
  services: iot-central
- author: v-krishnag
+ author: dominicbetts
  ms.service: iot-central
  ms.topic: include
- ms.date: 04/27/2022
- ms.author: v-krishnag
+ ms.date: 11/14/2022
+ ms.author: dobett
  ms.custom: include file
 ---
 
 Use this feature to continuously export filtered and enriched IoT data from your IoT Central application. Data export pushes changes in near real time to other parts of your cloud solution for warm-path insights, analytics, and storage.
 
 For example, you can:
 
-- Continuously export telemetry, property changes, device connectivity, device lifecycle, and device template lifecycle data in JSON format in near real time.
+- Continuously export telemetry, property changes, device connectivity, device lifecycle, device template lifecycle, and audit log data in JSON format in near real time.
 - Filter the data streams to export data that matches custom conditions.
 - Enrich the data streams with custom values and property values from the device.
 - [Transform the data](../articles/iot-central/core/howto-transform-data-internally.md) streams to modify their shape and content.
 
-> [!Tip]
+> [!TIP]
 > When you turn on data export, you get only the data from that moment onward. Currently, data can't be retrieved for a time when data export was off. To retain more historical data, turn on data export early.
 
 ## Prerequisites
 
-To use data export features, you must have the [Data export](../articles/iot-central/core/howto-manage-users-roles.md) permission.
+To use data export features, you must have the [Data export](../articles/iot-central/core/howto-manage-users-roles.md) permission.