feat: sp_HumanEvents Add Wildcard Support, A Few Fixes, And Event Type Check Handling

[mattcargile]

feat: sp_HumanEvents Add Wildcard Support, A Few Fixes, And Event Type Check Handling
Closes #639 , #640
Wildcard support for the below parameters:
@database_name
@object_name
@username
@client_hostname
@client_app_name
Remove ending periods on @help for for @cleanup and @gimme_danger
Bug in substring for @view_sql
Bug that Waits session doesn't support object_name
Use @@Procid for @help query
Use Lower on event type to avoid redundancy
Add event type and pattern variables to centralize checks
Format three IF blocks

Considerations For Maintainers

1. Is @use_like parameter appropriate? Should auto opt-in without an opt-out?
2. Are you ok supporting the bracket wildcard feature too?
3. Is leaving out wildcard support for a single underscore ok?
4. Overall attempts are made to match @database_name and/or @object_name with an exact match first even when wild card characters are found to hopefully not break folks and be helpfu. Is this ok?
5. Should we incorporate @gimme_danger check for predicates close to 1000 characters? The limit is 3000 characters and MSSQL will complain. Is that enough?
6. Are you ok taking this without wildcard support for @object_schema?
7. Are you able to reproduce the error for @event_type = N'waits' using @object_name? Should the procedure raise an error with this or continue as is?
8. Is it appropriate for the queries deriving the object_id for the blocking @event_type to filter out the is_ms_shipped objects. Users could get around this if not using wildcard because OBJECT_ID is used instead of a query to sys.objects.

Work To Be Done

1. Generate a set of procedure executions of the varying scenarios for testing.
2. Update Install All script. Automatically happens upon merge
3. Update help docs

[erikdarlingdata]

1. Is @use_like parameter appropriate? Should auto opt-in without an opt-out?

I don't understand why this is a parameter and not a local variable that's set internally when a percent sign is present in a wildcard searchable parameter.

2. Are you ok supporting the bracket wildcard feature too?

I don't know what you're asking here. If there are any major bugs with this, I'll likely pull out the changes and assign the issue to you. You will effectively own this feature.

3. Is leaving out wildcard support for a single underscore ok?

I guess? It's difficult to gauge what use cases users will want for this. It might be good enough as-is. Someone might ask for it later.

4. Overall attempts are made to match @database_name and/or @object_name with an exact match first even when wild card characters are found to hopefully not break folks and be helpful. Is this ok?

If there's a percent, we shouldn't bother with exact matches. Just get a count of wildcard matches and bail if it's zero. It should be a different code path.

5. Should we incorporate @gimme_danger check for predicates close to 1000 characters? The limit is 3000 characters and MSSQL will complain. Is that enough?

I don't understand this one at all. Can you clarify?

6. Are you ok taking this without wildcard support for @object_schema?

Yes, but I don't generally have a use for this feature on my own. Again, it comes down to how people end up using it. But there should be an explicit check for people trying to use a wildcard here and some sort of message raised to note it's not supported.

7. Are you able to reproduce the error for @event_type = N'waits' using @object_name? Should the procedure raise an error with this or continue as is?

No, I have not tested or reviewed any of the actual code here. I'm not sure when I'll have time to. What is the error?

8. Is it appropriate for the queries deriving the object_id for the blocking @event_type to filter out the is_ms_shipped objects. Users could get around this if not using wildcard because OBJECT_ID is used instead of a query to sys.objects.

No, not at all. There are many blocking events that occur on system objects that are valid to look at.

[mattcargile]

1. Is @use_like parameter appropriate? Should auto opt-in without an opt-out?

I don't understand why this is a parameter and not a local variable that's set internally when a percent sign is present in a wildcard searchable parameter.

Do we want to support users with wild card characters in their object names, basically. Should there be a hard disable on this wildcard feature for users at the procedure level. Or should users be made aware of certain parameters being "wildcard-aware" and to act accordingly to escape the wildcard characters. Percent signs or brackets in object names isn't super common, of course. Underscores are common though.

2. Are you ok supporting the bracket wildcard feature too?

I don't know what you're asking here. If there are any major bugs with this, I'll likely pull out the changes and assign the issue to you. You will effectively own this feature.

One can have a pattern of N'db[tp] to match both dbp and dbt, as I assume you know. What is your take on if we can/should support the wildcard feature if a user uses a percent sign or both the opening and closing bracket. There is also potentially something to be said for having the feature disabled by default and having the parameter @use_like or similar to allow the user to enable it. It can be challenging to gauge the user's intent exactly.

There is also something to be said for defaulting to always using the like predicate compare for applicable parameters similar to how sp_WhoIsActive works with @filter. Now the behavior of LIKE has subtle differences to sqlserver.like_i_sql_unicode_string, namely the forced case insensitivity where LIKE would respect a case sensitive collation. I don't believe there is a case sensitive like predicate available.

3. Is leaving out wildcard support for a single underscore ok?

I guess? It's difficult to gauge what use cases users will want for this. It might be good enough as-is. Someone might ask for it later.

My thought process there was that the underscore is pretty common in object names. I would guess defaulting to the like pattern matching could produce unexpected results. N'db_name' would match both N'dbsname' and N'db_name'. Probably more of an edge case there.

4. Overall attempts are made to match @database_name and/or @object_name with an exact match first even when wild card characters are found to hopefully not break folks and be helpful. Is this ok?

If there's a percent, we shouldn't bother with exact matches. Just get a count of wildcard matches and bail if it's zero. It should be a different code path.

Ok, that does get at some of my comments above too. It does sound like I've gone more complicated and we only want to support the percent sign only.

5. Should we incorporate @gimme_danger check for predicates close to 1000 characters? The limit is 3000 characters and MSSQL will complain. Is that enough?

I don't understand this one at all. Can you clarify?

So the documentation states a 3000 character limit on the WHERE predicate expression. If we support @object_name wildcarding then there is a chance the predicate will be very large as we have to generate a predicate out of the returned object_id for the blocking event. This causes SQL Server to error out with the below.

Msg 25716, Level 16, State 1, Line 43
The predicate on event, "sqlserver.blocked_process_report", exceeds the maximum length of 3000 characters.

Should we force users to use the @gimme_danger flag if there returned object_id output is too large? Or should we let the error propagate straight from SQL Server? Or somewhere in the middle where we count the characters of the predicate and error out before creating the session?

6. Are you ok taking this without wildcard support for @object_schema?

Yes, but I don't generally have a use for this feature on my own. Again, it comes down to how people end up using it. But there should be an explicit check for people trying to use a wildcard here and some sort of message raised to note it's not supported.

Ok, I'll work on that.

7. Are you able to reproduce the error for @event_type = N'waits' using @object_name? Should the procedure raise an error with this or continue as is?

No, I have not tested or reviewed any of the actual code here. I'm not sure when I'll have time to. What is the error?

Consider the below execution on version 6.6.

USE [master];
GO
EXECUTE dbo.sp_HumanEvents
    @event_type = N'wait',
    @database_name = N'master',
    @object_name = N'sp_WhoIsActive',
    @seconds_sample = 2;
GO

It returns the below error.

Msg 25706, Level 16, State 8, Line 59
The event attribute or predicate source, "object_name", could not be found.

Should probably either RAISERROR and RETURN or atleast RAISERROR to alert the user that @object_name is not supported. (NOTE: Maybe this should be in another PR.)

8. Is it appropriate for the queries deriving the object_id for the blocking @event_type to filter out the is_ms_shipped objects. Users could get around this if not using wildcard because OBJECT_ID is used instead of a query to sys.objects.

No, not at all. There are many blocking events that occur on system objects that are valid to look at.

Sounds good. I pushed this change.

[erikdarlingdata]

@mattcargile My advice here is to design this in the simplest way that allows you to accomplish the feature functionality that you're after. You're getting quite into the weeds with a lot of this.

Keep in mind that the goal of this procedure is to make getting extended events set up and running for specific tasks very simple for people. It's okay for things to be dumbed down, as long as the results are correct.

Aim to make life easier for the bottom quintile, not to make things impressive for the top end (they're not using this thing anyway).

The issue with object names/waits is indeed separate. It should not be included as a predicate there.