MENGUBAH SESI PERISTIWA (Transact-SQL)

Berlaku untuk:SQL ServerAzure SQL Managed Instance

Memulai atau menghentikan sesi peristiwa atau mengubah konfigurasi sesi peristiwa.

Konvensi sintaks transact-SQL

Sintaks

ALTER EVENT SESSION event_session_name
ON { SERVER | DATABASE }
{
    [ [ {  <add_drop_event> [ , ...n ] }
       | { <add_drop_event_target> [ , ...n ] } ]
    [ WITH ( <event_session_options> [ , ...n ] ) ]
    ]
    | [ STATE = { START | STOP } ]
}

<add_drop_event>::=
{
    [ ADD EVENT <event_specifier>
         [ ( {
                 [ SET { event_customizable_attribute = <value> [ , ...n ] } ]
                 [ ACTION ( { [event_module_guid].event_package_name.action_name [ , ...n ] } ) ]
                 [ WHERE <predicate_expression> ]
        } ) ]
   ]
   | DROP EVENT <event_specifier> }

<event_specifier> ::=
{
[event_module_guid].event_package_name.event_name
}
<predicate_expression> ::=
{
    [ NOT ] <predicate_factor> | { ( <predicate_expression> ) }
    [ { AND | OR } [ NOT ] { <predicate_factor> | ( <predicate_expression> ) } ]
    [ , ...n ]
}

<predicate_factor>::=
{
    <predicate_leaf> | ( <predicate_expression> )
}

<predicate_leaf>::=
{
      <predicate_source_declaration> { = | < > | != | > | >= | < | <= } <value>
    | [event_module_guid].event_package_name.predicate_compare_name ( <predicate_source_declaration> , <value> )
}

<predicate_source_declaration>::=
{
    event_field_name | ( [event_module_guid].event_package_name.predicate_source_name )
}

<value>::=
{
    number | 'string'
}

<add_drop_event_target>::=
{
    ADD TARGET <event_target_specifier>
        [ ( SET { target_parameter_name = <value> [ , ...n ] } ) ]
    | DROP TARGET <event_target_specifier>
}

<event_target_specifier>::=
{
    [event_module_guid].event_package_name.target_name
}

<event_session_options>::=
{
    [       MAX_MEMORY = size [ KB | MB ] ]
    [ [ , ] EVENT_RETENTION_MODE = { ALLOW_SINGLE_EVENT_LOSS | ALLOW_MULTIPLE_EVENT_LOSS | NO_EVENT_LOSS } ]
    [ [ , ] MAX_DISPATCH_LATENCY = { seconds SECONDS | INFINITE } ]
    [ [ , ] MAX_EVENT_SIZE = size [ KB | MB ] ]
    [ [ , ] MEMORY_PARTITION_MODE = { NONE | PER_NODE | PER_CPU } ]
    [ [ , ] TRACK_CAUSALITY = { ON | OFF } ]
    [ [ , ] STARTUP_STATE = { ON | OFF } ]
    [ [ , ] MAX_DURATION = { <time duration> { SECONDS | MINUTES | HOURS | DAYS } | UNLIMITED } ]
}

Argumen

event_session_name

Nama sesi peristiwa yang ada.

STATE = MULAI | STOP

Memulai atau menghentikan sesi peristiwa. Argumen STATE harus ditentukan sendiri. Ini tidak dapat dikombinasikan dengan argumen lain dalam pernyataan yang sama ALTER EVENT SESSION .

TAMBAHKAN event_specifier PERISTIWA <>

Mengidentifikasi peristiwa untuk dikaitkan dengan sesi peristiwa. < > event_specifier dalam bentuk [event_module_guid].event_package_name. event_name, di mana:

• event_module_guid adalah GUID untuk modul yang berisi peristiwa.
• event_package_name adalah paket yang berisi peristiwa.
• event_name adalah nama peristiwa.

Peristiwa yang tersedia dapat ditemukan dengan menjalankan kueri berikut:

SELECT o.name AS event_name,
       o.description AS event_description,
       p.name AS package_name,
       p.description AS package_description
FROM sys.dm_xe_objects AS o
     INNER JOIN sys.dm_xe_packages AS p
         ON o.package_guid = p.guid
WHERE o.object_type = 'event'
ORDER BY event_name ASC;

SET { event_customizable_attribute = <nilai> [ ,... n ] }

Atribut yang dapat disesuaikan untuk peristiwa tersebut.

Atribut yang dapat disesuaikan untuk peristiwa tertentu dapat ditemukan dengan menjalankan kueri berikut:

SELECT object_name,
       name AS column_name,
       type_name,
       column_value,
       description
FROM sys.dm_xe_object_columns
WHERE object_name = 'event-name-placeholder'
      AND column_type = 'customizable'
ORDER BY column_name ASC;

ACTION ( { [event_module_guid].event_package_name. action_name [ ,... n ] })

Tindakan untuk mengaitkan dengan peristiwa, di mana:

• event_module_guid adalah GUID untuk modul yang berisi tindakan.
• event_package_name adalah paket yang berisi tindakan.
• action_name adalah nama tindakan.

Tindakan yang tersedia dapat ditemukan dengan menjalankan kueri berikut:

SELECT o.name AS action_name,
       o.description AS action_description,
       p.name AS package_name,
       p.description AS package_description
FROM sys.dm_xe_objects AS o
     INNER JOIN sys.dm_xe_packages AS p
         ON o.package_guid = p.guid
WHERE o.object_type = 'action'
ORDER BY action_name ASC;

DI MANA <predicate_expression>

Menentukan ekspresi predikat yang digunakan untuk menentukan apakah suatu peristiwa harus diproses. Jika <predicate_expression> benar, peristiwa diproses lebih lanjut oleh tindakan dan target untuk sesi tersebut. Jika <predicate_expression> salah, peristiwa dihilangkan, menghindari tindakan tambahan dan pemrosesan target. Setiap ekspresi predikat dibatasi hingga 3.000 karakter.

event_field_name

Nama bidang peristiwa yang mengidentifikasi sumber predikat.

Bidang untuk peristiwa dapat ditemukan dengan menjalankan kueri berikut:

SELECT oc.name AS field_name,
       oc.type_name AS field_type,
       oc.description AS field_description
FROM sys.dm_xe_objects AS o
INNER JOIN sys.dm_xe_packages AS p
ON o.package_guid = p.guid
INNER JOIN sys.dm_xe_object_columns AS oc
ON o.name = oc.object_name
   AND
   o.package_guid = oc.object_package_guid
WHERE o.object_type = 'event'
      AND
      o.name = 'event-name-placeholder'
      AND
      oc.column_type = 'data'
ORDER BY field_name ASC;

[event_module_guid]. event_package_name. predicate_source_name

Nama sumber predikat global di mana:

• event_module_guid adalah GUID untuk modul yang berisi peristiwa.
• event_package_name adalah paket yang berisi objek sumber predikat.
• predicate_source_name adalah nama sumber predikat.

Sumber predikat dapat ditemukan dengan menjalankan kueri berikut:

SELECT o.name AS predicate_source_name,
       o.description AS predicate_source_description,
       p.name AS package_name,
       p.description AS package_description
FROM sys.dm_xe_objects AS o
     INNER JOIN sys.dm_xe_packages AS p
         ON o.package_guid = p.guid
WHERE o.object_type = 'pred_source'
ORDER BY predicate_source ASC;

[event_module_guid].event_package_name.predicate_compare_name

Nama objek komparator predikat, di mana:

• event_module_guid adalah GUID untuk modul yang berisi peristiwa.
• event_package_name adalah paket yang berisi objek komparator predikat.
• predicate_compare_name adalah nama komparator predikat.

Komparatata predikat dapat ditemukan dengan menjalankan kueri berikut:

SELECT o.name AS predicate_comparator_name,
       o.description AS predicate_comparator_description,
       p.name AS package_name,
       p.description AS package_description
FROM sys.dm_xe_objects AS o
     INNER JOIN sys.dm_xe_packages AS p
         ON o.package_guid = p.guid
WHERE o.object_type = 'pred_compare'
ORDER BY predicate_comparator ASC;

nomor

Jenis numerik apa pun yang dapat direpresentasikan sebagai bilangan bulat 64-bit.

'string'

Baik string ANSI atau Unicode sebagaimana diperlukan oleh komparatata predikat. Tidak ada konversi jenis string implisit yang dilakukan untuk predikat membandingkan fungsi. Meneruskan nilai jenis yang tidak terduga menghasilkan kesalahan.

HILANGKAN event_specifier PERISTIWA <>

Mengidentifikasi peristiwa yang akan dihapus dari sesi peristiwa. Penentu peristiwa dalam bentuk [event_module_guid]. event_package_name. event_name, di mana:

• event_module_guid adalah GUID untuk modul yang berisi peristiwa.

• event_package_name adalah paket yang berisi objek tindakan.

• event_name adalah objek peristiwa.

  < > event_specifier harus mengidentifikasi peristiwa yang sebelumnya ditambahkan ke sesi peristiwa.

MENAMBAHKAN event_target_specifier TARGET <>

Mengidentifikasi target untuk dikaitkan dengan sesi peristiwa. Penentu target peristiwa dalam bentuk [event_module_guid]. event_package_name. target_name, di mana:

• event_module_guid adalah GUID untuk modul yang berisi peristiwa.
• event_package_name adalah paket yang berisi objek tindakan.
• target_name adalah nama target.

Target yang tersedia dapat ditemukan dengan menjalankan kueri berikut:

SELECT o.name AS target_name,
       o.description AS target_description,
       o.capabilities_desc,
       p.name AS package_name,
       p.description AS package_description
FROM sys.dm_xe_objects AS o
     INNER JOIN sys.dm_xe_packages AS p
         ON o.package_guid = p.guid
WHERE o.object_type = 'target'
ORDER BY target_name ASC;

Sesi peristiwa dapat memiliki target nol, satu, atau banyak. Semua target yang ditambahkan ke sesi peristiwa harus berbeda. Misalnya, Anda tidak dapat menambahkan target kedua event_file ke sesi yang sudah memiliki event_file target.

Untuk informasi selengkapnya, termasuk contoh penggunaan untuk target yang umum digunakan, lihat Target Peristiwa yang Diperluas.

SET { target_parameter_name = <value> [ , ... n ] }

Menetapkan parameter target.

Untuk melihat semua parameter target dan deskripsinya, jalankan kueri berikut, ganti target-name-placeholder dengan nama target, seperti event_file, ring_buffer, histogram, dll.

SELECT name AS target_parameter_name,
       column_value AS default_value,
       description
FROM sys.dm_xe_object_columns
WHERE column_type = 'customizable'
      AND object_name = 'target-name-placeholder';

Penting

Jika Anda menggunakan target buffer cincin, kami sarankan Anda mengatur MAX_MEMORY parameter target (berbeda dari MAX_MEMORY parameter sesi) menjadi 1.024 kilobyte (KB) atau kurang untuk membantu menghindari kemungkinan pemotongan data output XML.

Untuk informasi selengkapnya tentang jenis target, lihat Target Peristiwa yang Diperluas.

JATUHKAN event_target_specifier TARGET <>

Mengidentifikasi target yang akan dihapus dari sesi peristiwa. Penentu target peristiwa dalam bentuk [event_module_guid]. event_package_name. target_name, di mana:

• event_module_guid adalah GUID untuk modul yang berisi peristiwa.
• event_package_name adalah paket yang berisi objek tindakan.
• target_name adalah nama target.

Penentu target peristiwa harus mengidentifikasi target yang sebelumnya ditambahkan ke sesi peristiwa.

WITH ( <event_session_options> [ ,... n ] )

Menentukan opsi yang akan digunakan dengan sesi peristiwa.

MAX_MEMORY = ukuran [ KB | MB ]

Menentukan jumlah maksimum memori yang akan dialokasikan ke sesi untuk buffering peristiwa. Defaultnya adalah 4 MB. ukuran adalah bilangan bulat dan dapat berupa nilai kilobyte (KB) atau megabyte (MB). Jumlah maksimum tidak boleh melebihi 2 GB (2.048 MB). Namun, menggunakan nilai memori dalam rentang GB tidak disarankan.

EVENT_RETENTION_MODE = { ALLOW_SINGLE_EVENT_LOSS | ALLOW_MULTIPLE_EVENT_LOSS | NO_EVENT_LOSS }

Menentukan mode retensi peristiwa yang akan digunakan untuk menangani kehilangan peristiwa.

• ALLOW_SINGLE_EVENT_LOSS

  Peristiwa dapat hilang dari sesi. Satu peristiwa hanya dihilangkan ketika semua buffer peristiwa penuh. Kehilangan satu peristiwa ketika buffer peristiwa sepenuhnya meminimalkan dampak performa sekaligus meminimalkan hilangnya data dalam aliran peristiwa yang diproses.

• ALLOW_MULTIPLE_EVENT_LOSS

  Buffer peristiwa penuh yang berisi beberapa peristiwa dapat hilang dari sesi. Jumlah peristiwa yang hilang tergantung pada ukuran memori yang dialokasikan untuk sesi, partisi memori, dan ukuran peristiwa dalam buffer. Opsi ini umumnya menghindari dampak performa pada server ketika buffer peristiwa diisi dengan cepat, tetapi sejumlah besar peristiwa dapat hilang dari sesi.

• NO_EVENT_LOSS

  Tidak ada kehilangan peristiwa yang diperbolehkan. Opsi ini memastikan bahwa semua peristiwa yang diangkat dipertahankan. Menggunakan opsi ini memaksa semua tugas yang mengaktifkan peristiwa untuk menunggu hingga ruang tersedia dalam buffer peristiwa. Menggunakan NO_EVENT_LOSS dapat menyebabkan masalah performa yang dapat dideteksi saat sesi peristiwa aktif. Sesi dan kueri pengguna mungkin mengulur waktu sambil menunggu peristiwa dibuang dari buffer.

  Nota

  Untuk target file peristiwa di Azure SQL Database dan di Azure SQL Managed Instance (dengan kebijakan pembaruanSQL Server 2025 atau Always-up-to-date), mulai juni 2024, NO_EVENT_LOSS bereaksi sama seperti ALLOW_SINGLE_EVENT_LOSS. Jika Anda menentukan NO_EVENT_LOSS, peringatan dengan ID pesan 25665, tingkat keparahan 10, dan pesan This target doesn't support the NO_EVENT_LOSS event retention mode. The ALLOW_SINGLE_EVENT_LOSS retention mode is used instead. dikembalikan, dan sesi dibuat.

  Perubahan ini menghindari batas waktu koneksi, penundaan failover, dan masalah lain yang dapat mengurangi ketersediaan database saat NO_EVENT_LOSS digunakan dengan target file peristiwa di penyimpanan blob Azure.

  NO_EVENT_LOSS direncanakan untuk dihapus sebagai argumen yang didukung EVENT_RETENTION_MODE dalam pembaruan di masa mendatang untuk Azure SQL Database dan Azure SQL Managed Instance. Hindari menggunakan fitur ini dalam pekerjaan pengembangan baru, dan rencanakan untuk memodifikasi aplikasi yang saat ini menggunakan fitur ini.

MAX_DISPATCH_LATENCY = { detik DETIK | TAK TERBATAS }

Menentukan jumlah waktu peristiwa di-buffer dalam memori sebelum dikirim ke target sesi peristiwa. Secara default, nilai ini diatur ke 30 detik.

• detik DETIK

  Waktu, dalam detik, untuk menunggu sebelum mulai menyiram buffer ke target. detik adalah bilangan bujur. Nilai latensi minimum adalah 1 detik. Namun, 0 dapat digunakan untuk menentukan latensi INFINITE.

• TAK TERHINGGA

  Buffer flush ke target hanya ketika buffer penuh, atau ketika sesi peristiwa ditutup.

MAX_EVENT_SIZE = ukuran [ KB | MB ]

Menentukan ukuran maksimum yang diperbolehkan untuk peristiwa. MAX_EVENT_SIZE hanya boleh diatur untuk mengizinkan peristiwa tunggal yang lebih besar dari MAX_MEMORY; mengaturnya ke kurang dari MAX_MEMORY menimbulkan kesalahan. ukuran adalah bilangan bulat dan dapat berupa nilai kilobyte (KB) atau megabyte (MB). Jika ukuran ditentukan dalam kilobyte, ukuran minimum yang diizinkan adalah 64 KB. Saat MAX_EVENT_SIZE diatur, dua buffer ukuran dibuat selain MAX_MEMORY, dan total memori yang digunakan untuk buffering peristiwa MAX_MEMORY + 2 * MAX_EVENT_SIZE.

MEMORY_PARTITION_MODE = { TIDAK ADA | PER_NODE | PER_CPU }

Menentukan afinitas buffer peristiwa. Opsi selain NONE menghasilkan lebih banyak buffer dan konsumsi memori yang lebih tinggi, tetapi dapat menghindari pertikaian dan meningkatkan performa pada komputer yang lebih besar.

• TIDAK

  Satu set buffer dibuat dalam instans Mesin Database.

• PER_NODE

  Satu set buffer dibuat untuk setiap simpul NUMA.

• PER_CPU

  Satu set buffer dibuat untuk setiap CPU.

TRACK_CAUSALITY = { AKTIF | NONAKTIF }

Menentukan apakah penyebab peristiwa dilacak atau tidak. Jika diaktifkan, kausalitas memungkinkan peristiwa terkait pada koneksi server yang berbeda untuk dikorelasikan bersama-sama.

STARTUP_STATE = { AKTIF | NONAKTIF }

Menentukan apakah akan memulai sesi kejadian ini secara otomatis saat Mesin Database dimulai atau tidak.

Nota

Jika STARTUP_STATE = ON, sesi peristiwa dimulai ketika Mesin Database dihentikan lalu dimulai ulang. Untuk segera memulai sesi peristiwa, gunakan ALTER EVENT SESSION ... ON SERVER STATE = START.

• AKTIF

  Sesi peristiwa dimulai saat startup.

• TIDAK AKTIF

  Sesi peristiwa tidak dimulai saat startup.

MAX_DURATION = { durasi waktu { DETIK | MENIT | JAM | DAYS } | UNLIMITED }

Berlaku untuk: SQL Server 2025 (17.x)

• UNLIMITED

  Menyebabkan sesi peristiwa berjalan tanpa batas waktu setelah dimulai, hingga berhenti menggunakan ALTER EVENT SESSION ... STATE = STOP pernyataan.

• durasi waktu DETIK | MENIT | JAM | HARI

  Menyebabkan sesi peristiwa berhenti secara otomatis setelah waktu yang ditentukan berlalu setelah sesi dimulai. Durasi maksimum yang didukung adalah 2.147.483 detik, atau 35.792 menit, atau 596 jam, atau 24 hari.

Untuk informasi selengkapnya, lihat Sesi peristiwa terikat waktu.

Keterangan

Untuk informasi selengkapnya tentang argumen sesi peristiwa, lihat Sesi acara yang Diperluas.

Argumen ADD dan DROP tidak dapat digunakan dalam pernyataan yang sama.

Izin

SQL Server dan Azure SQL Managed Instance memerlukan ALTER ANY EVENT SESSION izin.

Azure SQL Database memerlukan ALTER ANY DATABASE EVENT SESSION izin dalam database.

Tip

SQL Server 2022 memperkenalkan izin yang lebih terperinci untuk Acara yang Diperluas. Untuk informasi selengkapnya, lihat Blog: Izin terperinci baru untuk SQL Server 2022 dan Azure SQL untuk meningkatkan kepatuhan dengan PoLP.

Contoh

A. Memulai dan menghentikan sesi peristiwa

Untuk menggunakan contoh ini dengan sesi peristiwa database, ganti ON SERVER dengan ON DATABASE.

ALTER EVENT SESSION test_session ON SERVER STATE = START;
ALTER EVENT SESSION test_session ON SERVER STATE = STOP;

B. Menambahkan peristiwa baru ke sesi yang sudah ada

Untuk menggunakan contoh ini dengan sesi peristiwa database, ganti ON SERVER dengan ON DATABASE.

ALTER EVENT SESSION test_session ON SERVER
ADD EVENT sqlserver.database_transaction_begin,
ADD EVENT sqlserver.database_transaction_end;

C. Menampilkan statistik sesi

Untuk menggunakan contoh ini dengan sesi peristiwa database, ganti sys.dm_xe_sessions dengan sys.dm_xe_database_sessions, dan sys.dm_xe_session_events dengan sys.dm_xe_database_session_events.

SELECT *
FROM sys.dm_xe_sessions
WHERE name = 'test_session';

SELECT se.*
FROM sys.dm_xe_session_events AS se
WHERE EXISTS (SELECT 1
              FROM sys.dm_xe_sessions AS s
              WHERE s.address = se.event_session_address
                    AND s.name = 'test_session');

Konten terkait

• CREATE EVENT SESSION (T-SQL)
• HILANGKAN SESI PERISTIWA (T-SQL)
• Target Peristiwa Yang Diperluas SQL Server
• sys.server_event_sessions (T-SQL)
• sys.dm_xe_objects (T-SQL)
• sys.dm_xe_object_columns (T-SQL)