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é.

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. Les utilisateurs peuvent choisir une combinaison de ces options en spécifiant la valeur totale des options choisies. 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.

[ @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é.)

@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 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 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_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 trace SQL (sp_trace_*) sont strictement typés. Si ces paramètres ne sont pas appelés avec les types de données de paramètre d’entrée corrects, comme spécifié 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.

Pour obtenir un exemple d’utilisation de procédures stockées de trace, consultez Créer une trace (Transact-SQL).

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.

Contenu connexe

• sp_trace_generateevent (Transact-SQL)
• sp_trace_setevent (Transact-SQL)
• sp_trace_setfilter (Transact-SQL)
• sp_trace_setstatus (Transact-SQL)
• Trace SQL