Destinos de Eventos Estendidos

Aplica-se a:SQL ServerBanco de Dados SQL do AzureInstância Gerenciada de SQL do AzureBanco de dados SQL no Microsoft Fabric

Este artigo explica quando e como usar destinos de Eventos Estendidos. Para cada destino, o artigo descreve:

• Suas habilidades em coletar e relatar dados de eventos
• Exemplos de sessões de evento usando o alvo

A tabela a seguir descreve a disponibilidade de cada tipo de destino em diferentes plataformas SQL.

A menos que indicado de forma diferente, os destinos processam os dados recebidos de forma assíncrona.

Para aproveitar ao máximo este artigo, você deve:

• Familiarizar-se com os conceitos básicos de Eventos Estendidos, conforme descrito em Início rápido: Eventos Estendidos.
• Use uma versão recente do SSMS (SQL Server Management Studio).

Destino event_file

O event_file destino grava os dados de saída da sessão de eventos dos buffers de memória em um arquivo de disco ou em um blob no Armazenamento do Azure.

• Você especifica o parâmetro filename na cláusula ADD TARGET. A extensão do arquivo deve ser xel.

• O nome do arquivo escolhido é usado pelo sistema como um prefixo ao qual um valor numérico baseado em data e hora é acrescentado, seguido pela xel extensão.

• Opcionalmente, você pode especificar o MAX_FILE_SIZE parâmetro. Ele define o tamanho máximo em megabytes (MB) para o qual o arquivo pode crescer antes de um novo arquivo ser criado.

• Opcionalmente, você pode especificar a opção MAX_ROLLOVER_FILES para escolher o número máximo de arquivos a serem mantidos no sistema de arquivos, além do arquivo atual. O valor padrão é UNLIMITED. Quando MAX_ROLLOVER_FILES for avaliado, se o número de arquivos exceder a MAX_ROLLOVER_FILES configuração, os arquivos mais antigos serão excluídos.

Criar uma sessão de evento com o alvo event_file no sistema de arquivos local.

Para obter um passo a passo para criar uma sessão de evento usando um event_file com armazenamento de arquivos local, com SSMS ou T-SQL, consulte Início Rápido: Eventos Estendidos.

Criar uma sessão de evento com destino event_file no Azure Storage

Para obter uma descrição detalhada de como criar uma conta de armazenamento no Armazenamento do Azure, consulte Criar uma conta de armazenamento. Você pode criar uma conta de armazenamento usando o portal do Azure, o PowerShell, o SQL do Azure, um modelo do ARM ou um modelo Bicep. Use uma conta que:

• É uma conta Standard general-purpose v2.
• Usa a camada de acesso de Hotblob.
• Se estiver usando o SQL Server na VM do Azure (Máquina Virtual do Azure), a conta de armazenamento deverá estar na mesma região do Azure que a VM do Azure.
• Não tem o namespace hierárquico habilitado.

Em seguida, crie um contêiner nesta conta de armazenamento usando o portal do Azure. Você também pode criar um contêiner usando o PowerShell ou usando a CLI do Azure.

Observe os nomes da conta de armazenamento e do contêiner que você criou. Use-as nas etapas a seguir.

Para ler e gravar dados de evento, o mecanismo de banco de dados requer acesso específico. Você concede esse acesso de forma diferente dependendo da sua escolha de tipo de autenticação: identidade gerenciada ou autenticação baseada em segredo com um token SAS (assinatura de acesso compartilhado).

Para autenticar no Armazenamento do Azure, o mecanismo de banco de dados requer uma credencial com escopo de servidor ou uma credencial com escopo de banco de dados, que especifica o tipo de autenticação a ser usado e fornece uma chave secreta para autenticação baseada em segredo. A criação dessa credencial requer a permissão do CONTROL banco de dados.

Para o SQL Server e a Instância Gerenciada de SQL do Azure, essa permissão é necessária no master banco de dados. Por padrão, a permissão é mantida pelos membros da função de banco de dados db_owner em master, e pelos membros da função de servidor sysadmin na instância. Para o Banco de Dados SQL do Azure e o Banco de Dados SQL no Fabric, essa permissão é mantida pelo proprietário do banco de dados (dbo), pelos membros da função de banco de db_owner dados e pelo administrador do servidor lógico.

Depois que uma credencial é criada, as etapas restantes para criar uma sessão de evento não exigem a CONTROL permissão. Consulte Permissões para obter as permissões específicas necessárias.

Conceder acesso usando a identidade gerenciada

Se estiver usando identidade gerenciada com autenticação do Microsoft Entra, atribua ao contêiner a função RBAC de Colaborador de Dados de Blob de Armazenamento para a identidade gerenciada usada pelo mecanismo de banco de dados. Para obter mais informações, consulte o seguinte com base na plataforma SQL:

• A identidade gerenciada do servidor lógico do Banco de Dados SQL do Azure.
• A identidade gerenciada da instância gerenciada de SQL do Azure.
• A identidade gerenciada da VM do Azure que hospeda sua instância do SQL Server. Para obter mais informações, consulte Como as identidades gerenciadas para recursos do Azure funcionam com máquinas virtuais do Azure.
• A identidade gerenciada da instância do SQL Server habilitada para Arc.

Depois que a atribuição de função RBAC estiver implementada, use as seguintes etapas:

1. Crie uma credencial usando T-SQL.

   Antes de executar o seguinte lote T-SQL, faça a seguinte alteração:

   • Em todas as três ocorrências de https://<storage-account-name>.blob.core.windows.net/<container-name>, substitua <storage-account-name> pelo nome da sua conta de armazenamento e substitua <container-name> pelo nome do contêiner. Verifique se não há barra ao final da URL.

   Criar uma credencial no escopo do servidor: (aplica-se ao SQL Server, Instância Gerenciada de SQL do Azure)

   Usando uma ferramenta de cliente, como o SSMS, abra uma nova janela de consulta, conecte-se ao master banco de dados na instância em que você deseja criar a sessão de evento e cole o lote T-SQL a seguir.

   /* The name of the credential must match the URL of the blob container. */
   IF EXISTS (SELECT 1
              FROM sys.credentials
              WHERE name = 'https://<storage-account-name>.blob.core.windows.net/<container-name>')
       DROP CREDENTIAL
           [https://<storage-account-name>.blob.core.windows.net/<container-name>];
   
   /* When using managed identity, the credential does not contain a secret */
   CREATE CREDENTIAL
       [https://<storage-account-name>.blob.core.windows.net/<container-name>]
       WITH IDENTITY = 'MANAGED IDENTITY';
   

   Criar uma credencial no escopo do banco de dados: (aplica-se ao Banco de Dados SQL do Azure, à Instância Gerenciada de SQL do Azure, ao Banco de Dados SQL no Fabric)

   Usando uma ferramenta de cliente, como o SSMS, abra uma nova janela de consulta, conecte-se ao banco de dados do usuário onde você cria a sessão de eventos e cole o lote T-SQL a seguir. Verifique se você está conectado ao banco de dados de usuário, e não ao banco de dados master.

   /* The name of the credential must match the URL of the blob container. */
   IF EXISTS (SELECT 1
              FROM sys.database_credentials
              WHERE name = 'https://<storage-account-name>.blob.core.windows.net/<container-name>')
       DROP DATABASE SCOPED CREDENTIAL
           [https://<storage-account-name>.blob.core.windows.net/<container-name>];
   
   /* When using managed identity, the credential does not contain a secret */
   CREATE DATABASE SCOPED CREDENTIAL
       [https://<storage-account-name>.blob.core.windows.net/<container-name>]
       WITH IDENTITY = 'MANAGED IDENTITY';
   

2. Em seguida, siga as etapas para criar uma sessão de evento no SSMS com event_file destino no Armazenamento do Azure.

Conceder acesso usando um token SAS (assinatura de acesso compartilhado)

Se estiver usando a autenticação baseada em segredo, você criará um token SAS (assinatura de acesso compartilhado) para o contêiner. Para usar esse tipo de autenticação, a opção Permitir acesso à chave da conta de armazenamento deve estar habilitada para a conta de armazenamento. Para obter mais informações, veja Impedir a autorização de chave compartilhada para uma conta do Armazenamento do Microsoft Azure.

1. No portal do Azure, navegue até a conta de armazenamento e o contêiner que você criou. Selecione o contêiner e navegue até Configurações > Tokens de acesso compartilhado.

   O token SAS deve atender aos seguintes requisitos:

   • Permissões definidas como Read, Write, , Delete. List
   • A hora de início e a hora de expiração devem abranger o tempo de vida da sessão de evento. O token SAS criado só funciona nesse intervalo de tempo.
   • Para o Banco de Dados SQL do Azure, a Instância Gerenciada de SQL do Azure e o Banco de Dados SQL no Fabric, o token SAS não deve ter restrições de endereço IP.

   Selecione o botão Gerar token SAS e URL. O token SAS está na caixa de token SAS do Blob . Você pode copiá-lo para usar na próxima etapa.

   Importante

   O token SAS fornece acesso de leitura e gravação a esse contêiner. Trate-a como você trataria uma senha ou qualquer outro segredo.

   

2. Crie uma credencial para armazenar o token SAS usando T-SQL.

   Antes de executar o seguinte lote T-SQL, faça estas alterações:

   • Se estiver criando uma credencial no escopo do servidor e usando a CREATE MASTER KEY instrução, substitua <password> por uma senha forte que proteja a chave mestra. Para obter mais informações, confira CREATE MASTER KEY.

   • Em todas as três ocorrências de https://<storage-account-name>.blob.core.windows.net/<container-name>, substitua <storage-account-name> pelo nome da sua conta de armazenamento e substitua <container-name> pelo nome do contêiner.

   • Na cláusula SECRET, substitua <sas-token> pelo token SAS copiado no passo anterior.

   Criar uma credencial no escopo do servidor: (aplica-se ao SQL Server, Instância Gerenciada de SQL do Azure)

   Usando uma ferramenta cliente como o SSMS, abra uma nova janela de consulta, conecte-a à instância do banco de dados master onde você cria a sessão de eventos, e cole o lote de T-SQL a seguir.

   /* Create a master key to protect the secret of the credential */
   IF NOT EXISTS (SELECT 1
                  FROM sys.symmetric_keys
                  WHERE name = '##MS_DatabaseMasterKey##')
       CREATE MASTER KEY ENCRYPTION BY PASSWORD = '<password>'
   
   /* The name of the credential must match the URL of the blob container. */;
   IF EXISTS (SELECT 1
              FROM sys.credentials
              WHERE name = 'https://<storage-account-name>.blob.core.windows.net/<container-name>')
       DROP CREDENTIAL
           [https://<storage-account-name>.blob.core.windows.net/<container-name>];
   
   /* The secret is the SAS token for the container. */
   CREATE CREDENTIAL
       [https://<storage-account-name>.blob.core.windows.net/<container-name>]
   WITH IDENTITY = 'SHARED ACCESS SIGNATURE',
       SECRET = '<sas-token>';
   

   Criar uma credencial no escopo do banco de dados: (aplica-se ao Banco de Dados SQL do Azure, à Instância Gerenciada de SQL do Azure, ao Banco de Dados SQL no Fabric)

   Usando uma ferramenta de cliente, como o SSMS, abra uma nova janela de consulta, conecte-se ao banco de dados em que você cria a sessão de eventos e cole o lote T-SQL a seguir. Verifique se você está conectado ao banco de dados de usuário, e não ao banco de dados master.

   /* The name of the credential must match the URL of the blob container. */
   IF EXISTS (SELECT 1
              FROM sys.database_credentials
              WHERE name = 'https://<storage-account-name>.blob.core.windows.net/<container-name>')
       DROP DATABASE SCOPED CREDENTIAL
           [https://<storage-account-name>.blob.core.windows.net/<container-name>];
   
   /* The secret is the SAS token for the container. */
   CREATE DATABASE SCOPED CREDENTIAL
       [https://<storage-account-name>.blob.core.windows.net/<container-name>]
   WITH IDENTITY = 'SHARED ACCESS SIGNATURE',
       SECRET = '<sas-token>';
   

3. Em seguida, siga as etapas na próxima seção para criar uma sessão de evento no SSMS com event_file destino no Armazenamento do Azure.

Criar uma sessão de evento no SSMS com destino event_file no Armazenamento do Azure

Depois que a credencial que fornece acesso ao contêiner de armazenamento for criada, você poderá criar a sessão de evento. Ao contrário da criação da credencial, a criação de uma sessão de evento não requer a CONTROL permissão. Depois que a credencial for criada, você poderá criar sessões de evento mesmo se tiver permissões mais restritas. Consulte Permissões para obter as permissões específicas necessárias.

Para criar uma nova sessão de evento no SSMS:

1. Para SQL Server e Instância Gerenciada de SQL do Azure, expanda o nó Eventos Estendidos na pasta Gerenciamento. Para o Banco de Dados SQL do Azure e o Banco de Dados SQL no Fabric, expanda o nó Eventos Estendidos dentro do banco de dados.

2. Clique com o botão direito do mouse na pasta Sessões e selecione Nova Sessão....

3. Na página Geral , insira um nome para a sessão, que é example-session para o exemplo de código a seguir.

4. Na página Eventos , selecione um ou mais eventos a serem adicionados à sessão. Por exemplo, você pode selecionar o sql_batch_starting evento.

5. Na página Armazenamento de Dados , selecione event_file como o tipo de destino. Cole a URL do contêiner de armazenamento na caixa URL de Armazenamento . Digite uma barra (/) no final dessa URL, seguida pelo nome do arquivo (blob). Por exemplo, https://<storage-account-name>.blob.core.windows.net/<container-name>/example-session.xel.

6. Agora que a sessão está configurada, opcionalmente, você pode selecionar o botão Script para criar um script T-SQL da sessão, para salvá-la para mais tarde.

7. Selecione OK para criar a sessão.

8. No Pesquisador de Objetos, expanda a pasta Sessões para ver a sessão de evento que você criou. Por padrão, a sessão não é iniciada quando é criada. Para iniciar a sessão, clique com o botão direito do mouse no nome da sessão e selecione Iniciar Sessão. Posteriormente, você pode pará-lo selecionando Parar Sessão depois que a sessão estiver em execução.

À medida que os lotes T-SQL são executados, a sessão grava eventos sql_batch_starting no blob example-session.xel do contêiner de armazenamento.

Crie uma sessão de evento com destino event_file no Armazenamento do Azure no T-SQL

Aqui está um exemplo do CREATE EVENT SESSION com uma ADD TARGET cláusula que adiciona um destino baseado no event_file Armazenamento do Azure.

CREATE EVENT SESSION [example-session]
ON SERVER
ADD EVENT sqlserver.sql_batch_starting
ADD TARGET package0.event_file
(
    SET filename = N'https://<storage-account-name>.blob.core.windows.net/<container-name>/example-session.xel'
)
GO

Para usar este exemplo no Banco de Dados SQL do Azure ou no Banco de Dados SQL no Fabric, substitua ON SERVER por ON DATABASE.

Solucionar problemas de sessões de evento com destino event_file no Armazenamento do Azure

A lista a seguir contém erros que você pode encontrar ao iniciar uma sessão de evento estendida que usa o Armazenamento do Azure, com as possíveis explicações para o erro.

• O sistema operacional retornou o erro 5: "O acesso foi negado".
  • Se estiver usando a autenticação de identidade gerenciada:
    • A identidade gerenciada usada pelo mecanismo de banco de dados não tem a atribuição de função RBAC necessária. Para obter mais informações, consulte Conceder acesso usando uma identidade gerenciada.
    • O firewall da conta de armazenamento está habilitado e uma exceção para permitir que serviços confiáveis do Azure acessem a conta de armazenamento também está habilitada, mas uma Microsoft.Sql/servers instância de recurso para o servidor lógico não foi adicionada à lista de instâncias de recursos que recebem acesso. Para obter mais informações, consulte Conceder acesso a partir de instâncias de recursos do Azure.
    • Se estiver usando um perímetro de segurança de rede com o modo imposto, o banco de dados e a conta de armazenamento não estão no mesmo perímetro.
  • Se estiver usando a autenticação de token SAS:
    • O firewall da conta de armazenamento está habilitado. Não há suporte para sessões de evento que usam a autenticação de token SAS.
    • O token SAS não tem permissões suficientes ou expirou. Para obter mais informações, consulte Conceder acesso usando um token SAS.
    • Se estiver usando um perímetro de segurança de rede com o modo imposto, as regras de acesso para permitir a comunicação de saída irrestrita do banco de dados e a comunicação de entrada irrestrita para a conta de armazenamento não estão em vigor.
• O sistema operacional retornou o erro 86: "A senha de rede especificada não está correta.".
  • Não há nenhuma credencial no escopo do banco de dados (para o Banco de Dados SQL do Azure) ou credencial no escopo do servidor (para a Instância Gerenciada de SQL do Azure ou o SQL Server) com o nome correspondente à URL do contêiner de blob. Para obter mais informações, consulte os exemplos para conceder acesso usando a identidade gerenciada ou conceder acesso usando um token SAS.
  • O nome da credencial termina com uma barra (/). O nome da credencial deve terminar com o nome do contêiner sem incluir a barra final.
• O sistema operacional retornou o erro 3: "O sistema não pode localizar o caminho especificado."
  • O contêiner especificado na URL do contêiner de blob não existe.
• O sistema operacional retornou o erro 13: "Os dados são inválidos".
  • Há uma política de imutabilidade no contêiner de blob. Não há suporte para armazenamento imutável para sessões de evento.
  • A conta de armazenamento tem o namespace hierárquico habilitado. Contas de armazenamento com namespace hierárquico habilitado não são suportadas para sessões de eventos.

função sys.fn_xe_file_target_read_file()

O destino event_file armazena os dados recebidos em um formato binário que não é legível por humanos. A sys.fn_xe_file_target_read_file função permite que você represente o conteúdo de um xel arquivo como um conjunto de linhas relacional. Para obter mais informações, incluindo exemplos de uso, consulte sys.fn_xe_file_target_read_file.

Destino ring_buffer

O destino ring_buffer é útil para iniciar rapidamente uma sessão de evento e coletar dados de evento apenas na memória. Quando a memória disponível no buffer de anel é usada por eventos, os eventos mais antigos são descartados. Quando você interrompe a sessão de evento, toda a saída da sessão para o ring_buffer alvo é descartada também.

Você consome dados de um destino ring_buffer convertendo-os em XML, conforme mostrado no exemplo a seguir. Durante essa conversão, todos os dados que não se encaixarem em um documento XML de 4 MB serão omitidos. Portanto, mesmo que você capture mais eventos no buffer de anel usando valores MAX_MEMORY maiores (ou deixando esse parâmetro em seu valor padrão), talvez não seja possível consumir todos eles devido ao limite de 4 MB no tamanho do documento XML, considerando a sobrecarga de marcação XML e cadeias de caracteres Unicode.

Você sabe que o conteúdo do buffer de anel é omitido durante a conversão para XML se o atributo truncated no documento XML estiver definido como 1, por exemplo:

<RingBufferTarget truncated="1" processingTime="0" totalEventsProcessed="284" eventCount="284" droppedCount="0" memoryUsed="64139">

Criar uma sessão de evento com um destino ring_buffer

Aqui está um exemplo de criação de uma sessão de evento com um ring_buffer destino para coletar os lock_acquired eventos, limitando o número total de eventos no buffer de anéis para 100. Neste exemplo, o MAX_MEMORY parâmetro aparece duas vezes: uma para definir a ring_buffer memória de destino como 1.024 KB e uma vez para definir a memória do buffer de sessão de evento como 2 MB.

Para usar este exemplo no Banco de Dados SQL do Azure ou no Banco de Dados SQL no Fabric, substitua ON SERVER por ON DATABASE.

CREATE EVENT SESSION ring_buffer_lock_acquired
ON SERVER
ADD EVENT sqlserver.lock_acquired
ADD TARGET package0.ring_buffer
(
SET MAX_EVENTS_LIMIT = 100,
    MAX_MEMORY = 1024
)
WITH
(
    MAX_MEMORY = 2 MB,
    MAX_DISPATCH_LATENCY = 3 SECONDS
);

Para iniciar a sessão de evento, execute a seguinte instrução:

ALTER EVENT SESSION ring_buffer_lock_acquired
ON SERVER
STATE = START;

Para exibir os dados de evento coletados no buffer de anel no SSMS, expanda o nó de sessão e selecione o package0.ping_buffer alvo. Os dados são exibidos em XML.

Para ver dados de evento de um ring_buffer destino em um conjunto de linhas relacional enquanto a sessão está ativa, use expressões XQuery para converter XML em dados relacionais. Por exemplo:

;WITH
/* An XML document representing memory buffer contents */
RingBuffer AS
(
    SELECT CAST (xst.target_data AS XML) AS TargetData
    FROM sys.dm_xe_session_targets AS xst
         INNER JOIN sys.dm_xe_sessions AS xs
             ON xst.event_session_address = xs.address
    WHERE xs.name = N'ring_buffer_lock_acquired'
),
/* A row for each event in the buffer, represented as an XML fragment */
EventNode AS
(
    SELECT CAST (NodeData.query('.') AS XML) AS EventInfo
    FROM RingBuffer AS rb
    CROSS APPLY rb.TargetData.nodes('/RingBufferTarget/event') AS n(NodeData)
)

/* A relational rowset formed by using the XQuery value method */
SELECT EventInfo.value('(event/@timestamp)[1]','datetimeoffset') AS timestamp,
       EventInfo.value('(event/@name)[1]','sysname') AS event_name,
       EventInfo.value('(event/data/value)[1]','nvarchar(max)') AS sql_batch_text
FROM EventNode
ORDER BY timestamp DESC;

Destino event_stream

O destino event_stream apenas pode ser usado em programas do .NET escritos em linguagens como o C#. Os desenvolvedores podem acessar um fluxo de eventos por meio de classes do .NET Framework no Microsoft.SqlServer.XEvents.Linq namespace. Esse alvo está implicitamente presente em qualquer sessão de eventos. Ele não pode ser adicionado usando T-SQL.

Para obter mais informações, consulte sys.fn_MSxe_read_event_stream.

Se você encontrar o erro 25726, The event data stream was disconnected because there were too many outstanding events. To avoid this error either remove events or actions from your session or add a more restrictive predicate filter to your session. ao ler do destino event_stream, significa que o fluxo de eventos foi preenchido com dados mais rapidamente do que o cliente poderia consumir os dados. Isso faz com que o mecanismo de banco de dados se desconecte do fluxo de eventos para evitar afetar o desempenho do mecanismo de banco de dados.

destino de histograma

O histogram destino conta o número de ocorrências de evento para valores distintos em um campo ou ação. Para cada valor distinto, um bucket de contagem separado é usado. O histogram destino processa os dados recebidos de forma síncrona.

O SOURCE_TYPE parâmetro controla o comportamento do histogram destino:

• SOURCE_TYPE = 0: coletar dados para um campo de evento.
• SOURCE_TYPE = 1: coletar dados para uma ação. Esse é o padrão.

O valor padrão do SLOTS parâmetro é 256. Se você atribuir outro valor, o valor será arredondado para a próxima potência de 2. Por exemplo, SLOTS = 59 seria arredondado para 64. O número máximo de slots de histograma para um alvo histogram é 16,384.

Ao usar histogram como destino, às vezes você pode ver resultados inesperados. Alguns eventos podem não aparecer nos espaços esperados, enquanto outros slots podem mostrar um número de eventos maior que o esperado. Isso pode acontecer se ocorrer uma colisão de hash ao atribuir eventos a slots. Embora ela seja rara, se ocorrer uma colisão de hash, um evento que deveria ser contado em um slot será contado em outro. Por esse motivo, é preciso ter cuidado ao presumir que um evento não ocorreu apenas porque a contagem em um determinado slot é zero.

Por exemplo, considere o cenário a seguir:

• Você configura uma sessão de Eventos Estendidos, usando histogram como destino e segmentando eventos por object_id, para coletar estatísticas de execução de procedimentos armazenados.
• Você executa o procedimento armazenado A. Em seguida, você executa o procedimento Barmazenado.

Se a função de hash retornar o mesmo valor para os object_id dois procedimentos armazenados, o histograma mostrará A que está sendo executado duas vezes enquanto B não aparece.

Para atenuar esse problema quando o número de valores distintos for relativamente pequeno, defina o número de slots de histograma como maior do que o quadrado dos valores distintos esperados. Por exemplo, se o destino histogram tiver seu SOURCE definido como o campo de evento table_name e houver 20 tabelas no banco de dados, 20*20 = 400. A próxima potência de 2 maior que 400 é 512, que é o número recomendado de slots neste exemplo.

Cada histogram destino aceita dados de uma única origem (um campo de evento ou uma ação) e contém apenas um histograma. Não é possível adicionar mais de um destino do mesmo tipo por sessão de evento. Também não é possível ter mais de um tipo de origem por histogram destino. Portanto, uma nova sessão de evento é necessária para acompanhar diferentes ações ou campos de evento em um destino separado histogram .

Criar uma sessão de eventos com um alvo de histograma

Confira a seguir um exemplo de criação de uma sessão de evento com um destino histogram.

Para usar este exemplo no Banco de Dados SQL do Azure ou no Banco de Dados SQL no Fabric, substitua ON SERVER por ON DATABASE.

CREATE EVENT SESSION histogram_lock_acquired
ON SERVER
ADD EVENT sqlserver.lock_acquired
(
    ACTION (sqlos.system_thread_id)
)
ADD TARGET package0.histogram
(
    SET FILTERING_EVENT_NAME = N'sqlserver.lock_acquired',
        SLOTS = 16,
        SOURCE = N'sqlos.system_thread_id',
        SOURCE_TYPE = 1
);

ADD TARGET ... (SET ...) Na cláusula, o parâmetro de destino SOURCE_TYPE é definido como 1, o que significa que o histogram destino rastreia uma ação.

A ADD EVENT ... (ACTION ...) cláusula adiciona a ação sqlos.system_thread_id ao evento. O parâmetro SOURCE é configurado como sqlos.system_thread_id para utilizar a ID do thread do sistema coletada por esta ação como fonte de dados para o destino histogram. O histogram destino neste exemplo conta o número de eventos para cada thread do lock_acquired sistema que adquire bloqueios enquanto a sessão está ativa.

Para iniciar a sessão de evento, execute a seguinte instrução:

ALTER EVENT SESSION histogram_lock_acquired
ON SERVER
STATE = START;

Para exibir os dados de histograma coletados no SSMS, expanda o nó da sessão e selecione o package0.histogram destino. Os dados são exibidos em uma grade de duas colunas. Cada linha representa um bucket de valores distintos e uma contagem de ocorrências.

Veja a seguir a aparência dos dados capturados pelo histogram destino neste exemplo. Os valores na coluna value são valores system_thread_id. Por exemplo, um total de 236 bloqueios foram adquiridos pelo thread 6540 do sistema.

value   count
-----   -----
 6540     236
 9308      91
 9668      74
10144      49
 5244      44
 2396      28

Aqui está um exemplo de leitura dos dados de um histogram destino com T-SQL:

WITH histogram_target
AS (SELECT TRY_CAST (st.target_data AS XML) AS target_data
    FROM sys.dm_xe_sessions AS s
         INNER JOIN sys.dm_xe_session_targets AS st
             ON s.address = st.event_session_address
    WHERE s.name = 'event-session-name-placeholder'),
 histogram
AS (SELECT hb.slot.value('(@count)[1]', 'bigint') AS slot_count,
           hb.slot.value('(value/text())[1]', 'nvarchar(max)') AS slot_value
    FROM histogram_target AS ht
CROSS APPLY ht.target_data.nodes('/HistogramTarget/Slot') AS hb(slot))
SELECT slot_value,
       slot_count
FROM histogram;

destino event_counter

O destino event_counter conta quantas vezes cada evento especificado ocorre.

O event_counter destino não tem parâmetros e processa os dados recebidos de forma síncrona.

Criar uma sessão de evento com um alvo event_counter

Confira a seguir um exemplo de criação de uma sessão de evento com um destino event_counter. A sessão conta os quatro checkpoint_begin primeiros eventos e, em seguida, interrompe a contagem porque seu predicado limita o número de eventos enviados aos destinos para quatro. Você pode gerar o checkpoint_begin evento para este exemplo executando o CHECKPOINT comando.

Para usar este exemplo no Banco de Dados SQL do Azure ou no Banco de Dados SQL no Fabric, substitua ON SERVER por ON DATABASE.

CREATE EVENT SESSION event_counter_checkpoint_begin
ON SERVER
ADD EVENT sqlserver.checkpoint_begin
(
    WHERE package0.counter <= 4
)
ADD TARGET package0.event_counter
WITH
(
    MAX_MEMORY = 4096 KB,
    MAX_DISPATCH_LATENCY = 3 SECONDS
);

Para iniciar a sessão de evento, execute a seguinte instrução:

ALTER EVENT SESSION event_counter_checkpoint_begin
ON SERVER
STATE = START;

Para exibir os dados coletados no SSMS, expanda o nó da sessão e selecione o package0.event_counter alvo. Os dados são exibidos em uma grade de três colunas. Cada linha representa um evento com uma contagem de suas ocorrências.

Veja como os dados capturados pelo event_counter alvo neste exemplo podem parecer após a ocorrência de quatro pontos de verificação.

package_name   event_name         count
------------   ----------------   -----
sqlserver      checkpoint_begin   4

destino pair_matching

O destino pair_matching permite detectar eventos de início que ocorrem sem um evento de término correspondente. Por exemplo, você pode encontrar um lock_acquired evento sem um lock_released evento correspondente, o que pode indicar que uma transação de longa duração está mantendo bloqueios.

Eventos Estendidos não correspondem automaticamente aos eventos de início e término. Em vez disso, você define a lógica correspondente na pair_matching especificação de destino na CREATE EVENT SESSION instrução. Quando um evento de início e término é pareado, o destino descarta o par, mas retém eventos de início que não foram pareados.

Criar uma sessão de evento com um alvo de pareamento

Para este exemplo, criamos uma tabela de exemplo chamada T1, inserimos três linhas e obtemos o object_id valor dessa tabela. Para simplificar, criamos a tabela no tempdb banco de dados neste exemplo. Se você usar um banco de dados diferente, ajuste o nome do banco de dados no código de exemplo T-SQL a seguir.

CREATE TABLE T1 (id INT PRIMARY KEY);

INSERT INTO T1 (id)
VALUES (1), (2), (3);

SELECT OBJECT_ID('T1') AS object_id;
-- object_id = 1029578706

A sessão de evento a seguir coleta dois eventos lock_acquired e lock_released. Ele também tem dois alvos. Um é o event_counter alvo que fornece o número de ocorrências para cada evento. O outro é o pair_matching alvo que define a lógica para a correspondência entre o evento inicial lock_acquired e o evento final lock_released por meio de pares.

A sequência de campos delimitados por vírgulas atribuídos a BEGIN_MATCHING_COLUMNS e a END_MATCHING_COLUMNS deve ser a mesma. Não são permitidas guias nem novas linhas entre os campos mencionados no valor delimitado por vírgula, embora o uso de espaços seja permitido.

Na definição da sessão de evento, utilizamos um predicado de evento para coletar somente aqueles eventos no banco de dados tempdb onde o object_id do evento corresponde ao ID do objeto da tabela T1. Ajuste o predicado na cláusula WHERE para usar o ID do objeto da tabela.

Para usar este exemplo no Banco de Dados SQL do Azure ou no Banco de Dados SQL no Fabric, substitua ON SERVER por ON DATABASE.

CREATE EVENT SESSION pair_matching_lock_acquired_released
ON SERVER
ADD EVENT sqlserver.lock_acquired
(
    SET COLLECT_DATABASE_NAME = 1,
        COLLECT_RESOURCE_DESCRIPTION = 1
    ACTION (sqlserver.transaction_id)
    WHERE (database_name = 'tempdb'
           AND object_id = 1029578706)
),
ADD EVENT sqlserver.lock_released
(
    SET COLLECT_DATABASE_NAME = 1,
        COLLECT_RESOURCE_DESCRIPTION = 1
    ACTION (sqlserver.transaction_id)
    WHERE (database_name = 'tempdb'
           AND object_id = 1029578706)
)
ADD TARGET package0.event_counter,
ADD TARGET package0.pair_matching
(
    SET BEGIN_EVENT = N'sqlserver.lock_acquired',
        BEGIN_MATCHING_COLUMNS = N'resource_0, resource_1, resource_2, transaction_id, database_id',
        END_EVENT = N'sqlserver.lock_released',
        END_MATCHING_COLUMNS = N'resource_0, resource_1, resource_2, transaction_id, database_id',
        RESPOND_TO_MEMORY_PRESSURE = 1
)
WITH
(
    MAX_MEMORY = 8192 KB,
    MAX_DISPATCH_LATENCY = 15 SECONDS
);

Para iniciar a sessão de evento, execute a seguinte instrução:

ALTER EVENT SESSION pair_matching_lock_acquired_released
ON SERVER
STATE = START;

Inicie uma transação que atualize a T1 tabela, mas não a confirme ou reverta. Isso garante que haja bloqueios adquiridos, mas não liberados.

BEGIN TRANSACTION;
UPDATE T1
    SET id = id + 1;

Examine a saída de cada destino da sessão de eventos pair_matching_lock_acquired_released no SSMS.

O event_counter destino tem a saída a seguir, mostrando que um bloqueio permanece não liberado. No entanto, esse alvo não exibe nenhum detalhe desse bloqueio.

package_name   event_name      count
------------   ----------      -----
sqlserver      lock_acquired   4
sqlserver      lock_released   3

O pair_matching destino tem a saída a seguir, truncada para fins de brevidade. Conforme sugerido pela saída event_counter, vemos de fato a única linha do evento não pareado lock_acquired, com mais detalhes sobre o evento.

package_name  event_name    timestamp                     associated_object_id  database_id  database_name
------------  ------------  ---------                     -------------         -----------  -------------
sqlserver    lock_acquired   2025-10-01 20:06:07.1890000  1029578706            2            tempdb

Reverta a transação.

ROLLBACK;

Se você adicionar uma ação a um evento coletado pelo pair_matching alvo, os dados da ação também serão coletados. Por exemplo, você pode incluir o texto T-SQL fornecido pela ação sqlserver.sql_text com o evento. Neste exemplo, ele coletaria a consulta que adquiriu o bloqueio.

destino etw_classic_sync_target

No SQL Server, Eventos Estendidos podem interoperar com o ETW (Rastreamento de Eventos para Windows) para monitorar a atividade do sistema. Para saber mais, veja:

• Destino do Rastreamento de Eventos para Windows
• Monitorar a atividade do sistema usando Eventos Estendidos

Esse destino ETW processa os dados recebidos de forma síncrona.

Conteúdo relacionado

• Visão geral de eventos estendidos
• Início rápido: Eventos Estendidos
• Eventos estendidos no SQL do Azure