sp_trace_create (Transact-SQL)
S'applique à : 
SQL Server
Crée une définition de trace. La nouvelle trace est dans un état arrêté.
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_create
[ @traceid = ] traceid OUTPUT
, [ @options = ] options
, [ @tracefile = ] N'tracefile'
[ , [ @maxfilesize = ] maxfilesize ]
[ , [ @stoptime = ] 'stoptime' ]
[ , [ @filecount = ] filecount ]
[ ; ]
Arguments
[ @traceid = ] traceid OUTPUT
Numéro attribué par SQL Server à la nouvelle trace. Toute entrée fournie par l’utilisateur est ignorée. @traceid est un paramètre OUTPUT de type int, avec une valeur par défaut NULL. L’utilisateur utilise la valeur @traceid pour identifier, modifier et contrôler la trace définie par cette procédure stockée.
[ @options = ] options
Spécifie les options définies pour la trace. @options est int, sans valeur par défaut. Vous pouvez choisir une combinaison de ces options en spécifiant la valeur de somme des options sélectionnées. Par exemple, pour activer les deux options TRACE_FILE_ROLLOVER et SHUTDOWN_ON_ERRORspécifier 6 pour @options.
Le tableau suivant répertorie les options, leur description et leurs valeurs.
| Nom de l’option | Valeur d'option | Description |
|---|---|---|
TRACE_FILE_ROLLOVER |
2 |
Spécifie que lorsque le @filecount est atteint, le fichier de trace actuel est fermé et un nouveau fichier est créé. Tous les nouveaux enregistrements sont écrits dans le nouveau fichier. Le nouveau fichier porte le même nom que le fichier précédent, mais un entier est ajouté pour indiquer sa séquence. Par exemple, si le fichier de trace d’origine est nommé filename.trc, le fichier de trace suivant est nommé filename_1.trc, le fichier de trace suivant est filename_2.trc, et ainsi de suite.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 @filecount (5 Mo) si cette option est spécifiée sans spécifier de valeur pour @filecount. |
SHUTDOWN_ON_ERROR |
4 |
Spécifie que si la trace ne peut pas être écrite dans le fichier pour une raison quelconque, SQL Server s’arrête. Cette option est utile lors de l'exécution de traces d'audit de sécurité. |
TRACE_PRODUCE_BLACKBOX |
8 |
Spécifie qu’un enregistrement des 5 derniers Mo d’informations de trace produites par le serveur est enregistré par le serveur. TRACE_PRODUCE_BLACKBOX est incompatible avec toutes les autres options. |
[ @tracefile = ] N’tracefile'
Spécifie l’emplacement et le nom de fichier dans lesquels la trace est écrite. @tracefile est nvarchar(245) sans valeur par défaut. @tracefile peut être un répertoire local (par exempleN'C:\MSSQL\Trace\trace.trc') ou un UNC vers un partage ou un chemin d’accès (par N'\\<servername>\<sharename>\<directory>\trace.trc'exemple).
SQL Server ajoute une .trc extension à tous les noms de fichiers de trace. Si l’option TRACE_FILE_ROLLOVER et une @filecount sont spécifiées, SQL Server crée un fichier de trace lorsque le fichier de trace d’origine augmente à sa taille maximale. Le nouveau fichier porte le même nom que le fichier d’origine, mais _n est ajouté pour indiquer sa séquence, en commençant par 1. Par exemple, si le premier fichier de trace est nommé filename.trc, le deuxième fichier de trace est nommé filename_1.trc.
Si vous utilisez l’option TRACE_FILE_ROLLOVER , nous vous recommandons de ne pas utiliser de caractères de soulignement dans le nom du fichier de trace d’origine. Si vous utilisez les traits de soulignement, vous obtenez :
SQL Server Profiler ne charge pas automatiquement ou vous invite à charger les fichiers de substitution (si l’une de ces options de substitution de fichier est configurée).
La fonction sys.fn_trace_gettable ne charge pas les fichiers de substitution (lorsqu’elle est spécifiée à l’aide de l’argument @number_files ) où le nom de fichier d’origine se termine par un trait de soulignement et une valeur numérique. (Cela ne s’applique pas au trait de soulignement et au nombre ajoutés automatiquement lorsqu’un fichier est annulé.)
Remarque
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 est nommé my_trace.trcet que le fichier de substitution est nommé my_trace_1.trc, vous pouvez renommer les fichiers et mytrace.trc mytrace_1.trc avant d’ouvrir les fichiers dans SQL Server Profiler.
@tracefile ne peut pas être spécifié lorsque l’option TRACE_PRODUCE_BLACKBOX est utilisée.
[ @maxfilesize = ] maxfilesize
Indique la taille maximale en mégaoctets (Mo) d'un fichier de trace. @maxfilesize est bigint, avec une valeur par défaut de 5.
Si ce paramètre est spécifié sans l’option TRACE_FILE_ROLLOVER , la trace arrête l’enregistrement dans le fichier lorsque l’espace disque utilisé dépasse la quantité spécifiée par @maxfilesize.
[ @stoptime = ] 'stoptime'
Indique la date et l'heure d'arrêt de la trace. @stoptime est datetime, avec la valeur par défaut NULL. Si NULL, la trace s’exécute jusqu’à ce qu’elle soit arrêtée manuellement ou jusqu’à ce que le serveur s’arrête.
Si les @stoptime et les @maxfilesize sont spécifiés et TRACE_FILE_ROLLOVER ne sont pas spécifiés, les sommets de trace lorsque l’heure d’arrêt spécifiée ou la taille maximale du fichier sont atteintes. Si @stoptime, @maxfilesize et TRACE_FILE_ROLLOVER sont spécifiés, la trace s’arrête au moment de l’arrêt spécifié, en supposant que la trace ne remplit pas le lecteur.
[ @filecount = ] 'filecount'
Spécifie le nombre maximal de fichiers de trace à conserver avec le même nom de fichier de base. @filecount est int, supérieur à 1. Ce paramètre est valide uniquement si l’option TRACE_FILE_ROLLOVER est spécifiée. Lorsque @filecount est spécifié, SQL Server tente de conserver pas plus de @filecount fichiers de trace en supprimant le fichier de trace le plus ancien avant d’ouvrir un nouveau fichier de trace. SQL Server suit l’âge des fichiers de trace en ajoutant un nombre au nom du fichier de base.
Par exemple, lorsque le paramètre @tracefile est spécifié comme C:\mytrace, un fichier portant le nom C:\mytrace_123.trc est plus ancien qu’un fichier portant le nom C:\mytrace_124.trc. Si @filecount est défini 2sur , SQL Server supprime le fichier C:\mytrace_123.trc avant de créer le fichier C:\mytrace_125.trc de trace.
SQL Server tente uniquement de supprimer chaque fichier une seule fois et ne peut pas supprimer un fichier en cours d’utilisation par un autre processus. Par conséquent, si une autre application fonctionne avec des fichiers de trace pendant l’exécution de la trace, SQL Server peut laisser ces fichiers de trace dans le système de fichiers.
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. |
10 |
Options non valides. Renvoyé lorsque les options spécifiées sont incompatibles. |
12 |
Fichier non créé. |
13 |
Mémoire insuffisante. Retourné lorsqu’il n’y a pas suffisamment de mémoire pour effectuer l’action spécifiée. |
14 |
Heure d'arrêt non valide. Renvoyé lorsque l'heure d'arrêt spécifiée est déjà dépassée. |
15 |
Paramètres incorrects. Renvoyé lorsque l'utilisateur a fourni des paramètres incompatibles. |
Notes
sp_trace_create est une procédure stockée SQL Server qui effectue une grande partie des actions précédemment exécutées par xp_trace_* des procédures stockées étendues disponibles dans les versions antérieures de SQL Server. Utilisez sp_trace_create plutôt que :
xp_trace_addnewqueuexp_trace_setqueuecreateinfoxp_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 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.
Pour sp_trace_createcela, le compte de service SQL Server doit disposer d’une autorisation d’écriture dans le dossier du fichier de trace. Si le compte de service SQL Server n’est pas administrateur sur l’ordinateur où se trouve le fichier de trace, vous devez accorder explicitement l’autorisation d’écriture au compte de service SQL Server.
Remarque
Vous pouvez charger automatiquement le fichier de trace créé dans sp_trace_create une table à l’aide de la fn_trace_gettable fonction système. Pour plus d’informations, consultez sys.fn_trace_gettable.
Pour obtenir un exemple d’utilisation de procédures stockées de trace, consultez Créer une trace.
TRACE_PRODUCE_BLACKBOX présente les caractéristiques suivantes :
C’est une trace de substitution. La @filecount par défaut est 2, mais peut être remplacée par l’utilisateur à l’aide de l’option @filecount.
La @maxfilesize 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 est enregistré en tant que :
N'%SQLDIR%\MSSQL\DATA\blackbox.trc'.Seuls les événements suivants et leurs colonnes sont contenus dans la trace :
- Démarrage RPC
- Démarrage par lot
- Exception
- Attention
Les événements ou colonnes ne peuvent pas être ajoutés ou supprimés de cette trace.
Les filtres ne peuvent pas être spécifiés pour cette trace.
autorisations
Nécessite l’autorisation ALTER TRACE.