مسئله‌ای که این دستور حل می‌کند

وقتی یک نشست Extended Events فقط در حد تعریف باقی نماند و قرار باشد در چرخه استقرار، عیب‌یابی و نگهداری استفاده شود، شناخت دقیق ADD EVENT ضروری است. این مقاله مسئله عملی «انتخاب درست Event تعیین می‌کند چه لحظه‌ای از موتور ثبت شود و چه Contextی در خروجی وجود داشته باشد.» را از دید SQL Server بررسی می‌کند و تفاوت Metadata با وضعیت Runtime را روشن نگه می‌دارد.

پیش‌نیاز مطالعه، آشنایی پایه با Event، Action، Predicate و Target است. در پایان می‌توانید Syntax را درست بنویسید، نتیجه را از Catalog یا DMV کنترل کنید، خطاهای رایج را پیش از اجرا تشخیص دهید و اثر Performance را متناسب با event-add بسنجید.

برای دیدن جایگاه این دستور در کل چرخه، راهنمای جامع دستورات Extended Events را نیز در دسترس داشته باشید؛ این صفحه روی جزئیات مستقل همین Topic تمرکز می‌کند.

دسترسی سریع

1. تعریف و جایگاه
2. نحو و اجزا
3. ده مثال عملی
4. کارایی و خطاها
5. پرسش‌های تکمیلی

تعریف و جایگاه فنی

ADD EVENT یک رویداد مشخص از Package را به تعریف نشست اضافه می‌کند و می‌تواند Actionها، Predicate و گزینه‌های جمع‌آوری همان رویداد را همراه داشته باشد.

انتخاب درست Event تعیین می‌کند چه لحظه‌ای از موتور ثبت شود و چه Contextی در خروجی وجود داشته باشد.

در معماری Extended Events، این Topic در گروه «event-add» قرار می‌گیرد. تصمیم درباره Scope، وضعیت Session و مقصد داده باید قبل از اجرا روشن باشد؛ زیرا موفقیت DDL لزوماً به معنی دریافت داده قابل استفاده نیست.

Syntax، پارامترها و رفتار خروجی

Syntax استاندارد

ALTER EVENT SESSION [SessionName]
ON SERVER
ADD EVENT sqlserver.sql_statement_completed
(
    ACTION(sqlserver.sql_text, sqlserver.session_id)
    WHERE (duration > 1000000)
);

پارامترها و اجزای اثرگذار

• نام Event به‌صورت package.event_name نوشته می‌شود.
• ACTION فیلدهای Context اختیاری را اضافه می‌کند.
• WHERE Predicate را قبل از ارسال به Target اعمال می‌کند.
• SET گزینه‌های اختصاصی Event را مقداردهی می‌کند.

Return Type، NULL و سازگاری

خروجی مستقیم ندارد؛ از اجرای بعدی نشست، نمونه‌های مطابق Event وارد Pipeline می‌شوند.

این یک دستور DDL یا عبارت کنترلی است و Return Type تابعی ندارد؛ بنابراین رفتار NULL فقط در Predicateها، SET valueها یا Queryهای کنترلی اطراف آن مطرح می‌شود. Scopeهای Server و Database، نام DMVها و دسترسی‌های لازم می‌توانند بین نسخه‌ها و سرویس‌های Azure تفاوت داشته باشند؛ قبل از انتقال اسکریپت، مستندات نسخه مقصد و sys.dm_xe_objects همان Instance را کنترل کنید.

منطق اجرا و نکات فنی

مثال‌های عملی از ساده تا پیشرفته

مثال 1: افزودن error_reported

سناریو: در این مرحله هدف، افزودن error_reported برای Session نمونه است. Query عمداً کامل نوشته شده تا بتوان آن را در محیط آزمایشی اجرا یا با نام واقعی جایگزین کرد.

ALTER EVENT SESSION [XE_Article_Demo] ON SERVER
ADD EVENT sqlserver.error_reported;
GO

این مثال روی جنبه «افزودن error_reported» تمرکز دارد. در محیط واقعی نام Session، مسیر فایل، Scope و سطح دسترسی را با استاندارد استقرار خود هماهنگ کنید.

مثال 2: افزودن Actionهای Context

سناریو: در این مرحله هدف، افزودن Actionهای Context برای Session نمونه است. Query عمداً کامل نوشته شده تا بتوان آن را در محیط آزمایشی اجرا یا با نام واقعی جایگزین کرد.

ALTER EVENT SESSION [XE_Article_Demo] ON SERVER
ADD EVENT sqlserver.error_reported
(ACTION(sqlserver.sql_text, sqlserver.session_id));
GO

این مثال روی جنبه «افزودن Actionهای Context» تمرکز دارد. در محیط واقعی نام Session، مسیر فایل، Scope و سطح دسترسی را با استاندارد استقرار خود هماهنگ کنید.

مثال 3: Predicate روی Severity

سناریو: در این مرحله هدف، Predicate روی Severity برای Session نمونه است. Query عمداً کامل نوشته شده تا بتوان آن را در محیط آزمایشی اجرا یا با نام واقعی جایگزین کرد.

ALTER EVENT SESSION [XE_Article_Demo] ON SERVER
ADD EVENT sqlserver.error_reported
(WHERE (severity >= 16));
GO

این مثال روی جنبه «Predicate روی Severity» تمرکز دارد. در محیط واقعی نام Session، مسیر فایل، Scope و سطح دسترسی را با استاندارد استقرار خود هماهنگ کنید.

مثال 4: ثبت RPCهای کند

سناریو: در این مرحله هدف، ثبت RPCهای کند برای Session نمونه است. Query عمداً کامل نوشته شده تا بتوان آن را در محیط آزمایشی اجرا یا با نام واقعی جایگزین کرد.

ALTER EVENT SESSION [XE_Article_Demo] ON SERVER
ADD EVENT sqlserver.rpc_completed
(
 ACTION(sqlserver.client_app_name, sqlserver.database_id)
 WHERE (duration > 1500000)
);
GO

این مثال روی جنبه «ثبت RPCهای کند» تمرکز دارد. در محیط واقعی نام Session، مسیر فایل، Scope و سطح دسترسی را با استاندارد استقرار خود هماهنگ کنید.

مثال 5: ثبت Deadlock XML

سناریو: در این مرحله هدف، ثبت Deadlock XML برای Session نمونه است. Query عمداً کامل نوشته شده تا بتوان آن را در محیط آزمایشی اجرا یا با نام واقعی جایگزین کرد.

ALTER EVENT SESSION [XE_Article_Demo] ON SERVER
ADD EVENT sqlserver.xml_deadlock_report;
GO

این مثال روی جنبه «ثبت Deadlock XML» تمرکز دارد. در محیط واقعی نام Session، مسیر فایل، Scope و سطح دسترسی را با استاندارد استقرار خود هماهنگ کنید.

مثال 6: کنترل وجود Event

سناریو: در این مرحله هدف، کنترل وجود Event برای Session نمونه است. Query عمداً کامل نوشته شده تا بتوان آن را در محیط آزمایشی اجرا یا با نام واقعی جایگزین کرد.

SELECT e.name, e.package, e.predicate
FROM sys.server_event_session_events AS e
JOIN sys.server_event_sessions AS s ON s.event_session_id=e.event_session_id
WHERE s.name=N'XE_Article_Demo';

این مثال روی جنبه «کنترل وجود Event» تمرکز دارد. در محیط واقعی نام Session، مسیر فایل، Scope و سطح دسترسی را با استاندارد استقرار خود هماهنگ کنید.

مثال 7: بررسی ستون‌های Event

سناریو: در این مرحله هدف، بررسی ستون‌های Event برای Session نمونه است. Query عمداً کامل نوشته شده تا بتوان آن را در محیط آزمایشی اجرا یا با نام واقعی جایگزین کرد.

SELECT c.name, c.column_type, c.type_name
FROM sys.dm_xe_object_columns AS c
WHERE c.object_name=N'error_reported'
ORDER BY c.column_type, c.name;

این مثال روی جنبه «بررسی ستون‌های Event» تمرکز دارد. در محیط واقعی نام Session، مسیر فایل، Scope و سطح دسترسی را با استاندارد استقرار خود هماهنگ کنید.

مثال 8: افزودن attention برای لغو Query

سناریو: در این مرحله هدف، افزودن attention برای لغو Query برای Session نمونه است. Query عمداً کامل نوشته شده تا بتوان آن را در محیط آزمایشی اجرا یا با نام واقعی جایگزین کرد.

ALTER EVENT SESSION [XE_Article_Demo] ON SERVER
ADD EVENT sqlserver.attention
(ACTION(sqlserver.client_app_name, sqlserver.sql_text));
GO

این مثال روی جنبه «افزودن attention برای لغو Query» تمرکز دارد. در محیط واقعی نام Session، مسیر فایل، Scope و سطح دسترسی را با استاندارد استقرار خود هماهنگ کنید.

مثال 9: روش اشتباه و اصلاح Predicate

سناریو: در این مرحله هدف، روش اشتباه و اصلاح Predicate برای Session نمونه است. Query عمداً کامل نوشته شده تا بتوان آن را در محیط آزمایشی اجرا یا با نام واقعی جایگزین کرد.

-- اشتباه: رویداد بسیار پرتکرار بدون فیلتر
-- ALTER EVENT SESSION [XE_Article_Demo] ON SERVER ADD EVENT sqlserver.sql_statement_starting;

ALTER EVENT SESSION [XE_Article_Demo] ON SERVER
ADD EVENT sqlserver.sql_statement_completed
(WHERE (duration > 1000000));
GO

این مثال روی جنبه «روش اشتباه و اصلاح Predicate» تمرکز دارد. در محیط واقعی نام Session، مسیر فایل، Scope و سطح دسترسی را با استاندارد استقرار خود هماهنگ کنید.

مثال 10: افزودن Event با توجه به Performance

سناریو: در این مرحله هدف، افزودن Event با توجه به Performance برای Session نمونه است. Query عمداً کامل نوشته شده تا بتوان آن را در محیط آزمایشی اجرا یا با نام واقعی جایگزین کرد.

ALTER EVENT SESSION [XE_Article_Demo] ON SERVER
ADD EVENT sqlserver.rpc_completed
(
 ACTION(sqlserver.database_id)
 WHERE (cpu_time > 500000 OR logical_reads > 10000)
);
GO

این مثال روی جنبه «افزودن Event با توجه به Performance» تمرکز دارد. در محیط واقعی نام Session، مسیر فایل، Scope و سطح دسترسی را با استاندارد استقرار خود هماهنگ کنید.

کاربردهای واقعی در پروژه

افزودن rpc_completed برای تفکیک RPCها، error_reported برای خطاهای مهم یا deadlock_graph برای تحلیل Deadlock.

در پروژه سازمانی بهتر است اجرای ADD EVENT بخشی از Runbook باشد: مالک Session، زمان شروع و پایان، مسیر داده، سقف نگهداری و Query کنترل بعد از اجرا ثبت شود. این ساختار به تیم DBA و توسعه اجازه می‌دهد تغییر را از یک اقدام دستی به فرآیند قابل حسابرسی تبدیل کنند.

برای محیط‌های پرترافیک، ابتدا نشست را در بار مشابه Production آزمایش کنید. مقدار Event تولیدشده، حجم فایل، رخدادهای Drop و زمان Parse باید با هدف مانیتورینگ مقایسه شوند؛ تنها مشاهده چند Event موفق معیار کافی نیست.

هشدار مهم

افزودن Event بدون شناخت Frequency یا بدون Predicate می‌تواند نشست کم‌هزینه را به منبع فشار تبدیل کند.

دستور را ابتدا در محیط آزمایشی اجرا کنید و برای نشست‌های امنیتی، Audit یا system_health از تغییر بدون تأیید مالک سرویس پرهیز کنید.

اشتباهات رایج و روش اصلاح

• اجرای ADD EVENT با Scope اشتباه؛ راه اصلاح: محل ایجاد Session را از Catalog متناظر پیدا کنید و ON SERVER یا ON DATABASE را همان‌جا به کار ببرید.
• اتکا به پیام Commands completed successfully؛ راه اصلاح: نتیجه را با Catalog و در صورت نیاز DMV Runtime تأیید کنید.
• استفاده از نام Package یا Object ناقص؛ راه اصلاح: نام رسمی را از sys.dm_xe_objects استخراج کنید.
• نادیده‌گرفتن مصرف Target و فایل؛ راه اصلاح: ظرفیت، Rollover و سیاست پاک‌سازی را قبل از اجرا تعیین کنید.
• تغییر مستقیم در Production بدون Script بازگشت؛ راه اصلاح: نسخه قبل و بعد DDL را در کنترل نسخه ثبت کنید.

Performance Considerations

Predicate زودهنگام و پرهیز از Actionهای گران مانند callstack در بار بالا معمولاً بیشترین اثر را دارد.

Extended Events نسبت به بسیاری از روش‌های قدیمی سبک‌تر است، اما بدون طراحی درست بی‌هزینه نیست. Actionهای Context، Eventهای بسیار پرتکرار، Predicate ضعیف، Target حافظه‌ای بزرگ یا فایل با Rollover نامناسب می‌توانند CPU، حافظه، I/O و زمان تحلیل را افزایش دهند.

برای سنجش واقعی، شمارنده‌های sys.dm_xe_sessions، اندازه target_data، نرخ رشد xel و زمان Queryهای Parser را در یک بازه ثابت ثبت کنید. مقایسه قبل و بعد از تغییر بهتر از اتکا به حدس یا توصیه عمومی است.

Best Practices

رویداد را از sys.dm_xe_objects و ستون‌هایش را از sys.dm_xe_object_columns بررسی کنید؛ سپس کمینه Context لازم را اضافه کنید.

1. Session را با نام و هدف قابل جست‌وجو تعریف کنید.
2. Scope و Permission را پیش از DDL کنترل کنید.
3. برای Eventهای پرتکرار Predicate دقیق بنویسید.
4. پس از هر تغییر Catalog و Runtime را جداگانه اعتبارسنجی کنید.
5. اسکریپت توقف، حذف یا بازگشت را کنار اسکریپت اصلی نگه دارید.
6. ظرفیت Target و عمر داده را به Runbook اضافه کنید.

مزایا، محدودیت‌ها و زمان نامناسب استفاده

سؤالات متداول

آیا این دستور داده‌ای برمی‌گرداند؟

خروجی مستقیم ندارد؛ از اجرای بعدی نشست، نمونه‌های مطابق Event وارد Pipeline می‌شوند.

چطور بفهمیم تغییر در Catalog ثبت شده است؟

برای Scope سطح Server از sys.server_event_sessions و Viewهای وابسته استفاده کنید؛ برای Session فعال، sys.dm_xe_sessions و sys.dm_xe_session_targets را نیز بررسی کنید.

آیا می‌توان آن را در Transaction برنامه کاربردی قرار داد؟

DDLهای Extended Events را بهتر است در اسکریپت مدیریت مستقل، با TRY/CATCH و کنترل وضعیت اجرا کنید؛ رفتار Transaction را در نسخه مقصد آزمایش کنید و به Rollback منطقی متکی باشید.

تفاوت ON SERVER و ON DATABASE چیست؟

Scope مالکیت، Permission، Catalog و DMVها را تغییر می‌دهد. اسکریپت نباید این دو را بدون بررسی سرویس مقصد جایگزین یکدیگر کند.

چرا Session در Catalog هست ولی داده ندارد؟

ممکن است Start نشده باشد، Predicate هیچ Eventی را عبور نداده باشد، Target باز نشده باشد یا مسیر فایل/مجوز مشکل داشته باشد.

برای اتوماسیون چه کنترل‌هایی لازم است؟

وجود Session، وضعیت Runtime، وجود Event/Target، Permission، مسیر فایل، نتیجه DDL و Query اعتبارسنجی بعد از اجرا را ثبت کنید.

سؤالات مصاحبه

در یک مصاحبه چگونه نقش ADD EVENT را توضیح می‌دهید؟

با تفکیک نقش آن در event-add، اثر روی Metadata/Runtime و نیاز به کنترل Scope پاسخ دهید.

چرا Predicate روی Performance مهم است؟

زیرا رویداد نامرتبط را پیش از Dispatch حذف می‌کند و حجم Target و Parse را کاهش می‌دهد.

چه تفاوتی میان Catalog و DMV Runtime وجود دارد؟

Catalog تعریف پایدار را نگه می‌دارد؛ DMV Runtime فقط وضعیت نشست فعال و Targetهای باز را نشان می‌دهد.

چطور یک تغییر Extended Events را قابل بازگشت می‌کنید؟

DDL فعلی را ثبت، تغییر را کوچک، Query کنترل را مشخص و Script معکوس یا Recreate را آماده می‌کنید.

چه زمانی event_file را به ring_buffer ترجیح می‌دهید؟

وقتی دوام، حجم بیشتر، تحلیل بعدی و مدیریت Rollover مهم است؛ ring_buffer برای مشاهده کوتاه و محدود مناسب‌تر است.

چک‌لیست نهایی

1. هدف مانیتورینگ و Scope را ثبت کنید.
2. وجود پیش‌نیازهای ADD EVENT را کنترل کنید.
3. DDL را با نام Session آزمایشی اجرا کنید.
4. Catalog و Runtime را جداگانه Query بگیرید.
5. حجم Target و رخداد Drop را بسنجید.
6. اسکریپت بازگشت را ذخیره کنید.
7. زمان و مالک تغییر را در Runbook ثبت کنید.

جمع‌بندی تصمیم‌محور

ADD EVENT زمانی انتخاب درستی است که نقش آن در چرخه Session روشن، پیش‌نیازهای Scope و Permission کنترل و نتیجه با Viewهای Metadata و Runtime تأیید شود. برای این دستور، توصیه محوری چنین است: رویداد را از sys.dm_xe_objects و ستون‌هایش را از sys.dm_xe_object_columns بررسی کنید؛ سپس کمینه Context لازم را اضافه کنید.

قدم بعدی، مرور نقشه کامل دستورات Extended Events و سپس آزمایش Queryهای همین مقاله روی یک Session غیرحیاتی است.

خدمات برنامه‌نویسی و پایگاه داده

قبول سفارش‌های برنامه‌نویسی و پایگاه داده در اصفهان با شماره 09131253620؛ مجموعه‌ای معتبر با سابقه فعالیت حرفه‌ای از سال ۱۳۷۵ شمسی تاکنون.

انجام پروژه، آموزش برنامه‌نویسی و آموزش پایگاه داده SQL Server برای دانشجویان، برنامه‌نویسان و سازمان‌ها انجام می‌شود. برای سفارش پروژه از ایتا، واتساپ یا تماس مستقیم استفاده کنید.

• دانلود پروژه‌های رایگان C#
• دانلود پروژه‌های رایگان SQL Server
• دانلود پروژه‌های رایگان Microsoft Access
• دانلود پروژه‌های رایگان UML
• دانلود پروژه‌های ASP.NET Web Forms
• گزارش‌های کارآموزی
• طرح‌های توجیهی و کارآفرینی
• پروژه‌های Multimedia Builder
• تماس مستقیم: 09131253620
• تماس با ما