通过

  • 项目

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.trc 和 mytrace_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 参数说明的建议，以便避免在原始跟踪文件名中使用下划线字符。