sp_trace_create (Transact-SQL)

  • 项目

适用于：SQL Server

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

重要

在 SQL Server的未来版本中将删除此功能。 请避免在新的开发工作中使用该功能，并着手修改当前还在使用该功能的应用程序。 请改用扩展事件。

Transact-SQL 语法约定

语法

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

参数

[ @traceid = ] traceid OUTPUT

SQL Server 分配给新跟踪的数字。 将忽略任何用户提供的输入。 @traceid是 int 类型的 OUTPUT 参数，默认值为 NULL. 用户使用 @traceid 值来标识、修改和控制由此存储过程定义的跟踪。

[ @options = ] 选项

指定为跟踪设置的选项。 @options 为 int，无默认值。 用户可以通过指定所选出选项之和来选择这些选项的组合。 例如，若要同时打开选项TRACE_FILE_ROLLOVER，并SHUTDOWN_ON_ERROR指定6@options。

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

选项名称 选项值 说明
TRACE_FILE_ROLLOVER 2 指定到达@filecount时，将关闭当前跟踪文件，并创建一个新文件。 所有新记录将写入新文件。 新文件的名称与上一个文件相同，但追加了一个整数以指示其序列。 例如，如果原始跟踪文件命名 filename.trc，则下一个跟踪文件命名 filename_1.trc，以下跟踪文件为 filename_2.trc等。

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

如果指定此选项而不指定@filecount值，则 SQL Server 将使用默认值 @filecount （5 MB）。
SHUTDOWN_ON_ERROR 4 指定如果由于任何原因无法将跟踪写入文件，SQL Server 将关闭。 执行安全审核跟踪时，该选项很有用。
TRACE_PRODUCE_BLACKBOX 8 指定服务器生成的最后 5 MB 跟踪信息的记录由服务器保存。 TRACE_PRODUCE_BLACKBOX 与所有其他选项不兼容。

[ @tracefile = ] N'tracefile'

指定将跟踪写入到的位置和文件名。 @tracefile为 nvarchar（245），没有默认值。 @tracefile可以是本地目录（例如N'C:\MSSQL\Trace\trace.trc'）或 UNC 到共享或路径（例如N'\\<servername>\<sharename>\<directory>\trace.trc'）。

SQL Server 将 .trc 扩展追加到所有跟踪文件名。 如果指定了 TRACE_FILE_ROLLOVER 选项和 @filecount ，则当原始跟踪文件增长到其最大大小时，SQL Server 将创建新的跟踪文件。 新文件的名称与原始文件相同，但追加 _n 以指示其序列，从 1开头。 例如，如果第一个跟踪文件命名 filename.trc，则第二个跟踪文件命名 filename_1.trc。

如果使用此选项 TRACE_FILE_ROLLOVER ，建议不要在原始跟踪文件名中使用下划线字符。 如果您使用了下划线，则会发生以下行为：

  • SQL Server Profiler 不会自动加载或提示加载滚动更新文件（如果配置了其中任一文件滚动更新选项）。

  • sys.fn_trace_gettable函数不会加载滚动更新文件（使用 @number_files 参数指定），其中原始文件名以下划线和数值结尾。 （这不适用于文件滚动更新时自动追加的下划线和数字。

注意

作为对这两个行为的解决方法，您可以重命名这些文件以便删除原始文件名中的下划线。 例如，如果原始文件命名 my_trace.trc，并且滚动更新文件已命名 my_trace_1.trc，则可以在 SQL Server Profiler 中打开文件之前将文件重命名为 mytrace.trc 该文件 mytrace_1.trc 。

使用选项时TRACE_PRODUCE_BLACKBOX，无法指定@tracefile。

[ @maxfilesize = ] maxfilesize

指定跟踪文件可以增长到的最大文件大小 (MB)。 @maxfilesize为 bigint，默认值为 5.

如果未指定此参数，TRACE_FILE_ROLLOVER则当使用的磁盘空间超过@maxfilesize指定的量时，跟踪将停止记录到文件。

[ @stoptime = ] 'stoptime'

指定停止跟踪的日期和时间。 @stoptime为日期/时间，默认值为 NULL. 如果 NULL跟踪在手动停止或服务器关闭之前运行。

如果同时指定了@stoptime和@maxfilesize，并且TRACE_FILE_ROLLOVER未指定，则达到指定的停止时间或最大文件大小时，跟踪顶部会达到跟踪顶端。 如果 @stoptime、 @maxfilesize并 TRACE_FILE_ROLLOVER 指定跟踪，则跟踪会在指定的停止时间停止，假设跟踪不会填满驱动器。

[ @filecount = ] 'filecount'

指定使用同一基准文件名维护的最大跟踪文件数。 @filecount是 int，大于 1。 仅当指定了选项时， TRACE_FILE_ROLLOVER 此参数才有效。 指定@filecount后，SQL Server 会尝试通过在打开新跟踪文件之前删除最早的跟踪文件来维护不超过@filecount跟踪文件。 SQL Server 通过将数字追加到基本文件名来跟踪跟踪文件的年龄。

例如，将@tracefile参数指定为C:\mytrace时，具有名称C:\mytrace_123.trc的文件早于名称C:\mytrace_124.trc的文件。 如果@filecount设置为，SQL Server 会在创建跟踪文件之前删除该文件C:\mytrace_123.trcC:\mytrace_125.trc。2

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_*）的参数都严格类型化。 如果这些参数不是使用正确的输入参数数据类型（正如参数说明中指定的一样）调用的，则存储过程会返回错误。

对于 sp_trace_create，SQL Server 服务帐户必须对跟踪文件文件夹具有 写入 权限。 如果 SQL Server 服务帐户不是跟踪文件所在计算机上的管理员，则必须显式授予对 SQL Server 服务帐户的写入权限。

注意

可以使用系统函数自动将创建的 sp_trace_create 跟踪文件加载到表中 fn_trace_gettable 。 有关详细信息，请参阅 sys.fn_trace_gettable。

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

TRACE_PRODUCE_BLACKBOX 具有以下特征：

  • 这是滚动更新跟踪。 默认@filecount为 2，但用户可以使用@filecount选项重写。

  • 与其他跟踪一样，默认 @maxfilesize为 5 MB，可以更改。

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

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

    • RPC 正在启动
    • 批处理启动
    • Exception
    • Attention

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

  • 无法为此跟踪指定筛选器。

权限

需要 ALTER TRACE 权限。

相关内容