CREATE EVENT SESSION (T-SQL)

Berlaku untuk: SQL Server (semua versi yang didukung) Azure SQL Database

Membuat sesi Extended Events yang mengidentifikasi sumber peristiwa, target sesi peristiwa, dan opsi sesi peristiwa.

Konvensi Sintaksis SQL Transaksi.

Sintaks

CREATE EVENT SESSION event_session_name
ON { SERVER | DATABASE }
{  
    <event_definition> [ ,...n]
    [ <event_target_definition> [ ,...n] ]
    [ WITH ( <event_session_options> [ ,...n] ) ]
}
;

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

<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'
}

<event_target_definition>::=
{
    ADD TARGET [event_module_guid].event_package_name.target_name
        [ ( SET { target_parameter_name = <value> [ ,...n] } ) ]
}

<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 } ]
}

Catatan

Untuk melihat sintaks transact-SQL untuk SQL Server 2014 dan yang lebih lama, lihat Dokumentasi versi sebelumnya.

Argumen

event_session_name

Adalah nama yang ditentukan pengguna untuk sesi peristiwa. event_session_name bersifat alfanumerik, dapat mencapai 128 karakter, harus unik dalam instans SQL Server, dan harus mematuhi aturan untuk Pengidentifikasi.

TAMBAHKAN PERISTIWA [ event_module_guid ]. event_package_name. event_name

Adalah peristiwa untuk dikaitkan dengan sesi peristiwa, 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.

Peristiwa muncul dalam sys.dm_xe_objects tampilan sebagai object_type 'peristiwa'.

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

Memungkinkan atribut yang dapat disesuaikan untuk peristiwa diatur. Atribut yang dapat disesuaikan muncul dalam sys.dm_xe_object_columns tampilan sebagai column_type 'dapat disesuaikan' dan object_name = event_name.

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

Adalah tindakan untuk mengaitkan dengan sesi peristiwa, di mana:

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

Tindakan muncul dalam sys.dm_xe_objects tampilan sebagai object_type 'tindakan'.

WHERE <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 oleh sesi sebelum diproses oleh tindakan dan target untuk sesi tersebut. Ekspresi predikat dibatasi hingga 3000 karakter, yang membatasi argumen string.

event_field_name Adalah nama bidang peristiwa yang mengidentifikasi sumber predikat.

[event_module_guid]. event_package_name. predicate_source_name Adalah nama sumber predikat global di mana:

• event_module_guid adalah GUID untuk modul yang berisi peristiwa.
• event_package_name adalah paket yang berisi objek predikat.
• predicate_source_name didefinisikan dalam sys.dm_xe_objects tampilan sebagai object_type 'pred_source'.

[event_module_guid]. event_package_name. predicate_compare_name Adalah nama objek predikat untuk dikaitkan dengan peristiwa, di mana:

• event_module_guid adalah GUID untuk modul yang berisi peristiwa.
• event_package_name adalah paket yang berisi objek predikat.
• predicate_compare_name adalah sumber global yang didefinisikan dalam sys.dm_xe_objects tampilan sebagai object_type 'pred_compare'.

Nomor Adalah jenis numerik apa pun termasuk desimal. Batasan adalah kurangnya memori fisik yang tersedia atau angka yang terlalu besar untuk direpresentasikan sebagai bilangan bulat 64-bit.

'string' Baik string ANSI atau Unicode sebagaimana diperlukan oleh perbandingan predikat. Tidak ada konversi jenis string implisit yang dilakukan untuk fungsi perbandingan predikat. Meneruskan jenis yang salah menghasilkan kesalahan.

TAMBAHKAN TARGET [event_module_guid]. event_package_name. target_name

Adalah target untuk dikaitkan dengan sesi peristiwa, di mana:

• event_module_guid adalah GUID untuk modul yang berisi peristiwa.
• event_package_name adalah paket yang berisi objek tindakan.
• target_name adalah targetnya. Target muncul dalam sys.dm_xe_objects tampilan sebagai object_type 'target'.

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

Menetapkan parameter target. Parameter target muncul dalam sys.dm_xe_object_columns tampilan sebagai column_type 'dapat disesuaikan' dan object_name = target_name.

Penting

Jika Anda menggunakan target buffer cincin, kami sarankan Anda mengatur parameter target max_memory ke 2048 kilobyte (KB) untuk membantu menghindari kemungkinan pemotokan data output XML. Untuk informasi selengkapnya tentang kapan menggunakan berbagai jenis target, lihat Target untuk Peristiwa yang Diperluas di SQL Server.

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

Menentukan opsi yang akan digunakan dengan sesi peristiwa.

MAX_MEMORY =size [ 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 (kurang dari 2048 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 penuh memungkinkan karakteristik performa SQL Server yang dapat diterima, 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 di buffer. Opsi ini meminimalkan 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 diizinkan. Opsi ini memastikan bahwa semua peristiwa yang diangkat akan dipertahankan. Menggunakan opsi ini memaksa semua tugas yang mengaktifkan peristiwa untuk menunggu hingga ruang tersedia dalam buffer peristiwa. Ini dapat menyebabkan masalah performa yang dapat dideteksi saat sesi peristiwa aktif. Koneksi pengguna mungkin terjaga saat menunggu peristiwa dibersihkan dari buffer.

MAX_DISPATCH_LATENCY = | DETIK { detikTAK TERBATAS }

Menentukan jumlah waktu peristiwa akan 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 membersihkan buffer ke target. detik adalah bilangan bujur. Nilai latensi minimum adalah 1 detik. Namun, 0 dapat digunakan untuk menentukan latensi INFINITE.

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

Catatan

MAX_DISPATCH_LATENCY = 0 DETIK setara dengan MAX_DISPATCH_LATENCY = INFINITE.

MAX_EVENT_SIZE =size [ KB | MB ]

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

MEMORY_PARTITION_MODE = { NONE | PER_NODE | PER_CPU }

Menentukan lokasi tempat buffer peristiwa dibuat.

TIDAK Satu set buffer dibuat dalam instans SQL Server.

PER_NODE Sekumpulan buffer dibuat untuk setiap simpul NUMA.

PER_CPU Sekumpulan buffer dibuat untuk setiap CPU.

TRACK_CAUSALITY = { ON | OFF }

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

STARTUP_STATE = { ON | OFF }

Menentukan apakah akan memulai sesi kejadian ini secara otomatis atau tidak ketika SQL Server dimulai.

Catatan

Jika STARTUP_STATE = ON, sesi peristiwa hanya akan dimulai jika SQL Server dihentikan lalu dimulai ulang.

PADA Sesi acara dimulai saat startup.

OFF Sesi kejadian tidak dimulai saat startup.

Keterangan

Urutan prioritas untuk operator logis adalah NOT (tertinggi), diikuti oleh AND, diikuti oleh OR.

Izin

Pada SQL Server dan SQL Managed Instance, memerlukan ALTER ANY EVENT SESSION izin. Pada SQL Database, memerlukan ALTER ANY DATABASE EVENT SESSION izin dalam database.

Contoh

contoh SQL Server

Contoh berikut menunjukkan cara membuat sesi peristiwa bernama test_session. Contoh ini menambahkan dua peristiwa dan menggunakan Pelacakan Peristiwa untuk target Windows.

IF EXISTS(SELECT * FROM sys.server_event_sessions WHERE name='test_session')
    DROP EVENT session test_session ON SERVER;
GO
CREATE EVENT SESSION test_session
ON SERVER
    ADD EVENT sqlos.async_io_requested,
    ADD EVENT sqlserver.lock_acquired
    ADD TARGET package0.etw_classic_sync_target
        (SET default_etw_session_logfile_path = N'C:\demo\traces\sqletw.etl' )
    WITH (MAX_MEMORY=4MB, MAX_EVENT_SIZE=4MB);
GO

contoh Azure SQL

Di Azure SQL Managed Instance atau Azure SQL Database, simpan file .xel di Azure Blob Storage. Anda dapat menggunakan sys.fn_xe_file_target_read_file untuk membaca dari sesi acara yang diperluas yang Anda buat sendiri dan menyimpan di Azure Blob Storage. Misalnya panduan, tinjau kode target File Peristiwa untuk peristiwa yang diperluas di Azure SQL Database dan Azure SQL Managed Instance.

Contoh kode dapat berbeda untuk Azure SQL Database dan SQL Managed Instance

Beberapa contoh kode transact-SQL yang ditulis untuk SQL Server lokal memerlukan perubahan kecil untuk dijalankan di cloud. Satu kategori contoh kode tersebut melibatkan tampilan sistem yang nama awalannya sedikit berbeda antara dua sistem database:

•   -   server_ awalan untuk SQL Server dan Azure SQL Managed Instance
•   -   database_ awalan untuk Azure SQL Database dan SQL Managed Instance

Azure SQL Database hanya mendukung sesi dengan cakupan database. SQL Server Management Studio (SSMS) sepenuhnya mendukung sesi cakupan database untuk Azure SQL Database: simpul Extended Events yang berisi sesi cakupan database muncul di bawah setiap database di Object Explorer.

Azure SQL Managed Instance mendukung sesi cakupan database dan sesi cakupan server. Sesi cakupan server direkomendasikan untuk instans terkelola. SSMS sepenuhnya mendukung sesi cakupan server untuk SQL Managed Instance: simpul Extended Events yang berisi semua sesi cakupan server muncul di bawah folder Manajemen untuk setiap instans terkelola di Object Explorer.

Catatan

Sesi cakupan database tidak ditampilkan dalam Object Explorer di SQL Server Management Azure SQL Managed Instance. Sesi cakupan database hanya dapat dikueri dan dikelola dengan SQL Transact saat menggunakan instans terkelola.

Untuk ilustrasi, tabel berikut mencantumkan dan membandingkan dua subset tampilan sistem. Untuk keringkasan, subset dibatasi untuk melihat nama yang juga berisi string _event. Subset memiliki awalan nama yang berbeda karena berasal dari dua sistem database yang berbeda.

Nama dari SQL Server	Nama dari layanan awan
server_event_notifications server_event_session_actions server_event_session_events server_event_session_fields server_event_session_targets server_event_sessions server_events server_trigger_events	database_event_session_actions database_event_session_events database_event_session_fields database_event_session_targets database_event_sessions

Dua daftar dalam tabel sebelumnya akurat per Maret 2022. Tetapi konten tabel di sini mungkin menjadi kedaluarsa, karena tidak akan dipertahankan di sini. Untuk daftar yang akurat, lihat pernyataan T-SQL SELECT berikut.

SELECT name
    FROM sys.all_objects
    WHERE
        (name LIKE 'database\_%' { ESCAPE '\' } OR
         name LIKE 'server\_%' { ESCAPE '\' })
        AND name LIKE '%\_event%' { ESCAPE '\' }
        AND type = 'V'
    ORDER BY name;

Lihat juga

• sys.server_event_sessions (SQL Bertransaksi)
• sys.dm_xe_objects (SQL Bertransaksi)
• sys.dm_xe_object_columns (SQL Bertransaksi)

Langkah berikutnya

• ALTER EVENT SESSION (Transact-SQL)
• HILANGKAN SESI PERISTIWA (SQL Transaksi)