sp_trace_create (Transact-SQL)

Erstellt eine Ablaufverfolgungsdefinition. Die neue Ablaufverfolgung weist einen beendeten Status auf.

Wichtiger HinweisWichtig

Diese Funktion wird in zukünftigen Versionen von Microsoft SQL Server nicht mehr bereitgestellt. Verwenden Sie diese Funktion beim Entwickeln neuer Anwendungen nicht, und planen Sie das Ändern von Anwendungen, in denen es zurzeit verwendet wird. Verwenden Sie stattdessen erweiterte Ereignisse.

Themenlink (Symbol) Transact-SQL-Syntaxkonventionen

Syntax

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

Argumente

  • [ @traceid= ] trace_id
    Die Nummer, die der neuen Ablaufverfolgung von Microsoft SQL Server zugewiesen wird. Benutzereingaben werden ignoriert. trace_id ist vom Datentyp int. Der Standardwert ist NULL. Der Benutzer verwendet den trace_id-Wert zum Identifizieren, Ändern und Steuern der von dieser gespeicherten Prozedur definierten Ablaufverfolgung.

  • [ @options= ] option_value
    Gibt die für die Ablaufverfolgung festgelegten Optionen an. option_value ist vom Datentyp int und hat keinen Standardwert. Benutzer können eine Kombination dieser Optionen wählen, indem sie den Summenwert der gewünschten Optionen angeben. Um z. B. die Optionen TRACE_FILE_ROLLOVER und SHUTDOWN_ON_ERROR zu aktivieren, geben Sie für option_value den Wert 6 an.

    In der folgenden Tabelle werden die Optionen, Beschreibungen und die zugehörigen Werte aufgeführt.

    Optionsname

    Optionswert

    Beschreibung

    TRACE_FILE_ROLLOVER

    2

    Gibt an, dass die aktuelle Ablaufverfolgungsdatei beim Erreichen einer Größe von max_file_size geschlossen und eine neue Datei erstellt wird. Alle neuen Datensätze werden in die neue Datei geschrieben. Der Name der neuen Datei stimmt mit dem der vorigen Datei überein, wird jedoch durch eine angefügte ganze Zahl ergänzt, um die Position der Datei in der Sequenz anzuzeigen. Ist z. B. der Name der ursprünglichen Ablaufverfolgungsdatei filename.trc, so wird die nächste Datei mit filename_1.trc benannt, dann folgt filename_2.trc usw.

    Wenn weitere Ablaufverfolgungs-Rolloverdateien erstellt werden, erhöht sich der an die Dateinamen angefügte ganzzahlige Wert sequenziell.

    SQL Server verwendet den Standardwert von max_file_size (5 MB), wenn diese Option ohne einen Wert für max_file_size angegeben wird.

    SHUTDOWN_ON_ERROR

    4

    Gibt an, dass SQL Server heruntergefahren wird, wenn die Ablaufverfolgung nicht in die Datei geschrieben werden kann, unabhängig vom Grund. Diese Option ist beim Ausführen von Ablaufverfolgungen zur Sicherheitsüberwachung hilfreich.

    TRACE_PRODUCE_BLACKBOX

    8

    Gibt an, dass eine Aufzeichnung der letzten 5 MB der Ablaufverfolgungsinformationen, die vom Server erzeugt wurden, von diesem Server gespeichert werden. TRACE_PRODUCE_BLACKBOX ist mit keiner der anderen Optionen kompatibel.

  • [ [ @tracefile= ] 'trace_file'
    Gibt den Speicherort und den Dateinamen zum Schreiben der Ablaufverfolgung an. trace_file ist vom Datentyp nvarchar(245) und hat keinen Standardwert. Bei trace_file kann es sich entweder um ein lokales Verzeichnis (wie z. B. N 'C:\MSSQL\Trace\trace.trc') oder um einen UNC-Namen für eine Freigabe oder einen Pfad handeln (N'\\Servername\Freigabename\Verzeichnis\trace.trc').

    SQL Server fügt die Erweiterung .trc an alle Namen von Ablaufverfolgungsdateien an. Wenn die Option TRACE_FILE_ROLLOVER und ein Wert für max_file_size angegeben werden, wird von SQL Server eine neue Ablaufverfolgungsdatei erstellt, wenn die ursprüngliche Datei auf ihre maximale Größe vergrößert wird. Die neue Datei hat den gleichen Namen wie die ursprüngliche Datei; es wird jedoch _n angefügt, um ihre Position in der Sequenz anzuzeigen, beginnend mit 1. Wenn die erste Ablaufverfolgungsdatei z. B. den Namen filename.trc hat, wird die zweite Datei mit filename_1.trc benannt.

    Wenn Sie die Option TRACE_FILE_ROLLOVER verwenden, sollten im ursprünglichen Dateinamen keine Unterstriche enthalten sein. Bei Verwendung von Unterstrichen tritt Folgendes auf:

    • SQL Server Profiler lädt die Rolloverdateien nicht automatisch und fordert nicht automatisch zum Laden auf (sofern eine dieser Dateirolloveroptionen konfiguriert ist).

    • Die fn_trace_gettable-Funktion lädt keine Rolloverdateien (sofern diese Option mit dem number_files-Argument angegeben wird), wenn der ursprüngliche Name der Ablaufverfolgungsdatei mit einem Unterstrich und einem numerischen Wert endet. (Dies gilt nicht für den Unterstrich und die Zahl, die beim Rollover automatisch angehängt werden.)

    HinweisHinweis

    Um diese beiden Probleme zu umgehen, können Sie die Dateien umbenennen und die Unterstriche im ursprünglichen Dateinamen entfernen. Wenn beispielsweise der ursprüngliche Dateiname my_trace.trc lautet und die Rolloverdatei my_trace_1.trc genannt wird, können Sie die Dateien zu mytrace.trc und mytrace_1.trc umbenennen, bevor Sie die Dateien in SQL Server Profiler öffnen.

    trace_file kann nicht angegeben werden, wenn die Option TRACE_PRODUCE_BLACKBOX verwendet wird.

  • [ @maxfilesize= ] max_file_size
    Gibt die Maximalgröße in Megabyte (MB) an, auf die eine Ablaufverfolgungsdatei vergrößert werden kann. max_file_size ist vom Datentyp bigint. Der Standardwert ist 5.

    Wenn dieser Parameter ohne die Option TRACE_FILE_ROLLOVER angegeben ist, beendet die Ablaufverfolgung die Aufzeichnung in der Datei, sobald der verwendete Speicherplatz den Wert max_file_size überschreitet.

  • [ @stoptime= ] 'stop_time'
    Gibt das Datum und die Uhrzeit an, zu denen die Ablaufverfolgung beendet wird. stop_time ist vom Datentyp datetime. Der Standardwert ist NULL. Beim Wert NULL wird die Ablaufverfolgung so lange ausgeführt, bis sie manuell beendet oder der Server heruntergefahren wird.

    Wenn stop_time und max_file_size angegeben sind, TRACE_FILE_ROLLOVER jedoch nicht, wird die Ablaufverfolgung beendet, sobald entweder die angegebene Beendigungszeit oder die maximale Dateigröße erreicht ist. Wenn stop_time, max_file_size und TRACE_FILE_ROLLOVER angegeben sind, wird die Ablaufverfolgung zur angegebenen Beendigungszeit beendet, es sei denn, die Ablaufverfolgung füllt den gesamten verfügbaren Speicherplatz auf dem Laufwerk.

  • [ @filecount= ] 'max_rollover_files'
    Gibt die maximale Anzahl von Ablaufverfolgungsdateien an, die mit dem gleichen Basisdateinamen verwaltet werden sollen. max_rollover_files ist vom Datentyp int und ist größer als 1. Dieser Parameter ist nur dann gültig, wenn die Option TRACE_FILE_ROLLOVER angegeben wird. Wenn max_rollover_files angegeben wird, wird von SQL Server versucht, nicht mehr als max_rollover_files Ablaufverfolgungsdateien beizubehalten, indem die älteste Ablaufverfolgungsdatei gelöscht wird, bevor eine neue Ablaufverfolgungsdatei geöffnet wird. In SQL Server wird das Alter von Ablaufverfolgungsdateien durch das Anfügen einer Nummer an den Basisdateinamen nachverfolgt.

    Wenn z. B. der trace_file-Parameter als "c:\mytrace" angegeben wird, ist eine Datei mit dem Namen "c:\mytrace_123.trc" älter als eine Datei mit dem Namen "c:\mytrace_124.trc". Wenn max_rollover_files auf 2 festgelegt ist, löscht SQL Server die Datei "c:\mytrace_123.trc" vor dem Erstellen der Ablaufverfolgungsdatei "c:\mytrace_125.trc".

    Beachten Sie, dass in SQL Server jede Datei nur einmal zu löschen versucht wird und eine Datei nicht gelöscht werden kann, wenn diese von einem anderen Prozess verwendet wird. Wenn in einer anderen Anwendung Ablaufverfolgungsdateien verwendet werden, während die Ablaufverfolgung ausgeführt wird, werden diese Ablaufverfolgungsdateien daher möglicherweise von SQL Server im Dateisystem belassen.

Rückgabecodewerte

In der folgenden Tabelle werden die Codewerte beschrieben, die die Benutzer nach Abschluss der gespeicherten Prozedur möglicherweise erhalten.

Rückgabecode

Beschreibung

0

Kein Fehler.

1

Unbekannter Fehler.

10

Ungültige Optionen. Wird zurückgegeben, wenn angegebene Optionen inkompatibel sind.

12

Datei nicht erstellt.

13

Nicht genügend Arbeitsspeicher. Wird zurückgegeben, wenn nicht genügend Arbeitsspeicher zum Ausführen der angegebenen Aktion verfügbar ist.

14

Ungültige Beendigungszeit. Wird zurückgegeben, wenn die angegebene Beendigungszeit bereits verstrichen ist.

15

Ungültige Parameter. Wird zurückgegeben, wenn der Benutzer inkompatible Parameter angegeben hat.

Hinweise

sp_trace_create ist eine gespeicherte Prozedur von SQL Server, die viele der zuvor von den erweiterten gespeicherten Prozeduren xp_trace_* ausgeführten Aktionen ausführt, die in früheren Versionen von SQL Server verfügbar waren. Verwenden Sie sp_trace_create anstelle von:

  • xp_trace_addnewqueue

  • xp_trace_setqueuecreateinfo

  • xp_trace_setqueuedestination

sp_trace_create erstellt nur eine Ablaufverfolgungsdefinition. Diese gespeicherte Prozedur kann nicht verwendet werden, um eine Ablaufverfolgung zu starten oder zu ändern.

Parameter aller gespeicherten Prozeduren der SQL-Ablaufverfolgung (sp_trace_xx) haben eine strikte Typbindung. Wenn diese Parameter nicht mit den richtigen Datentypen für Eingabeparameter aufgerufen werden, wie in der Argumentbeschreibung angegeben, gibt die gespeicherte Prozedur einen Fehler zurück.

Für sp_trace_create muss das SQL Server-Dienstkonto über die Schreibberechtigung für den Ordner der Ablaufverfolgungsdatei verfügen. Wenn das SQL Server-Dienstkonto kein Administrator auf dem Computer ist, auf dem die Ablaufverfolgungsdatei gespeichert ist, müssen Sie dem SQL Server-Dienstkonto explizit die Schreibberechtigung erteilen.

HinweisHinweis

Sie können die mit sp_trace_create erstellte Ablaufverfolgungsdatei automatisch in eine Tabelle laden, indem Sie die fn_trace_gettable-Systemfunktion verwenden. Informationen zum Verwenden dieser Systemfunktion finden Sie unter sys.fn_trace_gettable (Transact-SQL).

Ein Beispiel zum Verwenden gespeicherter Prozeduren der Ablaufverfolgung finden Sie unter Erstellen einer Ablaufverfolgung (Transact-SQL).

TRACE_PRODUCE_BLACKBOX hat die folgenden Eigenschaften:

  • Es handelt sich um eine Rollover-Ablaufverfolgung. Der Standardwert für file_count ist 2, kann aber vom Benutzer mit der filecount-Option überschrieben werden.

  • Der Standardwert für file_size ist, wie bei anderen Ablaufverfolgungen, 5 MB und kann geändert werden.

  • Es kann kein Dateiname angegeben werden. Die Datei wird gespeichert als: N'%SQLDIR%\MSSQL\DATA\blackbox.trc'

  • Nur die folgenden Ereignisse und deren Spalten sind in der Ablaufverfolgung enthalten:

    • RPC:Starting

    • BatchStarting

    • Ausnahme

    • Attention

  • Für diese Ablaufverfolgung können Ereignisse oder Spalten nicht hinzugefügt oder entfernt werden.

  • Filter können für diese Ablaufverfolgung nicht angegeben werden.

Berechtigungen

Benutzer müssen über die ALTER TRACE-Berechtigung verfügen.

Siehe auch

Verweis

sp_trace_generateevent (Transact-SQL)

sp_trace_setevent (Transact-SQL)

sp_trace_setfilter (Transact-SQL)

sp_trace_setstatus (Transact-SQL)

Konzepte

SQL-Ablaufverfolgung