xp_trace_setuserfilter (T-SQL)

Specifies the Microsoft® SQL Server™ username filter, or the SQL Server usernames to include or exclude for the events specified. SQL Server captures the required information, configured by executing xp_trace_seteventclassrequired, for the included usernames, if any, and does not capture the required information for the excluded usernames, if any.

Syntax

xp_trace_setuserfilter {queue_handle, 'include_users', 'exclude_users'}

Arguments

queue_handle

Is an integer representing the handle for the trace queue. queue_handle is used to reference the trace queue and is placed in an output parameter by xp_trace_addnewqueue.

'include_users'

Is a string value representing the username include filter. The username include filter indicates the usernames, separated by semicolons (;), that should be considered when capturing data previously determined by sp_seteventclassrequired. The % wildcard character can be used in specifying the usernames to include in the trace. If NULL, there are no restrictions on usernames to include for the specified event classes.

---

Note SQL Server usernames are those usernames used with SQL Server Authentication rather than Windows NT Authentication. Usernames can be obtained from the syslogins system table.

---

'exclude_users'

Is a string value representing the username exclude filter. The username exclude filter indicates the usernames, separated by semicolons (;), that should not be considered when capturing data previously determined by sp_seteventclassrequired. The % wildcard character can be used in specifying the usernames to exclude in the trace. If NULL, there are no excluded usernames for the specified event classes.

Return Code Values

0 (success) or >1 (failure)

Result Sets

xp_trace_setuserfilter returns this message:

The command(s) completed successfully.

Remarks

When you specify one or more SQL Server usernames to include, all other SQL Server usernames are excluded.

Permissions

Execute permissions for xp_trace_setuserfilter default to members of the sysadmin fixed server role but can be granted to other users.

Examples

This example configures the user filter value information for trace queue. All events for user janetl are traced and no users are excluded.

USE master

DECLARE @queue_handle int, @column_value int

SET @column_value = 16|32|8192|128|512

EXEC xp_trace_addnewqueue 1000,

    5,

    95,

    90,

    @column_value,

    @queue_handle OUTPUT

EXEC xp_trace_setuserfilter @queue_handle,

    'janetl%',

    NULL

See Also