You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Extended Events provides a table valued function (TVF) for internal use by the Extended Events user interface (UI). The table does not provide customer usable data.
25
-
26
-
To view event data, use one of the following:
27
-
28
-
- Extended Events New Session UI.
29
-
30
-
- fn_xe_file_target_read_file TVF. For more information, see [sys.fn_xe_file_target_read_file (Transact-SQL)](../../relational-databases/system-functions/sys-fn-xe-file-target-read-file-transact-sql.md).
[!INCLUDE [SQL Server SQL Database SQL Managed Instance](../../includes/applies-to-version/sql-asdb-asdbmi.md)]
26
+
27
+
`sys.fn_MSxe_read_event_stream` returns binary data for internal use by the [QueryableXEventData](/dotnet/api/microsoft.sqlserver.xevent.linq.queryablexeventdata) .NET class. Extended Events UI in the [!INCLUDE [ssManStudioFull](../../includes/ssmanstudiofull-md.md)] (SSMS) uses this class to read event session data.
28
+
29
+
To view human-readable event data, use one of the following instead of calling `sys.fn_MSxe_read_event_stream` directly:
The specific source of event data returned by the function. *Source* is **nvarchar(260)** with no default.
47
+
48
+
*Source* is interpreted differently depending on the value of *source_option*:
49
+
50
+
|*source_option*| Interpretation of *source*|
51
+
| --- | --- |
52
+
|`0`|*Source* is the name of a started event session. |
53
+
|`1`|*Source* is the path to the event session log files to read.<br /><br />When used with files in the local file system, *source* must include the name of an event session log file and can contain `*` as a wildcard.<br /><br />When used with blobs in an Azure Storage container, *source* is an HTTP URL constructed by the concatenation of two parts:<br /><br />1. The path to an Azure Storage storage container, followed by a slash (`/`).<br />2. A common prefix for the names of blobs in the container that should be read.<br /><br />For example, using `https://<storage-account-name>.blob.core.windows.net/container-name>/xe_session` as *source* retrieves data from all blobs with names starting with `xe_session`, and regardless of the remainder of the blob name including the extension. Wildcards can't be specified. A credential allowing access to the Azure Storage container must exist. |
54
+
55
+
#### *source_option*
56
+
57
+
The option that determines the type of the event data source. Possible values are:
58
+
59
+
| Value | Description |
60
+
| --- | --- |
61
+
|`0`| Returns event data from the [event_stream](../extended-events/targets-for-extended-events-in-sql-server.md#event_stream-target) target of a started event session. The function executes indefinitely, returning new event data as the session produces it. |
62
+
|`1`| Returns event data from the extended event log files specified by *source*. |
63
+
64
+
## Table returned
65
+
66
+
| Column name | Data type | Description |
67
+
| --- | --- | --- |
68
+
| type |**int**| The event type. Not nullable. |
69
+
| data |**image**| Binary event data. Is nullable. |
[!INCLUDE [SQL Server SQL Database SQL Managed Instance](../../includes/applies-to-version/sql-asdb-asdbmi.md)]
26
28
27
-
Reads files created by the Extended Events asynchronous file target. One event, in XML format, is returned per row.
29
+
Reads the event log XEL files created by the Extended Events `event_file`target. Each row in the result set represents an event. Event data is returned in XML format.
28
30
29
-
The Extended Events `event_file` target stores the data it receives in a binary format that isn't human readable. Read the contents of the `.xel` file with the `sys.fn_xe_file_target_read_file` function. These files can also be read from[!INCLUDE [ssManStudio](../../includes/ssmanstudio-md.md)]. For a walkthrough, see [Quickstart: Extended Events](../extended-events/quick-start-extended-events-in-sql-server.md).
31
+
XEL files can also be read by[!INCLUDE [ssManStudioFull](../../includes/ssmanstudiofull-md.md)]. For a walkthrough, see [Quickstart: Extended Events](../extended-events/quick-start-extended-events-in-sql-server.md).
The path to the files to read. *path* can contain wildcards and include the name of a file. *path* is **nvarchar(260)** with no default. In the context of Azure SQL Database, this value is an HTTP URL to a file in Azure Storage.
45
+
The path to the files to read. *path* is **nvarchar(260)** with no default.
46
+
47
+
- When used with files in the local file system, *path* must include the name of an event session log file. The file name can contain `*` as a wildcard to read data from multiple files.
48
+
49
+
- When used with blobs in an Azure Storage container, *path* is an HTTP URL constructed by the concatenation of two parts:
50
+
51
+
1. The path to an Azure Storage storage container, followed by a slash (`/`).
52
+
53
+
1. A common prefix for the names of blobs in the container that should be read. To read a single blob, use the full name of the blob.
54
+
55
+
For example, using `https://<storage-account-name>.blob.core.windows.net/container-name>/xe_session` as *path* retrieves data from all blobs with names starting with `xe_session`, and regardless of the remainder of the blob name including the extension. Wildcards can't be specified.
44
56
45
57
#### *mdpath*
46
58
47
59
The path to the metadata file that corresponds to the file or files specified by the *path* argument. *mdpath* is **nvarchar(260)** with no default.
48
60
49
-
In [!INCLUDE [sssql11-md](../../includes/sssql11-md.md)] and later versions, you don't need this parameter. It was retained for backward compatibility, for log files generated in previous versions of SQL Server. In [!INCLUDE [sssql16-md](../../includes/sssql16-md.md)] and later versions, this parameter can be given as `NULL`, as `.xem` files are no longer used.
61
+
In [!INCLUDE [sssql11-md](../../includes/sssql11-md.md)] and later versions, you don't need this parameter. It's retained for backward compatibility, for log files generated in previous versions of SQL Server. In [!INCLUDE [sssql16-md](../../includes/sssql16-md.md)] and later versions, this parameter can be given as `NULL`, as `.xem` files are no longer used.
50
62
51
63
#### *initial_file_name*
52
64
53
65
The first file to read from *path*. *initial_file_name* is **nvarchar(260)** with no default. If `NULL` is specified as the argument, all the files found in *path* are read.
54
66
55
-
> [!NOTE]
56
-
> *initial_file_name* and *initial_offset* are paired arguments. If you specify a value for either argument, you must specify a value for the other argument.
67
+
The file name must be a value returned in the result set of a `sys.fn_xe_file_target_read_file` function call with the same *path*.
57
68
58
69
#### *initial_offset*
59
70
60
-
Used to specify last offset read previously and skips all events up to the offset (inclusive). Event enumeration starts after the offset specified. *initial_offset* is **bigint**. If `NULL` is specified as the argument, the entire file is read.
71
+
Used to specify last offset read previously. Skips all events up to the offset (inclusive). Event enumeration starts after the offset specified. *initial_offset* is **bigint**. If `NULL` is specified as the argument, the entire file is read.
72
+
73
+
> [!NOTE]
74
+
> *initial_file_name* and *initial_offset* are paired arguments. If you specify a value for either argument, you must specify a value for the other argument.
61
75
62
76
## Table returned
63
77
@@ -69,7 +83,7 @@ Used to specify last offset read previously and skips all events up to the offse
69
83
|`event_data`|**nvarchar(max)**| The event contents, in XML format. Not nullable. |
70
84
|`file_name`|**nvarchar(260)**| The name of the file that contains the event. Not nullable. |
71
85
|`file_offset`|**bigint**| The offset of the block in the file that contains the event. Not nullable. |
72
-
|`timestamp_utc`|**datetime2(7)**| The date and time (UTC timezone) of the event. Not nullable.<br /><br />**Applies to**: [!INCLUDE [sssql17](../../includes/sssql17-md.md)] and later versions, and [!INCLUDE [ssazure-sqldb](../../includes/ssazure-sqldb.md)]. |
86
+
|`timestamp_utc`|**datetime2(7)**| The date and time (UTC timezone) of the event. Not nullable.<br /><br />**Applies to**: [!INCLUDE [sssql17](../../includes/sssql17-md.md)] and later versions, [!INCLUDE [ssazure-sqldb](../../includes/ssazure-sqldb.md)], and [!INCLUDE [ssazuremi-md](../../includes/ssazuremi-md.md)]. |
73
87
74
88
## Remarks
75
89
@@ -79,9 +93,11 @@ Reading large result sets by executing `sys.fn_xe_file_target_read_file` in [!IN
79
93
80
94
### Azure SQL
81
95
82
-
In [!INCLUDE [ssazuremi-md](../../includes/ssazuremi-md.md)] or [!INCLUDE [ssazure-sqldb](../../includes/ssazure-sqldb.md)], store `.xel`files in Azure Blob Storage. You can use `sys.fn_xe_file_target_read_file` to read from extended event sessions you create yourself and store in Azure Blob Storage. For example walkthrough, review [Create an event session with an event_file target in Azure Storage](/azure/azure-sql/database/xevent-code-event-file).
96
+
In [!INCLUDE [ssazuremi-md](../../includes/ssazuremi-md.md)] or [!INCLUDE [ssazure-sqldb](../../includes/ssazure-sqldb.md)], the files created by the `event_file` target are always stored as blobs in an Azure Storage container.
83
97
84
-
If you specify wildcard and/or a path for a local file system, you receive an error message similar to:
98
+
You can use `sys.fn_xe_file_target_read_file` to read data from these blobs if a credential allowing access to the Azure Storage container exists. For a walkthrough, review [Create an event session with an event_file target in Azure Storage](/azure/azure-sql/database/xevent-code-event-file).
99
+
100
+
If you specify a local file system path, you receive an error message similar to:
85
101
86
102
```output
87
103
Msg 40538, Level 16, State 3, Line 15
@@ -96,7 +112,7 @@ In [!INCLUDE [sssql22-md](../../includes/sssql22-md.md)] and later versions, req
96
112
97
113
## Examples
98
114
99
-
### A. Retrieve data from file targets
115
+
### A. Retrieve data from files in the local file system
100
116
101
117
For [!INCLUDE [ssSQL14](../../includes/sssql14-md.md)] and previous versions, the following example gets all the rows from all the files, including both the `.xel` and `.xem` file. In this example, the file targets and metafiles are located in the trace folder in the `C:\traces\` folder.
102
118
@@ -117,7 +133,45 @@ In [!INCLUDE [sssql17](../../includes/sssql17-md.md)] and later versions, the fo
0 commit comments