sp_trace_create (Transact-SQL)

Artikel
2025-03-11

van toepassing op:SQL Server-

Hiermee maakt u een traceringsdefinitie. De nieuwe tracering heeft een gestopte status.

Belangrijk

Deze functie wordt verwijderd in een toekomstige versie van SQL Server. Vermijd het gebruik van deze functie in nieuwe ontwikkelwerkzaamheden en plan om toepassingen te wijzigen die momenteel gebruikmaken van deze functie. Gebruik in plaats daarvan uitgebreide gebeurtenissen.

Transact-SQL syntaxisconventies

Syntaxis

sp_trace_create
    [ @traceid = ] traceid OUTPUT
    , [ @options = ] options
    , [ @tracefile = ] N'tracefile'
    [ , [ @maxfilesize = ] maxfilesize ]
    [ , [ @stoptime = ] 'stoptime' ]
    [ , [ @filecount = ] filecount ]
[ ; ]

Argumenten

Belangrijk

Argumenten voor uitgebreide opgeslagen procedures moeten worden ingevoerd in de specifieke volgorde, zoals beschreven in de sectie Syntaxis. Als de parameters niet in de volgorde zijn ingevoerd, treedt er een foutbericht op.

[ @traceid = ] traceid OUTPUT

Het nummer dat door SQL Server is toegewezen aan de nieuwe tracering. Alle door de gebruiker verstrekte invoer wordt genegeerd. @traceid is een UITVOERparameter van het type int, met een standaardwaarde van NULL. De gebruiker maakt gebruik van de @traceid waarde om de tracering te identificeren, wijzigen en beheren die is gedefinieerd door deze opgeslagen procedure.

[ @options = ] opties

Hiermee geeft u de opties die voor de tracering zijn ingesteld. @options is int, zonder standaardinstelling. U kunt een combinatie van deze opties kiezen door de somwaarde van de gekozen opties op te geven. Als u bijvoorbeeld zowel de opties TRACE_FILE_ROLLOVER als SHUTDOWN_ON_ERRORwilt inschakelen, geeft u 6 op voor @options.

De volgende tabel bevat de opties, beschrijvingen en de bijbehorende waarden.

Optienaam	Optiewaarde	Beschrijving
`TRACE_FILE_ROLLOVER`	`2`	Hiermee geeft u op dat wanneer het @filecount is bereikt, het huidige traceringsbestand wordt gesloten en er een nieuw bestand wordt gemaakt. Alle nieuwe records worden naar het nieuwe bestand geschreven. Het nieuwe bestand heeft dezelfde naam als het vorige bestand, maar er wordt een geheel getal toegevoegd om de volgorde aan te geven. Als het oorspronkelijke traceringsbestand bijvoorbeeld de naam `filename.trc`heeft, heeft het volgende traceringsbestand de naam `filename_1.trc`, is het volgende traceringsbestand `filename_2.trc`, enzovoort. Naarmate er meer rollover-traceringsbestanden worden gemaakt, neemt de geheel getalwaarde die aan de bestandsnaam wordt toegevoegd, opeenvolgend toe. SQL Server gebruikt de standaardwaarde van @filecount (5 MB) als deze optie is opgegeven zonder een waarde op te geven voor @filecount.
`SHUTDOWN_ON_ERROR`	`4`	Hiermee geeft u op dat als de tracering om welke reden dan ook niet naar het bestand kan worden geschreven, SQL Server wordt afgesloten. Deze optie is handig bij het uitvoeren van beveiligingscontroletraceringen.
`TRACE_PRODUCE_BLACKBOX`	`8`	Hiermee geeft u op dat een record van de laatste 5 MB aan traceringsgegevens die door de server worden geproduceerd, wordt opgeslagen door de server. `TRACE_PRODUCE_BLACKBOX` is niet compatibel met alle andere opties.

[ @tracefile = ] N'tracefile'

Hiermee geeft u de locatie en bestandsnaam waarnaar de tracering is geschreven. @tracefile is nvarchar(245) zonder standaardinstelling. @tracefile kan een lokale map (zoals N'C:\MSSQL\Trace\trace.trc') of een UNC zijn voor een share of pad (zoals N'\\<servername>\<sharename>\<directory>\trace.trc').

SQL Server voegt een .trc-extensie toe aan alle traceringsbestandsnamen. Als de optie TRACE_FILE_ROLLOVER en een @filecount zijn opgegeven, maakt SQL Server een nieuw traceringsbestand wanneer het oorspronkelijke traceringsbestand wordt uitgebreid tot de maximale grootte. Het nieuwe bestand heeft dezelfde naam als het oorspronkelijke bestand, maar _n wordt toegevoegd om de volgorde aan te geven, te beginnen met 1. Als het eerste traceringsbestand bijvoorbeeld de naam filename.trcheeft, heet het tweede traceringsbestand filename_1.trc.

Als u de optie TRACE_FILE_ROLLOVER gebruikt, wordt u aangeraden geen onderstrepingstekens te gebruiken in de oorspronkelijke traceringsbestandsnaam. Als u onderstrepingstekens gebruikt, treedt het volgende gedrag op:

SQL Server Profiler laadt niet automatisch of vraagt u om de rollover-bestanden te laden (als een van deze opties voor bestandsrollover is geconfigureerd).
Met de functie sys.fn_trace_gettable worden rollover-bestanden (wanneer deze zijn opgegeven met behulp van het argument @number_files) niet geladen, waarbij de oorspronkelijke bestandsnaam eindigt met een onderstrepingsteken en een numerieke waarde. (Dit geldt niet voor het onderstrepingsteken en nummer dat automatisch wordt toegevoegd wanneer een bestand wordt overgezet.)

Notitie

Als tijdelijke oplossing voor beide gedragingen kunt u de naam van de bestanden wijzigen om de onderstrepingstekens in de oorspronkelijke bestandsnaam te verwijderen. Als het oorspronkelijke bestand bijvoorbeeld my_trace.trcheet en het rollover-bestand my_trace_1.trcheet, kunt u de naam van de bestanden wijzigen in mytrace.trc en mytrace_1.trc voordat u de bestanden opent in SQL Server Profiler.

@tracefile kan niet worden opgegeven wanneer de optie TRACE_PRODUCE_BLACKBOX wordt gebruikt.

[ @maxfilesize = ] maxfilesize

Hiermee geeft u de maximale grootte in megabytes (MB) een traceringsbestand kan groeien. @maxfilesize is grote, met een standaardwaarde van 5.

Als deze parameter is opgegeven zonder de TRACE_FILE_ROLLOVER optie, stopt de tracering met het opnemen van het bestand wanneer de gebruikte schijfruimte de hoeveelheid overschrijdt die is opgegeven door @maxfilesize.

[ @stoptime = ] 'stoptijd'

Hiermee geeft u de datum en tijd waarop de tracering wordt gestopt. @stoptime is datum/tijd-, met een standaardwaarde van NULL. Als NULL, wordt de tracering uitgevoerd totdat deze handmatig wordt gestopt of totdat de server wordt afgesloten.

Als zowel @stoptime als @maxfilesize zijn opgegeven en TRACE_FILE_ROLLOVER niet is opgegeven, worden de traceringsstops weergegeven wanneer de opgegeven stoptijd of maximale bestandsgrootte is bereikt. Als @stoptime, @maxfilesizeen TRACE_FILE_ROLLOVER zijn opgegeven, stopt de tracering bij de opgegeven stoptijd, ervan uitgaande dat de tracering het station niet vult.

[ @filecount = ] 'filecount'

Hiermee geeft u het maximum aantal of traceringsbestanden dat moet worden onderhouden met dezelfde basisbestandsnaam. @filecount is int, groter dan 1. Deze parameter is alleen geldig als de optie TRACE_FILE_ROLLOVER is opgegeven. Wanneer @filecount is opgegeven, probeert SQL Server niet meer dan @filecount traceringsbestanden te onderhouden door het oudste traceringsbestand te verwijderen voordat u een nieuw traceringsbestand opent. SQL Server houdt de leeftijd van traceringsbestanden bij door een getal toe te voegen aan de naam van het basisbestand.

Wanneer de parameter @tracefile bijvoorbeeld is opgegeven als C:\mytrace, is een bestand met de naam C:\mytrace_123.trc ouder is dan een bestand met de naam C:\mytrace_124.trc. Als @filecount is ingesteld op 2, verwijdert SQL Server het bestand C:\mytrace_123.trc voordat u het traceringsbestand maakt C:\mytrace_125.trc.

SQL Server probeert slechts één keer elk bestand te verwijderen en kan een bestand dat door een ander proces wordt gebruikt, niet verwijderen. Als een andere toepassing werkt met traceringsbestanden terwijl de tracering wordt uitgevoerd, kan SQL Server deze traceringsbestanden in het bestandssysteem achterlaten.

Codewaarden retourneren

In de volgende tabel worden de codewaarden beschreven die u kunt verkrijgen na voltooiing van de opgeslagen procedure.

Retourcode	Beschrijving
`0`	Geen fout.
`1`	Onbekende fout.
`10`	Ongeldige opties. Geretourneerd wanneer de opgegeven opties niet compatibel zijn.
`12`	Het bestand is niet gemaakt.
`13`	Onvoldoende geheugen. Geretourneerd wanneer er onvoldoende geheugen is om de opgegeven actie uit te voeren.
`14`	Ongeldige stoptijd. Geretourneerd wanneer de opgegeven stoptijd al is gebeurd.
`15`	Ongeldige parameters. Geretourneerd wanneer de gebruiker incompatibele parameters heeft opgegeven.

Opmerkingen

sp_trace_create is een opgeslagen SQL Server-procedure die veel van de acties uitvoert die eerder zijn uitgevoerd door xp_trace_* uitgebreide opgeslagen procedures die beschikbaar zijn in eerdere versies van SQL Server. Gebruik sp_trace_create in plaats van:

xp_trace_addnewqueue
xp_trace_setqueuecreateinfo
xp_trace_setqueuedestination

sp_trace_create maakt alleen een traceringsdefinitie. Deze opgeslagen procedure kan niet worden gebruikt om een tracering te starten of te wijzigen.

Parameters van alle opgeslagen SQL Trace-procedures (sp_trace_*) worden strikt getypt. Als deze parameters niet worden aangeroepen met de juiste invoerparametergegevenstypen, zoals opgegeven in de beschrijving van het argument, retourneert de opgeslagen procedure een fout.

Voor sp_trace_createmoet het SQL Server-serviceaccount machtiging schrijven hebben voor de map traceringsbestand. Als het SQL Server-serviceaccount geen beheerder is op de computer waarop het traceringsbestand zich bevindt, moet u expliciet schrijfmachtigingen verlenen aan het SQL Server-serviceaccount.

Notitie

U kunt het traceringsbestand dat met sp_trace_create is gemaakt, automatisch laden in een tabel met behulp van de fn_trace_gettable systeemfunctie. Zie sys.fn_trace_gettablevoor meer informatie.

Zie Een tracerings-maken voor een voorbeeld van het gebruik van opgeslagen traceringsprocedures.

TRACE_PRODUCE_BLACKBOX heeft de volgende kenmerken:

Het is een rollover-trace. De standaard @filecount is 2, maar kan worden overschreven door de gebruiker met behulp van @filecount optie.
De standaard @maxfilesize, net als bij andere traceringen, is 5 MB en kan worden gewijzigd.
Er kan geen bestandsnaam worden opgegeven. Het bestand wordt opgeslagen als: N'%SQLDIR%\MSSQL\DATA\blackbox.trc'.
Alleen de volgende gebeurtenissen en hun kolommen bevinden zich in de tracering:
- RPC starten
- Batch starten
- Uitzonderings-
- Aandacht
Gebeurtenissen of kolommen kunnen niet worden toegevoegd of verwijderd uit deze tracering.
Filters kunnen niet worden opgegeven voor deze tracering.

Machtigingen

Vereist ALTER TRACE-machtiging.

Delen via