Хранимая процедура sp_trace_create (Transact-SQL)

  • Статья

Создает определение трассировки. Новая трассировка будет находиться в остановленном состоянии.

Важное примечаниеВажно!

В будущей версии Microsoft SQL Server эта возможность будет удалена. Избегайте использования этой возможности в новых разработках и запланируйте изменение существующих приложений, в которых она применяется. Вместо этого используйте расширенные события.

Значок ссылки на раздел Синтаксические обозначения в Transact-SQL

Синтаксис

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

Аргументы

  • [ @traceid= ] trace_id
    Номер, назначенный Microsoft SQL Server новой трассировке. Любое значение, предложенное пользователем, не будет учитываться. Аргумент trace_id имеет тип int и значение по умолчанию NULL. Пользователь применяет значение trace_id, чтобы идентифицировать, редактировать и управлять трассировкой, определенной данной хранимой процедурой.

  • [ @options= ] option_value
    Указывает набор параметров для трассировки. Аргумент option_value имеет тип int и не имеет значения по умолчанию. Пользователи могут выбирать сочетания этих параметров путем указания их суммарного значения. Например, чтобы установить параметры TRACE_FILE_ROLLOVER и SHUTDOWN_ON_ERROR, достаточно задать значение 6 для аргумента option_value.

    В следующей таблице содержится список параметров, их значений и описаний.

    Имя параметра

    Значение параметра

    Описание

    TRACE_FILE_ROLLOVER

    2

    Указывает, что при достижении размера аргумента max_file_size текущий трассировочный файл закрывается и создается новый. Все новые записи будут сохраняться в новый файл. Новый файл будет иметь то же имя, что и предыдущий, но в конец имени будет добавлено число, показывающее его порядковый номер. Например, если изначально трассировочный файл назывался filename.trc, то следующий трассировочный файл будет называться filename_1.trc, имя следующего трассировочного файла будет filename_2.trc и т. д.

    По мере увеличения количества трассировочных файлов число, добавляемое в конец имени файла, будет также последовательно увеличиваться.

    SQL Server по умолчанию в качестве значения аргумента max_file_size использует 5 МБ, если он указан без указания значения аргумента max_file_size.

    SHUTDOWN_ON_ERROR

    4

    Указывает, что если трассировка не может быть записана в файл по какой-либо причине, SQL Server останавливается. Этот параметр полезен в случае проведения трассировок по проверке безопасности.

    TRACE_PRODUCE_BLACKBOX

    8

    Указывает, что запись последних 5 МБ трассировочных сведений, формируемых сервером, будет сохранена на сервере. Значение параметра TRACE_PRODUCE_BLACKBOX несовместимо со всеми другими.

  • [ @tracefile= ] 'trace_file'
    Указывает расположение и имя файла, в который будет сохраняться трассировка. Аргумент trace_file имеет тип nvarchar(245) и не имеет значения по умолчанию. Аргумент trace_file может быть как именем локального каталога (например, N 'C:\MSSQL\Trace\trace.trc'), так и путем в формате UNC к общему ресурсу (N'\\Имя_сервера\Имя_общего_ресурса\Каталог\trace.trc').

    SQL Server добавляет расширение TRC ко всем именам файлов трассировки. Если указаны аргументы TRACE_FILE_ROLLOVER и max_file_size, SQL Server создаст новый файл трассировки, когда предыдущий файл достигнет своего максимального размера. Новый файл будет иметь то же имя, что и оригинальный, но с добавлением _n для определения очередности, начиная с 1. Например, если имя первого трассировочного файла filename.trc, второй файл будет называться filename_1.trc.

    Если используется параметр TRACE_FILE_ROLLOVER, рекомендуется не использовать в имени исходного файла трассировки символы подчеркивания. Если используются символы подчеркивания, выполняются следующие действия.

    • Приложение SQL Server Profiler не загружает файлы продолжения автоматически и не предлагает загрузить эти файлы (если настроен один из этих вариантов работы с файлами продолжения).

    • Функция fn_trace_gettable не загружает файлы продолжения (если этот параметр указан в аргументе number_files), в которых имя исходного файла трассировки завершается подчеркиванием и числовым значением. (Это не относится к подчеркиваниям и числам, которые автоматически добавляются, когда выполняется переключение на файл продолжения.)

    ПримечаниеПримечание

    В качестве временного решения в обоих случаях можно переименовать файлы трассировки, исключив подчеркивания из имени исходного файла. Например, если исходный файл имеет имя my_trace.trc, а файл продолжения имеет имя my_trace_1.trc, можно задать для файлов имена mytrace.trc и mytrace_1.trc перед открытием в приложении Приложение SQL Server Profiler.

    Аргумент trace_file не может быть указан при использовании параметра TRACE_PRODUCE_BLACKBOX.

  • [ @maxfilesize= ] max_file_size
    Указывает максимальный размер файла трассировки в мегабайтах (МБ). Аргумент max_file_size имеет тип bigint и значение по умолчанию 5.

    Если этот аргумент указан без параметра TRACE_FILE_ROLLOVER, трассировка остановит запись в файл, когда используемое дисковое пространство достигнет значения, установленного в аргументе max_file_size.

  • [ @stoptime= ] 'stop_time'
    Задает дату и время остановки трассировки. Аргумент stop_time имеет тип datetime и значение по умолчанию NULL. Если указано значение NULL, трассировка будет работать до тех пор, пока не будет остановлена вручную или пока не остановится сервер.

    Если указаны аргументы stop_time и max_file_size, а параметр TRACE_FILE_ROLLOVER не указан, трассировка остановится либо в указанный момент времени, либо по достижении максимального размера файла. Если указаны аргументы stop_time, max_file_size и параметр TRACE_FILE_ROLLOVER, трассировка остановится в указанное время, если при этом не будет исчерпано свободное пространство на диске.

  • [ @filecount= ] 'max_rollover_files'
    Указывает максимальное количество файлов трассировки, образованных с одним базовым именем. Аргумент max_rollover_files имеет тип int со значением >1. Этот аргумент имеет смысл только в случае, если указан параметр TRACE_FILE_ROLLOVER. Если указан аргумент max_rollover_files, SQL Server будет хранить файлы трассировки в количестве не более max_rollover_files, удаляя самые старые файлы перед открытием новых. SQL Server отслеживает возраст файлов трассировки, добавляя число в конец базового имени файла.

    Например, если в качестве аргумента trace_file указано «c:\mytrace», файл с именем «c:\mytrace_123.trc» будет старше файла с именем «c:\mytrace_124.trc». Если аргумент max_rollover_files установлен в 2, SQL Server удаляет трассировочный файл «c:\mytrace_123.trc» перед созданием трассировочного файла «c:\mytrace_125.trc».

    Обратите внимание, что SQL Server пытается удалить файл только один раз и не может удалить файл, используемый другим процессом. Поэтому, если другое приложение работает с файлами трассировки во время трассировки, SQL Server может оставить эти файлы в файловой системе.

Значения кода возврата

В следующей таблице описаны значения кодов, которые могут быть возвращены пользователю при завершении хранимой процедуры.

Код возврата

Описание

0

Ошибок нет.

1

Неизвестная ошибка.

10

Недопустимые параметры. Возвращается, если указанные параметры несовместимы.

12

Файл не создан.

13

Нехватка памяти. Возвращается, если для выполнения указанного действия недостаточно памяти.

14

Недопустимое время останова. Возвращается, если указанное время останова уже прошло.

15

Недопустимые аргументы. Возвращается, если пользователь ввел несовместимые аргументы.

Замечания

Хранимая процедура sp_trace_create в SQL Server выполняет большинство действий, которые ранее выполнялись расширенной хранимой процедурой xp_trace_*, доступной в более ранних версиях SQL Server. Используйте процедуру sp_trace_create вместо:

  • xp_trace_addnewqueue

  • xp_trace_setqueuecreateinfo

  • xp_trace_setqueuedestination

Процедура sp_trace_create создает только определение трассировки. Эта хранимая процедура не может быть использована для запуска или изменения трассировки.

Аргументы всех хранимых процедур трассировки SQL (sp_trace_xx) строго типизированы. Если эти аргументы не вызываются вместе с правильными типами данных входных аргументов, как указано в описании аргумента, хранимая процедура возвращает ошибку.

Для вызова процедуры sp_trace_create учетная запись службы SQL Server должна иметь разрешение на запись в папку с файлами трассировки. Если учетная запись службы SQL Server не имеет прав администратора на компьютере, на котором находится файл трассировки, необходимо предоставить ей разрешение на запись.

ПримечаниеПримечание

Трассировочный файл, созданный процедурой sp_trace_create, можно автоматически загружать в таблицу с помощью системной функции fn_trace_gettable. Дополнительные сведения об использовании этой системной функции см. в разделе sys.fn_trace_gettable (Transact-SQL).

Пример использования хранимых процедур трассировки см. в разделе создать трассировку (Transact-SQL).

TRACE_PRODUCE_BLACKBOX имеет следующие характеристики.

  • Это продолжение трассировки. По умолчанию для file_count задается значение 2, но его может изменить пользователь с помощью параметра filecount.

  • Как и для других трассировок, по умолчанию для file_size задается значение 5 МБ. Оно может быть изменено.

  • Не удалось задать имя файла. Файл будет сохранен как N'%SQLDIR%\MSSQL\DATA\blackbox.trc'

  • В трассировке будут содержаться только следующие события и их столбцы.

    • Запуск RPC

    • Начало пакета

    • Исключение

    • Внимание

  • События или столбцы нельзя добавить или удалить из данной трассировки.

  • Для данной трассировки нельзя указать фильтры.

Разрешения

Пользователь должен иметь разрешение ALTER TRACE.

См. также

Справочник

sp_trace_generateevent (Transact-SQL)

Хранимая процедура sp_trace_setevent (Transact-SQL)

sp_trace_setfilter (Transact-SQL)

sp_trace_setstatus (Transact-SQL)

Основные понятия

SQL-трассировка