sp_trace_create (Transact-SQL)

Syntaxe

sp_trace_create [ @traceid = ] trace_id OUTPUT 
          , [ @options = ] option_value 
          , [ @tracefile = ] 'trace_file' 
     [ , [ @maxfilesize = ] max_file_size ]
     [ , [ @stoptime = ] 'stop_time' ]
     [ , [ @filecount = ] 'max_rollover_files' ]

Arguments

• [ @traceid= ] trace_id
  Numéro attribué par Microsoft SQL Server à la nouvelle trace. Toute entrée fournie par l'utilisateur est ignorée. L'argument trace_id est de type int, avec NULL comme valeur par défaut. L'utilisateur spécifie la valeur de trace_id pour identifier, modifier et contrôler la trace définie par cette procédure stockée.

• [ @options= ] option_value
  Spécifie les options définies pour la trace. L'argument option_value est de type int et n'a pas de valeur par défaut. Les utilisateurs peuvent choisir une combinaison de ces options en spécifiant la valeur totale des options choisies. Ainsi, pour activer les deux options TRACE_FILE_ROLLOVER et SHUTDOWN_ON_ERROR, vous pouvez définir la valeur de option_value sur 6.

  Le tableau suivant répertorie les options, leur description et leurs valeurs.

  Nom d'option	Valeur d'option	Description
  TRACE_FILE_ROLLOVER	2	Spécifie que le fichier de trace actif est fermé et qu'un nouveau fichier est créé lorsque la valeur de max_file_size est atteinte. Tous les nouveaux enregistrements sont écrits dans le nouveau fichier. Le nouveau fichier porte le même nom que l'ancien, mais un nombre entier est ajouté pour indiquer son ordre dans la séquence. Par exemple, si le fichier de trace d'origine se nomme filename.trc, le fichier de trace suivant se nommera filename_1.trc, le fichier de trace suivant se nommera, filename_2.trc, etc. Au fur et à mesure que les fichiers de trace sont créés, la valeur du nombre entier ajouté au nom de fichier augmente de façon séquentielle. SQL Server utilise la valeur par défaut de max_file_size (5 Mo) si cette option est spécifiée sans qu'une valeur soit définie pour autant.
  SHUTDOWN_ON_ERROR	4	Indique que si la trace ne peut pas être écrite dans le fichier pour une raison quelconque, SQL Server doit s'arrêter. Cette option est utile lors de l'exécution de traces d'audit de sécurité.
  TRACE_PRODUCE_BLACKBOX	8	Indique que le serveur doit enregistrer les derniers 5 Mo d'informations de trace qu'il génère. TRACE_PRODUCE_BLACKBOX est incompatible avec toutes les autres options.

• [ @tracefile= ] 'trace_file'
  Indique l'emplacement et le nom du fichier dans lequel la trace doit être écrite. trace_file est de type nvarchar(245), sans valeur par défaut. L'argument trace_file peut être un répertoire local (par exemple, N 'C:\MSSQL\Trace\trace.trc') ou le nom UNC d'un partage ou d'un chemin d'accès (N'\\Servername\Sharename\Directory\trace.trc').

  SQL Server ajoute une extension .trc à tous les noms de fichiers de trace. Si l'option TRACE_FILE_ROLLOVER et l'argument max_file_size sont spécifiés, SQL Server crée un nouveau fichier de trace lorsque le fichier de trace d'origine a atteint sa taille maximale. Le nouveau fichier porte le même nom que le fichier d'origine, mais _n est ajouté pour indiquer son ordre dans la séquence, en commençant par 1. Par exemple, si le premier fichier de trace est nommé filename.trc, le second sera appelé filename_1.trc.

  Si vous utilisez l'option TRACE_FILE_ROLLOVER, il est préférable d'éviter les traits de soulignement dans le nom du fichier initial. Si vous utilisez les traits de soulignement, vous obtenez :

  • SQL Server Profiler ne vous amène pas à importer automatiquement des fichiers de substitution (lorsque les options appropriées sont configurées).

  • La fonction fn_trace_gettable ne permet pas d'importer des fichiers de substitution (selon l'argument number_files) lorsque le nom du fichier d'origine se termine par un trait de soulignement suivi d'une valeur numérique. Cela ne s'applique pas au trait de soulignement et au nombre qui sont automatiquement ajoutés lors du remplacement d'un fichier.

  Notes

  Une autre solution consiste à renommer les fichiers de trace pour supprimer les traits de soulignement dans le fichier d'origine. Par exemple, si le fichier d'origine s'appelle my_trace.trc, et le fichier de substitution my_trace_1.trc, vous pouvez renommer les fichiers respectivement en employant mytrace.trc et mytrace_1.trc avant de les ouvrir dans SQL Server Profiler.

  Il est impossible de spécifier l'argument trace_file lorsque l'option TRACE_PRODUCE_BLACKBOX est utilisée.

• [ @maxfilesize= ] max_file_size
  Indique la taille maximale en mégaoctets (Mo) d'un fichier de trace. L'argument max_file_size est de type bigint, avec 5 comme valeur par défaut.

  Si ce paramètre est défini sans l'option TRACE_FILE_ROLLOVER, l'enregistrement de la trace dans le fichier s'interrompt lorsque l'espace disque utilisé dépasse la quantité spécifiée par max_file_size.

• [ @stoptime= ] 'stop_time'
  Indique la date et l'heure d'arrêt de la trace. L'argument stop_time est de type datetime, avec NULL comme valeur par défaut. Si la valeur est NULL, la trace continue de s'exécuter jusqu'à ce qu'elle soit arrêtée manuellement ou que le serveur s'arrête.

  Si les arguments stop_time et max_file_size sont spécifiés et que l'option TRACE_FILE_ROLLOVER ne l'est pas, la trace s'arrête lorsque l'heure d'arrêt ou la taille maximale de fichier indiquée est atteinte. Si les valeurs de stop_time, de max_file_size et de TRACE_FILE_ROLLOVER sont spécifiées, la trace s'arrête à l'heure d'arrêt indiquée même si elle n'a pas rempli la totalité du lecteur.

• [ @filecount= ] 'max_rollover_files'
  Spécifie le nombre maximal de fichiers de trace à conserver avec le même nom de fichier de base. L'argument max_rollover_files est de type int et sa valeur est supérieure à un. Ce paramètre est valide uniquement si l'option TRACE_FILE_ROLLOVER est spécifiée. Lorsque l'argument max_rollover_files est spécifié, SQL Server tente de limiter le nombre de fichiers de trace à la valeur max_rollover_files spécifiée en supprimant le fichier le plus ancien avant d'en ouvrir un nouveau. SQL Server assure le suivi de l'ancienneté des fichiers de trace en ajoutant un numéro au nom de fichier de base.

  Par exemple, lorsque le paramètre trace_file est défini comme étant « c:\mytrace », un fichier dont le nom est « c:\mytrace_123.trc » est plus ancien qu'un fichier dont le nom est « c:\mytrace_124.trc ». Si la valeur de max_rollover_files est définie sur 2, alors SQL Server supprime le fichier « c:\mytrace_123.trc » avant de créer le fichier de trace « c:\mytrace_125.trc ».

  Notez que SQL Server n'effectue qu'une seule tentative de suppression pour chaque fichier et qu'il ne peut pas supprimer un fichier en cours d'utilisation par un autre processus. Par conséquent, si une autre application utilise des fichiers de trace tandis que la trace s'exécute, SQL Server peut laisser ces fichiers dans le système de fichiers.

Valeurs des codes de retour

Le tableau suivant décrit les valeurs de code que les utilisateurs peuvent recevoir à la fin de l'exécution de la procédure stockée.

Notes

sp_trace_create est une procédure stockée SQL Server qui exécute de nombreuses actions effectuées antérieurement par les procédures stockées étendues xp_trace_* disponibles dans les précédentes versions de SQL Server. Utilisez sp_trace_create au lieu de :

• xp_trace_addnewqueue

• xp_trace_setqueuecreateinfo

• xp_trace_setqueuedestination

sp_trace_create crée uniquement une définition de trace. Cette procédure stockée ne peut pas être utilisée pour démarrer ou modifier une trace.

Les paramètres de toutes les procédures stockées SQL Trace (sp_trace_xx) doivent être saisis de manière rigoureuse. Si ces paramètres ne sont pas appelés avec les types de données de paramètre d'entrée appropriés, comme spécifié dans la description de l'argument, la procédure stockée renvoie une erreur.

Pour sp_trace_create, le compte de service SQL Server doit disposer de l'autorisation d'écriture (Write) sur le dossier de fichiers de trace. Si le compte de service SQL Server n'est pas un administrateur sur l'ordinateur où se trouve le fichier de trace, vous devez explicitement accorder l'autorisation d'écriture à ce compte.

Pour obtenir un exemple d'utilisation de procédures stockées de trace, consultez Procédure : créer une trace (Transact-SQL).

TRACE_PRODUCE_BLACKBOX possède les caractéristiques suivantes :

• C'est une trace de substitution. Le numéro_fichier par défaut est 2 mais peut être remplacé par l'utilisateur à l'aide de l'option filecount.

• La taille_fichier par défaut comme avec d'autres traces est de 5 Mo et peut être modifiée.

• Aucun nom de fichier ne peut être spécifié. Le fichier sera enregistré sous : N'%SQLDIR%\MSSQL\DATA\blackbox.trc'

• Seuls les événements suivants et leurs colonnes sont contenus dans la trace :

  • Démarrage de RPC

  • Démarrage de lot de traitement

  • Exception

  • Attention

• Des événements ou des colonnes ne peuvent pas être ajoutés ou supprimés dans cette trace.

• Il n'est pas possible de spécifier des filtres pour cette trace.

Autorisations

L'utilisateur doit disposer de l'autorisation ALTER TRACE.

Voir aussi

Référence

Autres ressources