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.

Ikon tautan topikKonvensi Sintaks Transact-SQL.

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 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 mengatur peristiwa. 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'.

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 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 Apakah 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' 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 pemotongan data output XML. Untuk informasi selengkapnya tentang kapan menggunakan jenis target yang berbeda, 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, pemartisian memori, dan ukuran peristiwa dalam 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 dapat terjaga saat menunggu peristiwa dibersihkan dari buffer.

MAX_DISPATCH_LATENCY = { detik detik | INFINITE }

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 mengizinkan peristiwa tunggal yang lebih besar dari MAX_MEMORY; mengaturnya ke 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 diizinkan adalah 64 KB. Ketika 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 Satu set buffer dibuat untuk setiap simpul NUMA.

PER_CPU Satu set buffer dibuat untuk setiap CPU.

TRACK_CAUSALITY = { ON | NONAKTIF }

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

STARTUP_STATE = { ON | NONAKTIF }

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

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 peristiwa 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 Database Azure SQL Managed Instance atau Azure SQL, 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 simpan 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 awalan namanya 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 database Azure SQL: 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 lingkup database tidak ditampilkan dalam Object Explorer di SQL Server Management Azure SQL Managed Instance. Sesi cakupan database hanya dapat dikueri dan dikelola dengan Transact-SQL 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 isi tabel di sini mungkin sudah 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

Langkah berikutnya