Add event_file target troubleshooting

Author: dimitri-furman

azure-sql/database/xevent-code-event-file.md

@@ -5,7 +5,7 @@ description: Provides example steps to create an event session in Azure SQL, usi
 author: WilliamDAssafMSFT
 ms.author: wiassaf
 ms.reviewer: wiassaf, mathoma, randolphwest
-ms.date: 10/21/2024
+ms.date: 07/09/2025
 ms.service: azure-sql
 ms.subservice: performance
 ms.topic: sample
@@ -23,20 +23,21 @@ The high-level steps in this walkthrough are:
 1. Create an Azure Storage account, or find an existing suitable account to use.
 1. Create a container in this storage account.
 1. Grant the [!INCLUDE [ssde-md](../../docs/includes/ssde-md.md)] required access to the container using either an RBAC role assignment, or a SAS token.
-1. Create a credential in the database or managed instance where you create the event session.
+1. Create a credential in the database or SQL managed instance where you create the event session.
 1. Create, start, and use an event session.
 
 ## Create a storage account and container
 
 For a detailed description of how to create a storage account in Azure Storage, see [Create a storage account](/azure/storage/common/storage-account-create). You learn how to create a storage account using Azure portal, PowerShell, Azure SQL, an ARM template, or a Bicep template.
 
-We recommended you use an account that:
+Use an account that:
 
 - Is a `Standard general-purpose v2` account.
 - Has its redundancy type matching the redundancy of the Azure SQL database, elastic pool, or managed instance where event sessions are created.
   - For [locally redundant](high-availability-sla-local-zone-redundancy.md#locally-redundant-availability) Azure SQL resources, use LRS, GRS, or RA-GRS. For [zone-redundant](high-availability-sla-local-zone-redundancy.md#zone-redundant-availability) Azure SQL resources, use ZRS, GZRS, or RA-GZRS. For more information, see [Azure Storage redundancy](/azure/storage/common/storage-redundancy).
 - Uses the `Hot` [blob access tier](/azure/storage/blobs/access-tiers-overview).
 - Is in the same Azure region as the Azure SQL database, elastic pool, or managed instance.
+- Doesn't have the [hierarchical namespace](/azure/storage/blobs/data-lake-storage-namespace) enabled.
 
 Next, [create a container](/azure/storage/blobs/blob-containers-portal#create-a-container) in this storage account using Azure portal. You can also create a container [using PowerShell](/azure/storage/blobs/blob-containers-powershell#create-a-container), or [using Azure CLI](/azure/storage/blobs/blob-containers-cli#create-a-container).
 
@@ -96,10 +97,10 @@ To read and write event data, the [!INCLUDE [ssde-md](../../docs/includes/ssde-m
 
     # [SQL Managed Instance](#tab/sqlmi)
 
-    Create a server-scoped [credential](/sql/relational-databases/security/authentication-access/credentials-database-engine). Using a client tool such as SSMS or ADS, open a new query window, connect it to the `master` database on the managed instance where you create the event session, and paste the following T-SQL batch.
+    Create a server-scoped [credential](/sql/relational-databases/security/authentication-access/credentials-database-engine). Using a client tool such as SSMS or ADS, open a new query window, connect it to the `master` database on the SQL managed instance where you create the event session, and paste the following T-SQL batch.
 
     > [!NOTE]
-    > Executing the following T-SQL batch requires the `CONTROL` database permission in the `master` database, which is held by the members of the `db_owner` database role in `master`, and by the members of the `sysadmin` server role on the managed instance.
+    > Executing the following T-SQL batch requires the `CONTROL` database permission in the `master` database, which is held by the members of the `db_owner` database role in `master`, and by the members of the `sysadmin` server role on the SQL managed instance.
 
     ```sql
     /*
@@ -188,10 +189,10 @@ To read and write event data, the [!INCLUDE [ssde-md](../../docs/includes/ssde-m
 
     # [SQL Managed Instance](#tab/sqlmi)
 
-    Store the SAS token in a server-scoped [credential](/sql/relational-databases/security/authentication-access/credentials-database-engine). Using a client tool such as SSMS or ADS, open a new query window, connect it to the `master` database on the managed instance where you create the event session, and paste the following T-SQL batch.
+    Store the SAS token in a server-scoped [credential](/sql/relational-databases/security/authentication-access/credentials-database-engine). Using a client tool such as SSMS or ADS, open a new query window, connect it to the `master` database on the SQL managed instance where you create the event session, and paste the following T-SQL batch.
 
     > [!NOTE]
-    > Executing the following T-SQL batch requires the `CONTROL` database permission in the `master` database, which is held by the members of the `db_owner` database role in `master`, and by the members of the `sysadmin` server role on the managed instance.
+    > Executing the following T-SQL batch requires the `CONTROL` database permission in the `master` database, which is held by the members of the `db_owner` database role in `master`, and by the members of the `sysadmin` server role on the SQL managed instance.
 
     ```sql
     /*
@@ -271,10 +272,30 @@ Select **OK** to create the session.
 
 In Object Explorer, expand the **Sessions** folder to see the event session you created. By default, the session isn't started when it's created. To start the session, right-click on the session name, and select **Start Session**. You can later stop it by similarly selecting **Stop Session**, once the session is running.
 
-As T-SQL batches are executed in this database or managed instance, the session writes events to the `example-session.xel` blob in the storage container.
+As T-SQL batches are executed in this database or SQL managed instance, the session writes events to the `example-session.xel` blob in the storage container.
 
 To stop the session, right-click it in Object Explorer, and select **Stop Session**.
 
+### Troubleshoot event sessions with an event_file target in Azure Storage
+
+The following list contains errors that you might encounter when starting an extended event session that uses Azure Storage, with the possible explanations for the error.
+
+- **The operating system returned error 5: 'Access is denied.'**
+    - If using managed identity authentication:
+        - The managed identity of a logical server or SQL managed instance doesn't have the required RBAC role assignment. For more information, see [Grant access using managed identity](#grant-access-using-managed-identity).
+        - The storage account [firewall](/azure/storage/common/storage-network-security) is enabled and an exception to allow trusted Azure services to access the storage account is also enabled, but a `Microsoft.Sql/servers` resource instance for the logical server hasn't been added to the list of resource instances that are granted access. For more information, see [Grant access from Azure resource instances](/azure/storage/common/storage-network-security#grant-access-from-azure-resource-instances).
+    - If using SAS token authentication:
+        - The storage account [firewall](/azure/storage/common/storage-network-security) is enabled. This is not supported for event sessions that use SAS token authentication.
+        - The SAS token doesn't have sufficient permissions, or has expired. For more information, see [Grant access using a SAS token](#grant-access-using-a-sas-token).
+- **The operating system returned error 86: 'The specified network password is not correct'**
+    - There is no database-scoped credential (for Azure SQL Database) or server-scoped credential (for Azure SQL Managed Instance) with the name matching the blob container URL. For more information, see the examples in [Grant access to the container](#grant-access-to-the-container).
+    - The credential name ends with a slash (`/`). The credential name should end with the container name not including the trailing slash.
+- **The operating system returned error 3: 'The system cannot find the path specified'**
+    - The container specified in the blob container URL doesn't exist.
+- **The operating system returned error 13: 'The data is invalid'**
+    - There is an [immutability policy](/azure/storage/blobs/immutable-policy-configure-container-scope) on the blob container. Immutable storage isn't supported for event sessions.
+    - The storage account has the [hierarchical namespace](/azure/storage/blobs/data-lake-storage-namespace) enabled. Storage accounts with hierarchical namespace enabled aren't supported for event sessions.
+
 ## View event data
 
 You can view event data in the SQL Server Management Studio (SSMS) event viewer UI, where you can use filters and aggregations to analyze the data you captured. For more information on using the event viewer in SSMS, see [View event data in SSMS](/sql/relational-databases/extended-events/advanced-viewing-of-target-data-from-extended-events-in-sql-server).

azure-sql/database/xevent-db-diff-from-svr.md

@@ -5,7 +5,7 @@ description: Describes extended events (XEvents) in Azure SQL Database and Azure
 author: WilliamDAssafMSFT
 ms.author: wiassaf
 ms.reviewer: wiassaf, mathoma, randolphwest
-ms.date: 10/21/2024
+ms.date: 07/09/2025
 ms.service: azure-sql
 ms.subservice: performance
 ms.topic: reference
@@ -36,7 +36,7 @@ The feature set, functionality, and usage scenarios for Extended Events in Azure
 
 There are two examples to help you get started with Extended Events in Azure SQL Database and Azure SQL Managed Instance quickly:
 
-- [Create a session with an event_file target in Azure Storage](xevent-code-event-file.md). This example shows you how to capture event data in a file (blob) in Azure Storage using the `event_file` target. Use this if you need to persist captured event data, or if you want to use event viewer in SQL Server Management Studio (SSMS) to analyze captured data.
+- [Create a session with an event_file target in Azure Storage](xevent-code-event-file.md). This example shows you how to capture event data in a file (blob) in Azure Storage using the `event_file` target, and includes [troubleshooting guidance](xevent-code-event-file.md#troubleshoot-event-sessions-with-an-event_file-target-in-azure-storage) for common errors. Use this if you need to persist captured event data, or if you want to use event viewer in SQL Server Management Studio (SSMS) to analyze captured data.
 - [Create a session with a ring_buffer target in memory](xevent-code-ring-buffer.md). This example shows you how to capture the latest events from an event session in memory using the `ring_buffer` target. Use this as a quick way to look at recent events during ad hoc investigations or troubleshooting, without having to store captured event data.
 
 Extended Events can be used to monitor read-only replicas. For more information, see [Read queries on replicas](read-scale-out.md#monitor-read-only-replicas-with-extended-events).
@@ -49,6 +49,7 @@ Adopt the following best practices to use Extended Events in Azure SQL Database
   - Use a storage account in the same Azure region as the database or managed instance where you create event sessions.
   - Align the redundancy of the storage account with the redundancy of the database, elastic pool, or managed instance. For [locally redundant](high-availability-sla-local-zone-redundancy.md#locally-redundant-availability) resources, use LRS, GRS, or RA-GRS. For [zone-redundant](high-availability-sla-local-zone-redundancy.md#zone-redundant-availability) resources, use ZRS, GZRS, or RA-GZRS. See [Azure Storage redundancy](/azure/storage/common/storage-redundancy) for details.
   - Don't use any [blob access tier](/azure/storage/blobs/access-tiers-overview) other than `Hot`.
+  - Don't enable the [hierarchical namespace](/azure/storage/blobs/data-lake-storage-namespace) for the storage account.
 - If you want to create a continuously running event session that starts automatically after each [!INCLUDE [ssde-md](../../docs/includes/ssde-md.md)] restart (for example, after a failover or a maintenance event), include the event session option of `STARTUP_STATE = ON` in your `CREATE EVENT SESSION`  or `ALTER EVENT SESSION` statements.
 - Conversely, use `STARTUP_STATE = OFF` for short-term event sessions such as those used in ad hoc troubleshooting.
 - In Azure SQL Database, do not read deadlock events from the built-in `dl` event session. If there is a large number of deadlock events collected, reading them with the [sys.fn_xe_file_target_read_file()](/sql/relational-databases/system-functions/sys-fn-xe-file-target-read-file-transact-sql) function can cause an out-of-memory error in the `master` database. This might impact login processing and result in an application outage. For the recommended ways to monitor deadlocks, see [Collect deadlock graphs in Azure SQL Database with Extended Events](analyze-prevent-deadlocks.md#collect-deadlock-graphs-in-azure-sql-database-with-extended-events).