sp_trace_create (Transact-SQL)

创建跟踪定义。新的跟踪将处于停止状态。

主题链接图标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
    MicrosoftSQL Server 为新跟踪分配的编号。用户提供的任何输入都被忽略。trace_id 的数据类型为 int,默认为 NULL。用户使用 trace_id 值标识、修改和控制此存储过程定义的跟踪。

  • [ @options= ] option_value
    指定为跟踪设置的选项。option_value 的数据类型为 int,无默认设置。用户可以通过指定所选出选项值之和来选择这些选项的组合。例如,若要启用 TRACE_FILE_ROLLOVER 和 SHUTDOWN_ON_ERROR,请为 option_value 指定 6

    下表列出了选项、说明和选项值。

    选项名

    选项值

    说明

    TRACE_FILE_ROLLOVER

    2

    指定当达到 max_file_size 时,将关闭当前跟踪文件并创建新文件。所有新记录都将写入新文件。新文件将与前一个文件同名,但是在文件名后将附加一个整数以指示其序列。例如,如果原始跟踪文件命名为 filename.trc,则下个跟踪文件命名为 filename_1.trc,再下一个跟踪文件命名为 filename_2.trc,等等。

    随着更多滚动更新跟踪文件的创建,附加到文件名的整数值继续增加。

    如果指定该选项时未指定 max_file_size 的值,则 SQL Server 使用 max_file_size 的默认值 (5 MB)。

    SHUTDOWN_ON_ERROR

    4

    指定无论任何原因,如果不能将跟踪写入文件,则 SQL Server 将关闭。执行安全审核跟踪时,该选项很有用。

    TRACE_PRODUCE_BLACKBOX

    8

    指定服务器产生的最后 5 MB 跟踪信息记录将由服务器保存。TRACE_PRODUCE_BLACKBOX 与所有其他选项不兼容。

  • [ @tracefile= ] 'trace_file'
    指定跟踪将写入的位置和文件名。trace_file 的数据类型为 nvarchar(245),没有默认设置。trace_file 可以是本地目录(如 N 'C:\MSSQL\Trace\trace.trc'),也可以是到共享或路径 (N'\\Servername\Sharename\Directory\trace.trc') 的 UNC。

    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,则您可以在 SQL Server Profiler 中打开文件之前将这两个文件重命名为 mytrace.trcmytrace_1.trc

    在使用 TRACE_PRODUCE_BLACKBOX 选项时无法指定 trace_file。

  • [ @maxfilesize= ] max_file_size
    指定跟踪文件可以增长到的最大文件大小 (MB)。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_125.trc”前删除文件“c:\mytrace_123.trc”。

    请注意,SQL Server 仅尝试删除每个文件一次,且不能删除另一进程正在使用的文件。因此,如果在跟踪运行时另一应用程序正在使用跟踪文件,则 SQL Server 会将这些跟踪文件保留在文件系统中。

返回代码值

下表说明在存储过程完成后用户可能获得的代码值。

返回代码

说明

0

没有错误。

1

未知错误。

10

无效选项。指定的选项不兼容时返回此代码。

12

文件未创建。

13

内存不足。在没有足够内存执行指定的操作时返回此代码。

14

无效停止时间。在指定的停止时间已发生时返回此代码。

15

参数无效。在用户已提供不兼容的参数时返回此代码。

注释

sp_trace_create 是一个 SQL Server 存储过程,它执行以前由 SQL Server 早期版本中的 xp_trace_* 扩展存储过程执行的许多操作。使用 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 服务帐户不是跟踪文件所在计算机上的管理员,则必须将写入权限显式授予 SQL Server 服务帐户。

注意注意

通过使用 fn_trace_gettable 系统函数,可以将使用 sp_trace_create 创建的跟踪文件自动加载到表中。有关如何使用此系统函数的信息,请参阅 fn_trace_gettable (Transact-SQL)

有关使用跟踪存储过程的示例,请参阅如何创建跟踪 (Transact-SQL)

TRACE_PRODUCE_BLACKBOX 具有以下特征:

  • 它属于滚动更新跟踪。file_count 默认为 2,但用户可以使用 filecount 选项覆盖此值。

  • file_size 与其他跟踪一样默认为 5 MB 并且可以更改。

  • 不能指定文件名。文件将保存为:N'%SQLDIR%\MSSQL\DATA\blackbox.trc'

  • 跟踪中仅包含以下事件和它们的列:

    • RPC starting

    • Batch starting

    • Exception

    • Attention

  • 无法在此跟踪中添加或删除事件或列。

  • 不能为此跟踪指定筛选器。

权限

用户必须拥有 ALTER TRACE 权限。

更改历史记录

更新的内容

添加了对 @tracefile 参数说明的建议,以便避免在原始跟踪文件名中使用下划线字符。