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

Aplica-se a: Banco de Dados SQL do Azure Instância Gerenciada de SQL do Azure

As etapas de alto nível neste passo a passo são:

  1. Criar uma conta de Armazenamento do Azure ou localizar uma existente que seja adequada para usar
  2. Criar um contêiner nessa conta de armazenamento
  3. Criar um token SAS com o acesso necessário para esse contêiner
  4. Criar uma credencial para armazenar o token SAS no banco de dados ou instância gerenciada onde a sessão de evento foi criada
  5. Criar, iniciar e usar uma sessão de evento

Criar uma conta e um contêiner de armazenamento

Para obter uma descrição mais detalhada sobre a criação de uma conta de armazenamento do Azure, veja Criar uma conta de armazenamento. Você aprenderá a criar uma conta de armazenamento usando o portal do Azure, PowerShell, SQL do Azure, um modelo do ARM ou um modelo Bicep.

Recomendamos que você use uma conta com as seguintes características:

  • É uma conta do Standard general-purpose v2.
  • Tem um tipo de redundância correspondente à redundância do banco de dados SQL do Azure, pool elástico ou instância gerenciada onde as sessões de evento são criadas.
  • Usa a Hot camada de acesso de blob.
  • Está na mesma região do Azure que o banco de dados SQL do Azure, pool elástico ou instância gerenciada.

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

Anote os nomes da conta de armazenamento e do contêiner usados.

Criar um token SAS

O Mecanismo de Banco de Dados que executa a sessão do evento precisa de acesso específico ao contêiner de armazenamento. Você concede esse acesso criando um token SAS para o contêiner. Esse token deve atender aos seguintes requisitos:

  • Ter as permissões rwl (Read, Write, List)
  • Ter um período com hora de início e hora de expiração que abranja o tempo de vida da sessão do evento
  • Não ter restrições de endereço IP

No portal do Azure, localize a conta de armazenamento e o contêiner que você criou. Selecione o contêiner e navegue até Configurações > Tokens de acesso compartilhado. Defina Permissões como Read, Write, List, e informe a data e a hora de Início e Expiração. O token SAS que você cria só funciona dentro desse intervalo de tempo.

Selecione o botão Gerar token SAS e URL. O token SAS está na caixa 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-o como você trataria uma senha ou qualquer outro segredo.

Captura de tela da tela Tokens de Acesso Compartilhado para um contêiner de Armazenamento do Azure, com um token SAS gerado para um contêiner de exemplo.

Criar uma credencial para armazenar o token SAS

No Banco de Dados SQL do Azure, você usa uma credencial com escopo de banco de dados para armazenar o token SAS. Na Instância Gerenciada de SQL do Azure, você usa uma credencial com escopo de servidor.

Armazene o token SAS em uma credencial com escopo de banco de dados. Usando uma ferramenta de cliente, como o SSMS ou o ADS, abra uma janela de nova consulta, conecte-se ao banco de dados onde a sessão de evento foi criada 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.

Observação

A execução do seguinte lote T-SQL requer a permissão CONTROL do banco de dados, que é gerenciada pelo proprietário do banco de dados (dbo), pelos membros da função de banco de dados de db_owner e pelo administrador do servidor lógico.

/*
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;

/*
(Re-)create a database scoped credential.
The name of the credential must match the URL of the blob container.
*/
IF EXISTS (
          SELECT 1
          FROM sys.database_credentials
          WHERE name = 'https://exampleaccount4xe.blob.core.windows.net/xe-example-container'
          )
    DROP DATABASE SCOPED CREDENTIAL [https://exampleaccount4xe.blob.core.windows.net/xe-example-container];

/*
The secret is the SAS token for the container. The Read, Write, and List permissions are set.
*/
CREATE DATABASE SCOPED CREDENTIAL [https://exampleaccount4xe.blob.core.windows.net/xe-example-container]
WITH IDENTITY = 'SHARED ACCESS SIGNATURE',
     SECRET = 'sp=rwl&st=2023-10-17T23:28:32Z&se=2023-10-18T07:28:32Z&spr=https&sv=2022-11-02&sr=c&sig=REDACTED';

Antes de executar esse lote, faça as seguintes alterações:

  • Nas três ocorrências de https://exampleaccount4xe.blob.core.windows.net/xe-example-container, substitua exampleaccount4xe pelo nome da sua conta de armazenamento e substitua xe-example-container pelo nome do seu contêiner.
  • Substitua toda a cadeia de caracteres entre aspas simples na cláusula SECRET pelo token SAS copiado na etapa anterior.

Criar, iniciar e parar uma sessão de Evento

Depois que a credencial com o token SAS for criada, você poderá criar a sessão de evento. A criação de uma sessão de evento não requer a permissão CONTROL. Se a credencial com o token SAS correto já existir, você poderá criar sessões de evento mesmo se tiver um conjunto mais restrito de permissões. Consulte permissões para saber as permissões específicas necessárias.

Para criar uma nova sessão de evento no SSMS, expanda o nó Eventos Estendidos. Esse nó está na pasta de banco de dados no Banco de Dados SQL do Azure e na pasta Gerenciamento na Instância Gerenciada de SQL do Azure. Clique com o botão direito do mouse na pasta Sessões e selecione Nova Sessão.... Na página Geral, informe um nome para a sessão, que neste exemplo é example-session. Na página Eventos, selecione um ou mais eventos para adicionar à sessão. Neste exemplo, selecionamos o evento sql_batch_starting.

Captura de tela da caixa de diálogo Novo SSMS de Sessão mostrando a página de seleção de eventos com o evento sql_batch_starting selecionado.

Na página Armazenamento de Dados, selecione event_file como o tipo de destino e 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). Em nosso exemplo, o nome do BLOb é example-session.xel, e a URL inteira é https://exampleaccount4xe.blob.core.windows.net/xe-example-container/example-session.xel.

Observação

Para Instância Gerenciada de SQL, em vez de colar a URL do contêiner de armazenamento na página Armazenamento de dados, use o botão Script para criar um script T-SQL da sessão. Especifique a URL do contêiner como o valor do filename argumento, similar ao exemplo de Instância Gerenciada de SQL abaixo, e execute o script para criar a sessão.

Captura de tela da caixa de diálogo Novo SSMS de Sessão mostrando a página de seleção de armazenamento de dados com um destino event_file selecionado e uma URL de armazenamento inserida.

Agora que a sessão está configurada, você pode escolher o botão Script para criar um script T-SQL da sessão e salvá-lo para mais tarde. Veja abaixo o script do nosso exemplo de sessão:

CREATE EVENT SESSION [example-session] ON DATABASE
ADD EVENT sqlserver.sql_batch_starting
ADD TARGET package0.event_file(SET filename=N'https://exampleaccount4xe.blob.core.windows.net/xe-example-container/example-session.xel')
GO

Selecione OK para criar a sessão.

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. Você pode interrompê-la mais tarde selecionando Parar sessão da mesma forma, depois que a sessão estiver em execução.

À medida que os lotes T-SQL são executados nesse banco de dados ou instância gerenciada, a sessão grava eventos no BLOB example-session.xel do contêiner de armazenamento xe-example-container.

Para interromper a sessão, clique com o botão direito do mouse nela no Pesquisador de Objetos e selecione Parar Sessão.

Exibir dados do evento

Você pode exibir os dados de eventos na interface do usuário do visualizador de eventos do SQL Server Management Studio (SSMS), onde é possível usar filtros e agregações para analisar os dados capturados. Para obter mais informações sobre como usar o visualizador de eventos no SSMS, consulte Exibir dados de eventos no SSMS.

Baixar arquivos xel do armazenamento do Azure

Dica

Se você usar o SSMS v19.2 ou posterior, não será necessário baixar os arquivos xel da maneira descrita nesta seção. Nessas versões, o SSMS lê os arquivos xel de cada sessão diretamente do armazenamento do Azure. Para obter mais informações, consulte o blog Melhorar eventos estendidos no SQL do Azure.

Baixe o BLOB xel da sessão do contêiner de armazenamento e salve-o como um arquivo local. No portal do Azure, localize a conta de armazenamento usada, selecione Contêineres em Armazenamento de dados e encontre o contêiner criado para sua sessão de evento. O BLOb da sessão tem o nome da sessão na primeira parte seguida por um sufixo numérico. Selecione as reticências (...) para mostrar o menu de contexto do BLOb e selecione Baixar.

Você pode instalar o Gerenciador de Armazenamento do Azure para baixar vários BLObs xel em uma operação.

Depois que o arquivo xel for baixado, abra-o no SSMS. No menu principal do SSMS, vá para Arquivo e selecione Abrir. Se você tiver um único arquivo xel, selecione Arquivo... e navegue até o arquivo que você baixou. Caso tenha vários arquivos xel gerados pela mesma sessão de evento (conhecidos como arquivos de substituição), você poderá usar a caixa de diálogo Mesclar Arquivos de Evento Estendido... para abrir todos eles no visualizador de eventos.

Exibir dados de eventos usando T-SQL

Para ler dados da sessão de evento com o T-SQL, use a função sys.fn_xe_file_target_read_file(). Para usar essa função em um banco de dados ou instância gerenciada diferente daquele em que a sessão de evento foi criada, crie uma credencial para conceder ao mecanismo de banco de dados acesso ao contêiner de armazenamento com os BLOBs do evento.

Para obter um passo a passo mais detalhado, consulte Criar uma sessão de evento no SSMS.