Skip to content

Commit 7454c1d

Browse files
rwestMSFTrwestMSFT
committed
Refresh CREATE DIAGNOSTIC SESSION article
1 parent 79f5dd8 commit 7454c1d

1 file changed

Lines changed: 197 additions & 181 deletions

File tree

‎docs/t-sql/language-elements/create-diagnostics-session-transact-sql.md‎

Lines changed: 197 additions & 181 deletions
Original file line numberDiff line numberDiff line change
@@ -1,197 +1,213 @@
11
---
22
title: "CREATE DIAGNOSTICS SESSION (Transact-SQL)"
3-
description: "CREATE DIAGNOSTICS SESSION (Transact-SQL)"
3+
description: Create a diagnostics session to save detailed, user-defined diagnostic information on system or query performance.
44
author: WilliamDAssafMSFT
55
ms.author: wiassaf
6-
ms.date: "03/04/2017"
6+
ms.reviewer: randolphwest
7+
ms.date: 03/28/2025
78
ms.service: sql
89
ms.subservice: t-sql
910
ms.topic: reference
1011
dev_langs:
1112
- "TSQL"
12-
monikerRange: ">= aps-pdw-2016"
13+
monikerRange: ">=aps-pdw-2016"
1314
---
1415
# CREATE DIAGNOSTICS SESSION (Transact-SQL)
16+
1517
[!INCLUDE [pdw](../../includes/applies-to-version/pdw.md)]
1618

17-
Diagnostics sessions allow you to save detailed, user-defined diagnostic information on system or query performance.
18-
19-
Diagnostics sessions are typically used to debug performance for a specific query, or to monitor the behavior of a specific appliance component during appliance operation.
20-
19+
Diagnostics sessions allow you to save detailed, user-defined diagnostic information on system or query performance.
20+
21+
Diagnostics sessions are typically used to debug performance for a specific query, or to monitor the behavior of a specific appliance component during appliance operation.
22+
2123
> [!NOTE]
22-
> You should be familiar with XML in order to use diagnostics sessions.
23-
24-
## Syntax
25-
24+
> You should be familiar with XML in order to use diagnostics sessions.
25+
26+
## Syntax
27+
2628
```syntaxsql
27-
-- Creating a new diagnostics session:
28-
CREATE DIAGNOSTICS SESSION diagnostics_name AS N'{<session_xml>}';
29-
30-
<session_xml>::
31-
<Session>
32-
[ <MaxItemCount>max_item_count_num</MaxItemCount> ]
33-
<Filter>
34-
{ \<Event Name="event_name"/>
35-
[ <Where>\<filter_property_name Name="value" ComparisonType="comp_type"/></Where> ] [ ,...n ]
36-
} [ ,...n ]
37-
</Filter> ]
38-
<Capture>
39-
\<Property Name="property_name"/> [ ,...n ]
40-
</Capture>
41-
<Session>
42-
43-
-- Retrieving results for a diagnostics session:
44-
SELECT * FROM master.sysdiag.diagnostics_name ;
45-
46-
-- Removing results for a diagnostics session:
47-
DROP DIAGNOSTICS SESSION diagnostics_name ;
48-
```
49-
29+
-- Creating a new diagnostics session:
30+
CREATE DIAGNOSTICS SESSION diagnostics_name AS N' { <session_xml> } ';
31+
32+
<session_xml>::
33+
<Session>
34+
[ <MaxItemCount>max_item_count_num</MaxItemCount> ]
35+
[ <Filter>
36+
{ <Event Name = "event_name"/>
37+
[ <Where><filter_property_name Name = "value" ComparisonType = "comp_type"/></Where> ] [ , ...n ]
38+
} [ , ...n ]
39+
</Filter> ]
40+
<Capture>
41+
<Property Name = "property_name"/> [ , ...n ]
42+
</Capture>
43+
<Session>
44+
45+
-- Retrieving results for a diagnostics session:
46+
SELECT * FROM master.sysdiag.diagnostics_name ;
47+
48+
-- Removing results for a diagnostics session:
49+
DROP DIAGNOSTICS SESSION diagnostics_name ;
50+
```
51+
5052
## Arguments
51-
*diagnostics_name*
52-
The name of the diagnostics session. Diagnostics session names can include characters a-z, A-Z, and 0-9 only. Also, diagnostics session names must start with a character. *diagnostics_name* is limited to 127 characters.
53-
54-
*max_item_count_num*
55-
The number of events to be persisted in a view. For example, if 100 is specified, the 100 most recent events matching the filter criteria will be persisted to the diagnostics session. If fewer than 100 matching events are found, the diagnostics session will contain less than 100 events. *max_item_count_num* must be at least 100 and less than or equal to 100,000.
56-
57-
*event_name*
58-
Defines the actual events to be collected in the diagnostics session. *event_name* is one of the events listed in [sys.pdw_diag_events](../../relational-databases/system-catalog-views/sys-pdw-diag-events-transact-sql.md) where `sys.pdw_diag_events.is_enabled='True'`.
59-
60-
*filter_property_name*
61-
The name of the property on which to restrict results. For example, if you want to limit based on session id, *filter_property_name* should be *SessionId*. See *property_name* below for a list of potential values for *filter_property_name*.
62-
63-
*value*
64-
A value to evaluate against *filter_property_name*. The value type must match the property type. For example, if the property type is decimal, the type of *value* must be decimal.
65-
66-
*comp_type*
67-
The comparison type. Potential values are:Equals, EqualsOrGreaterThan, EqualsOrLessThan, GreaterThan, LessThan, NotEquals, Contains, RegEx
68-
69-
*property_name*
70-
A property related to the event. Property names can be part of the capture tag, or used as part of filtering criteria.
71-
72-
|Property Name|Description|
73-
|-------------------|-----------------|
74-
|UserName|A user (login) name.|
75-
|SessionId|A session ID.|
76-
|QueryId|A query ID.|
77-
|CommandType|A command type.|
78-
|CommandText|Text within a command processed.|
79-
|OperationType|The operation type for the event.|
80-
|Duration|The duration of the event.|
81-
|SPID|The Session ID.|
82-
83-
## Remarks
84-
Each user is allowed a maximum of 10 concurrent diagnostics sessions. See [sys.pdw_diag_sessions](../../relational-databases/system-catalog-views/sys-pdw-diag-sessions-transact-sql.md) for a list of your current sessions, and drop any unneeded sessions using `DROP DIAGNOSTICS SESSION`.
85-
86-
Diagnostics sessions will continue to collect metadata until dropped.
87-
88-
## Permissions
89-
Requires the **ALTER SERVER STATE** permission.
90-
91-
## Locking
92-
Takes a shared lock on the Diagnostic Sessions table.
93-
94-
## Examples
95-
96-
### A. Creating a diagnostics session
97-
This example creates a diagnostics session to record metrics of the database engine performance. The example creates a diagnostics session that listens for Engine Query running/end events and a blocking DMS event. What is returned is the command text, machine name, request id (query id) and the session that the event was created on.
98-
99-
```sql
100-
CREATE DIAGNOSTICS SESSION MYDIAGSESSION AS N'
101-
<Session>
102-
<MaxItemCount>100</MaxItemCount>
103-
<Filter>
104-
<Event Name="EngineInstrumentation:EngineQueryRunningEvent" />
105-
<Event Name="DmsCoreInstrumentation:DmsBlockingQueueEnqueueBeginEvent" />
106-
<Where>
107-
<SessionId Value="381" ComparisonType="NotEquals" />
108-
</Where>
109-
</Filter>
110-
<Capture>
111-
<Property Name="Query.CommandText" />
112-
<Property Name="MachineName" />
113-
<Property Name="Query.QueryId" />
114-
<Property Name="Alias" />
115-
<Property Name="Duration" />
116-
<Property Name="Session.SessionId" />
117-
</Capture>
118-
</Session>';
119-
```
120-
121-
After creation of the diagnostics session, run a query.
122-
123-
```sql
124-
SELECT COUNT(EmployeeKey) FROM AdventureWorksPDW2012..FactSalesQuota;
125-
```
126-
127-
Then view the diagnostics session results by selecting from the sysdiag schema.
128-
129-
```sql
130-
SELECT * FROM master.sysdiag.MYDIAGSESSION;
131-
```
132-
133-
Notice that the sysdiag schema contains a view that is named your diagnostics session name.
134-
135-
To see only the activity for your connection, add the `Session.SPID` property and add `WHERE [Session.SPID] = @@spid;` to the query.
136-
137-
When you are finished with the diagnostics session, drop it using the **DROP DIAGNOSTICS** command.
138-
139-
```sql
140-
DROP DIAGNOSTICS SESSION MYDIAGSESSION;
141-
```
142-
143-
### B. Alternative diagnostic session
144-
A second example with slightly different properties.
145-
146-
```sql
147-
-- Determine the session_id of your current session
148-
SELECT TOP 1 session_id();
149-
-- Replace \<*session_number*> in the code below with the numbers in your session_id
150-
CREATE DIAGNOSTICS SESSION PdwOptimizationDiagnostics AS N'
151-
<Session>
152-
<MaxItemCount>100</MaxItemCount>
153-
<Filter>
154-
<Event Name="EngineInstrumentation:MemoGenerationBeginEvent" />
155-
<Event Name="EngineInstrumentation:MemoGenerationEndEvent" />
156-
<Event Name="DSQLInstrumentation:OptimizationBeginEvent" />
157-
<Event Name="DSQLInstrumentation:OptimizationEndEvent" />
158-
<Event Name="DSQLInstrumentation:BuildRelOpContextTreeBeginEvent" />
159-
<Event Name="DSQLInstrumentation:PostPlanGenModifiersEndEvent" />
160-
<Where>
161-
<SessionId Value="\<*session_number*>" ComparisonType="Equals" />
162-
</Where>
163-
</Filter>
164-
<Capture>
165-
<Property Name="Session.SessionId" />
166-
<Property Name="Query.QueryId" />
167-
<Property Name="Query.CommandText" />
168-
<Property Name="Name" />
169-
<Property Name="DateTimePublished" />
170-
<Property Name="DateTimePublished.Ticks" />
171-
</Capture>
172-
</Session>';
173-
```
174-
175-
Run a query, such as:
176-
177-
```sql
178-
USE ssawPDW;
179-
GO
180-
SELECT * FROM dbo.FactFinance;
181-
```
182-
183-
The following query returns the authorization timing:
184-
185-
```sql
186-
SELECT *
187-
FROM master.sysdiag.PdwOptimizationDiagnostics
188-
ORDER BY DateTimePublished;
189-
```
190-
191-
When you are finished with the diagnostics session, drop it using the **DROP DIAGNOSTICS** command.
192-
193-
```sql
194-
DROP DIAGNOSTICS SESSION PdwOptimizationDiagnostics;
195-
```
196-
197-
53+
54+
#### *diagnostics_name*
55+
56+
The name of the diagnostics session. Diagnostics session names can include characters a-z, A-Z, and 0-9 only. Also, diagnostics session names must start with a character. *diagnostics_name* is limited to 127 characters.
57+
58+
#### *max_item_count_num*
59+
60+
The number of events to be persisted in a view. For example, if 100 is specified, the 100 most recent events matching the filter criteria is persisted to the diagnostics session. If fewer than 100 matching events are found, the diagnostics session contains fewer than 100 events. *max_item_count_num* must be at least 100 and less than or equal to 100,000.
61+
62+
#### *event_name*
63+
64+
Defines the actual events to be collected in the diagnostics session. *event_name* is one of the events listed in [sys.pdw_diag_events](../../relational-databases/system-catalog-views/sys-pdw-diag-events-transact-sql.md) where `sys.pdw_diag_events.is_enabled='True'`.
65+
66+
#### *filter_property_name*
67+
68+
The name of the property on which to restrict results. For example, if you want to limit based on session ID, *filter_property_name* should be *SessionId*. See the *property_name* argument for a list of potential values for *filter_property_name*.
69+
70+
#### *value*
71+
72+
A value to evaluate against *filter_property_name*. The value type must match the property type. For example, if the property type is decimal, the type of *value* must be decimal.
73+
74+
#### *comp_type*
75+
76+
The comparison type. Potential values are: `Equals`, `EqualsOrGreaterThan`, `EqualsOrLessThan`, `GreaterThan`, `LessThan`, `NotEquals`, `Contains`, and `RegEx`.
77+
78+
#### *property_name*
79+
80+
A property related to the event. Property names can be part of the capture tag, or used as part of filtering criteria.
81+
82+
| Property name | Description |
83+
| --- | --- |
84+
| `UserName` | A user (login) name. |
85+
| `SessionId` | A session ID. |
86+
| `QueryId` | A query ID. |
87+
| `CommandType` | A command type. |
88+
| `CommandText` | Text within a command processed. |
89+
| `OperationType` | The operation type for the event. |
90+
| `Duration` | The duration of the event. |
91+
| `SPID` | The session ID. |
92+
93+
## Remarks
94+
95+
Each user is allowed a maximum of 10 concurrent diagnostics sessions. See [sys.pdw_diag_sessions](../../relational-databases/system-catalog-views/sys-pdw-diag-sessions-transact-sql.md) for a list of your current sessions, and drop any unneeded sessions using `DROP DIAGNOSTICS SESSION`.
96+
97+
Diagnostics sessions continue to collect metadata until dropped.
98+
99+
## Permissions
100+
101+
Requires the `ALTER SERVER STATE` permission.
102+
103+
## Locking
104+
105+
Takes a shared lock on the Diagnostic Sessions table.
106+
107+
## Examples
108+
109+
### A. Create a diagnostics session
110+
111+
This example creates a diagnostics session to record metrics of the database engine performance. The example creates a diagnostics session that listens for Engine Query running/end events and a blocking DMS event. What is returned is the command text, machine name, request ID (query ID), and the session that the event was created on.
112+
113+
```sql
114+
CREATE DIAGNOSTICS SESSION MYDIAGSESSION AS N'
115+
<Session>
116+
<MaxItemCount>100</MaxItemCount>
117+
<Filter>
118+
<Event Name="EngineInstrumentation:EngineQueryRunningEvent" />
119+
<Event Name="DmsCoreInstrumentation:DmsBlockingQueueEnqueueBeginEvent" />
120+
<Where>
121+
<SessionId Value="381" ComparisonType="NotEquals" />
122+
</Where>
123+
</Filter>
124+
<Capture>
125+
<Property Name="Query.CommandText" />
126+
<Property Name="MachineName" />
127+
<Property Name="Query.QueryId" />
128+
<Property Name="Alias" />
129+
<Property Name="Duration" />
130+
<Property Name="Session.SessionId" />
131+
</Capture>
132+
</Session>';
133+
```
134+
135+
After creation of the diagnostics session, run a query.
136+
137+
```sql
138+
SELECT COUNT(EmployeeKey)
139+
FROM AdventureWorksPDW2012..FactSalesQuota;
140+
```
141+
142+
Then view the diagnostics session results by selecting from the sysdiag schema.
143+
144+
```sql
145+
SELECT * FROM master.sysdiag.MYDIAGSESSION;
146+
```
147+
148+
The sysdiag schema contains a view that is named your diagnostics session name.
149+
150+
To see only the activity for your connection, add the `Session.SPID` property and add `WHERE [Session.SPID] = @@spid;` to the query.
151+
152+
When you're finished with the diagnostics session, drop it using the `DROP DIAGNOSTICS` command.
153+
154+
```sql
155+
DROP DIAGNOSTICS SESSION MYDIAGSESSION;
156+
```
157+
158+
### B. Alternative diagnostic session
159+
160+
A second example with slightly different properties.
161+
162+
```sql
163+
-- Determine the session_id of your current session
164+
SELECT TOP 1 session_id();
165+
166+
-- Replace <session_number> in the code below with the numbers in your session_id
167+
CREATE DIAGNOSTICS SESSION PdwOptimizationDiagnostics AS N'
168+
<Session>
169+
<MaxItemCount>100</MaxItemCount>
170+
<Filter>
171+
<Event Name="EngineInstrumentation:MemoGenerationBeginEvent" />
172+
<Event Name="EngineInstrumentation:MemoGenerationEndEvent" />
173+
<Event Name="DSQLInstrumentation:OptimizationBeginEvent" />
174+
<Event Name="DSQLInstrumentation:OptimizationEndEvent" />
175+
<Event Name="DSQLInstrumentation:BuildRelOpContextTreeBeginEvent" />
176+
<Event Name="DSQLInstrumentation:PostPlanGenModifiersEndEvent" />
177+
<Where>
178+
<SessionId Value="<session_number>" ComparisonType="Equals" />
179+
</Where>
180+
</Filter>
181+
<Capture>
182+
<Property Name="Session.SessionId" />
183+
<Property Name="Query.QueryId" />
184+
<Property Name="Query.CommandText" />
185+
<Property Name="Name" />
186+
<Property Name="DateTimePublished" />
187+
<Property Name="DateTimePublished.Ticks" />
188+
</Capture>
189+
</Session>';
190+
```
191+
192+
Run a query, such as:
193+
194+
```sql
195+
USE ssawPDW;
196+
GO
197+
198+
SELECT * FROM dbo.FactFinance;
199+
```
200+
201+
The following query returns the authorization timing:
202+
203+
```sql
204+
SELECT *
205+
FROM master.sysdiag.PdwOptimizationDiagnostics
206+
ORDER BY DateTimePublished;
207+
```
208+
209+
When you're finished with the diagnostics session, drop it using the `DROP DIAGNOSTICS` command.
210+
211+
```sql
212+
DROP DIAGNOSTICS SESSION PdwOptimizationDiagnostics;
213+
```

0 commit comments

Comments
 (0)