Compartilhar via

sp_trace_setfilter (Transact-SQL)

  • Artigo

Aplica-se: SQL Server

Aplica um filtro a um rastreamento. sp_trace_setfilter pode ser executado somente em rastreamentos existentes que são interrompidos (@status é 0). O SQL Server retornará um erro se esse procedimento armazenado for executado em um rastreamento que não existe ou cujo @status não 0é .

Importante

Esse recurso será removido em uma versão futura do SQL Server. Evite usar esse recurso em desenvolvimentos novos e planeje modificar os aplicativos que atualmente o utilizam. Em vez disso, use Eventos Estendidos.

Convenções de sintaxe de Transact-SQL

Sintaxe

sp_trace_setfilter
    [ @traceid = ] traceid
    , [ @columnid = ] columnid
    , [ @logical_operator = ] logical_operator
    , [ @comparison_operator = ] comparison_operator
    , [ @value = ] value
[ ; ]

Argumentos

@traceid [ = ] traceid

A ID do rastreamento para o qual o filtro está definido. @traceid é int, sem padrão. O usuário emprega esse valor @traceid para identificar, modificar e controlar o rastreamento.

@columnid [ = ] columnid

A identificação da coluna na qual o filtro é aplicado. @columnid é int, sem padrão. Se @columnid for NULL, o SQL Server limpará todos os filtros do rastreamento especificado.

@logical_operator [ = ] logical_operator

Especifica se o operador AND (0) ou OR (1) é aplicado. @logical_operator é int, sem padrão.

@comparison_operator [ = ] comparison_operator

Especifica o tipo de comparação a ser feita. @comparison_operator é int, sem padrão. A tabela contém os operadores de comparação e os valores representativos dos mesmos.

Valor Operador de comparação
0 = (Igual)
1 <> (Não é igual)
2 > (Maior que)
3 < (Menos que)
4 >= (Maior ou igual)
5 <= (Menor ou igual)
6 LIKE
7 NOT LIKE

[ @value = ] value

Especifica o valor no qual filtrar. O tipo de dados do @value deve corresponder ao tipo de dados da coluna a ser filtrada. Por exemplo, se o filtro for definido em uma coluna de ID de objeto que seja um tipo de dados int , @value deverá ser int. Se @value for nvarchar ou varbinary, ele pode ter um comprimento máximo de 8000.

Quando o operador de comparação é LIKE ou NOT LIKE, o operador lógico pode incluir % ou outro filtro apropriado para a LIKE operação.

Você pode especificar NULL para @value filtrar eventos com NULL valores de coluna. Somente 0 os operadores (= Equal) e 1 (<> Not Equal) são válidos com NULL. Nesse caso, esses operadores são equivalentes aos operadores Transact-SQL IS NULL e IS NOT NULL .

Para aplicar o filtro entre um intervalo de valores de coluna, sp_trace_setfilter deve ser executado duas vezes: uma vez com um operador de comparação maior ou igual (>=) e outra vez com um operador menor ou igual (<=).

Para obter mais informações sobre os tipos de dados da coluna de dados, consulte a Referência de classe de evento do SQL Server.

Valores do código de retorno

A tabela a seguir descreve os valores de código que você pode obter, após a conclusão do procedimento armazenado.

Código de retorno Descrição
0 Nenhum erro.
1 Erro desconhecido.
2 O rastreamento está sendo executado no momento. A alteração do rastreamento neste momento resulta em um erro.
4 A coluna especificada não é válida.
5 A coluna especificada não é permitida para filtragem. Esse valor é retornado apenas de sp_trace_setfilter.
6 O Operador de Comparação especificado não é válido.
7 O operador lógico especificado não é válido.
9 O identificador de rastreamento especificado não é válido.
13 Sem memória. Retornado quando não há memória suficiente para executar a ação especificada.
16 A função não é válida para esse rastreamento.

Comentários

sp_trace_setfilter é um procedimento armazenado do SQL Server que executa muitas das ações executadas anteriormente por procedimentos armazenados estendidos disponíveis em versões anteriores do SQL Server. Use sp_trace_setfilter em vez dos xp_trace_set*filter procedimentos armazenados estendidos para criar, aplicar, remover ou manipular filtros em rastreamentos. Para obter mais informações, consulte Filtrar um rastreamento.

Todos os filtros de uma coluna específica devem ser habilitados juntos em uma execução de sp_trace_setfilter. Por exemplo, se um usuário pretende aplicar dois filtros na coluna de nome de aplicativo e um filtro na coluna de nome de usuário, o usuário deve especificar os filtros em nome de aplicativo em sequência. O SQL Server retornará um erro se o usuário tentar especificar um filtro no nome do aplicativo em uma chamada de procedimento armazenado, seguido por um filtro no nome de usuário e, em seguida, outro filtro no nome do aplicativo.

Os parâmetros de todos os procedimentos armazenados do Rastreamento SQL (sp_trace_*) são estritamente tipados. Se esses parâmetros não forem chamados com os tipos de dados de parâmetro de entrada corretos, conforme especificado na descrição do argumento, o procedimento armazenado retornará um erro.

Permissões

Requer permissão ALTER TRACE.

Exemplos

O exemplo a seguir define três filtros em Rastreamento 1. O filtros N'SQLT%' e o N'MS%' funcionam em uma coluna (AppName, valor 10) que usa o operador de comparação "LIKE". O filtro N'joe' funciona em uma coluna diferente (UserName, valor 11) que usa o operador de comparação "EQUAL".

EXEC sp_trace_setfilter 1, 10, 0, 6, N'SQLT%';
EXEC sp_trace_setfilter 1, 10, 0, 6, N'MS%';
EXEC sp_trace_setfilter 1, 11, 0, 0, N'joe';

Conteúdo relacionado