Partager via

sp_trace_setfilter (Transact-SQL)

  • Article

S'applique à : SQL Server

Applique un filtre à une trace. sp_trace_setfilter peut être exécuté uniquement sur les traces existantes qui sont arrêtées (@status est 0). SQL Server retourne une erreur si cette procédure stockée est exécutée sur une trace qui n’existe pas ou dont @status n’est pas 0.

Important

Cette fonctionnalité sera supprimée dans une version future de SQL Server. Évitez d'utiliser cette fonctionnalité dans de nouveaux travaux de développement, et prévoyez de modifier les applications qui utilisent actuellement cette fonctionnalité. Utilisez plutôt des événements étendus.

Conventions de la syntaxe Transact-SQL

Syntaxe

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

Arguments

[ @traceid = ] traceid

ID de la trace sur laquelle le filtre est défini. @traceid est int, sans valeur par défaut. L’utilisateur utilise cette valeur @traceid pour identifier, modifier et contrôler la trace.

[ @columnid = ] columnid

ID de la colonne sur laquelle le filtre est appliqué. @columnid est int, sans valeur par défaut. Si @columnid est NULL, SQL Server efface tous les filtres pour la trace spécifiée.

[ @logical_operator = ] logical_operator

Spécifie si l’opérateur AND (0) ou OR (1) est appliqué. @logical_operator est int, sans valeur par défaut.

[ @comparison_operator = ] comparison_operator

Spécifie le type de comparaison à effectuer. @comparison_operator est int, sans valeur par défaut. Le tableau contient les opérateurs de comparaison et leurs valeurs.

Valeur Opérateur de comparaison
0 = (Égal)
1 <> (Non égal)
2 > (Supérieur à)
3 < (Inférieur à)
4 >= (Supérieur ou égal)
5 <= (Inférieur ou égal)
6 LIKE
7 NOT LIKE

[ @value = ] value

Indique la valeur sur laquelle appliquer le filtre. Le type de données de @value doit correspondre au type de données de la colonne à filtrer. Par exemple, si le filtre est défini sur une colonne ID d’objet qui est un type de données int , @value doit être int. Si @value est nvarchar ou varbinary, il peut avoir une longueur maximale de 8 000.

Lorsque l’opérateur de comparaison est LIKE ou NOT LIKE, l’opérateur logique peut inclure % ou un autre filtre approprié pour l’opération LIKE .

Vous pouvez spécifier NULL @value pour filtrer les événements avec NULL des valeurs de colonne. Seuls (= Égal 0 ) et 1 (<> Égal) les opérateurs sont valides avec NULL. Dans ce cas, ces opérateurs sont équivalents aux opérateurs Transact-SQLIS NULL.IS NOT NULL

Pour appliquer le filtre entre une plage de valeurs de colonne, sp_trace_setfilter doit être exécuté deux fois : une fois avec un opérateur de comparaison supérieur ou égal à (>=) et une autre fois avec un opérateur inférieur ou égal à (<=).

Pour plus d’informations sur les types de données de colonne de données, consultez la référence de la classe d’événements SQL Server.

Valeurs des codes de retour

Le tableau suivant décrit les valeurs de code que vous pouvez obtenir, après la fin de la procédure stockée.

Code de retour Description
0 Aucune erreur.
1 Erreur inconnue.
2 La trace est en cours d'exécution. La modification de la Trace à cet instant précis entraîne une erreur.
4 La colonne spécifiée n’est pas valide.
5 La colonne spécifiée n’est pas autorisée pour le filtrage. Cette valeur est retournée uniquement à partir de sp_trace_setfilter.
6 L’opérateur de comparaison spécifié n’est pas valide.
7 L’opérateur logique spécifié n’est pas valide.
9 Le handle de trace spécifié n’est pas valide.
13 Mémoire insuffisante. Retourné lorsqu’il n’y a pas suffisamment de mémoire pour effectuer l’action spécifiée.
16 La fonction n’est pas valide pour cette trace.

Notes

sp_trace_setfilter est une procédure stockée SQL Server qui effectue une grande partie des actions précédemment exécutées par des procédures stockées étendues disponibles dans les versions antérieures de SQL Server. Utilisez sp_trace_setfilter plutôt que les xp_trace_set*filter procédures stockées étendues pour créer, appliquer, supprimer ou manipuler des filtres sur des traces. Pour plus d’informations, consultez Filtrer une trace.

Tous les filtres d’une colonne particulière doivent être activés ensemble dans une exécution de sp_trace_setfilter. Par exemple, si un utilisateur décide d'appliquer deux filtres sur la colonne Nom d'application et un filtre sur la colonne Nom d'utilisateur, il doit spécifier les filtres sur le nom d'application de manière séquentielle. SQL Server retourne une erreur si l’utilisateur tente de spécifier un filtre sur le nom de l’application dans un appel de procédure stockée, suivi d’un filtre sur le nom d’utilisateur, puis d’un autre filtre sur le nom de l’application.

Les paramètres de toutes les procédures stockées trace SQL (sp_trace_*) sont strictement typés. Si ces paramètres ne sont pas appelés à l’aide des types de données appropriés pour les paramètres d’entrée tels qu’ils sont spécifiés dans la description de l’argument, la procédure stockée retourne une erreur.

autorisations

Nécessite l’autorisation ALTER TRACE.

Exemples

L'exemple suivant définit trois filtres sur Trace 1. Les filtres N'SQLT%' et N'MS%' opèrent sur une colonne (AppName, valeur 10) à l'aide de l'opérateur de comparaison « LIKE ». Le filtre N'joe' opère sur une autre colonne (UserName, valeur 11) à l'aide de l'opérateur de comparaison « 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';

Contenu connexe