sp_trace_generateevent (Transact-SQL)

  • Article

S’applique à :SQL ServerAzure SQL DatabaseAzure SQL Managed Instance

Crée un événement défini par l'utilisateur. L’événement peut être collecté à l’aide de la trace SQL ou des événements étendus.

Remarque

Cette procédure stockée n’est pas déconseillée. Toutes les autres procédures stockées associées à SQL Trace sont déconseillées.

Conventions de la syntaxe Transact-SQL

Syntaxe

sp_trace_generateevent
    [ @eventid = ] eventid
    [ , [ @userinfo = ] N'userinfo' ]
    [ , [ @userdata = ] userdata ]
[ ; ]

Arguments

[ @eventid = ] eventid

ID de l’événement à déclencher. @eventid est int, sans valeur par défaut. L’ID doit se trouver dans la plage à partir de 8291 l’inclusion. Cette plage représente les événements définis par l’utilisateur. Dans SQL Trace, utilisez sp_trace_setevent pour ajouter un événement avec cet ID à une trace pour capturer les événements avec le même ID déclenché à partir de cette procédure stockée.

[ @userinfo = ] 'userinfo'

Chaîne facultative définie par l’utilisateur. @userinfo est nvarchar(128), avec la valeur par défaut NULL.

[ @userdata = ] userdata

Données facultatives définies par l’utilisateur pour l’événement. @userdata est varbinary(8000), avec la valeur par défaut 0x.

Valeurs des codes de retour

Le tableau suivant décrit les valeurs de code de retour que les utilisateurs peuvent obtenir, après la fin de la procédure stockée.

Code de retour Description
0 Aucune erreur.
1 Erreur inconnue.
3 L’événement spécifié n’est pas valide. L’événement peut ne pas exister ou il n’est pas approprié pour la procédure stockée.
13 Mémoire insuffisante. Retourné lorsqu’il n’y a pas suffisamment de mémoire pour effectuer l’action spécifiée.

Notes

Pour capturer les événements déclenchés par cette procédure stockée à l’aide d’événements étendus, ajoutez l’événement user_info à une session d’événements. Pour plus d’informations, consultez CREATE EVENT SESSION. L’événement user_info est déclenché pour toute valeur d’ID d’événement définie par l’utilisateur passée au @eventid paramètre.

Seuls les numéros d’ID des événements définis par l’utilisateur peuvent être utilisés avec sp_trace_generateevent. Une erreur est générée si un autre numéro d’ID d’événement est utilisé.

Les paramètres de cette procédure stockée sont strictement typés. Si le type de données de la valeur passée à un paramètre ne correspond pas au type de données de paramètre spécifié dans sa description, la procédure stockée retourne une erreur.

sp_trace_generateevent effectue de nombreuses actions précédemment exécutées par les xp_trace_* procédures stockées étendues. Utilisez sp_trace_generateevent au lieu de xp_trace_generate_event.

Autorisations

Dans SQL Server et dans Azure SQL Managed Instance, nécessite l’autorisation ALTER TRACE . Dans Azure SQL Database, nécessite l’appartenance au public rôle de base de données.

Exemples

L’exemple suivant déclenche un événement défini par l’utilisateur lorsqu’une ligne est insérée dans une table. L’événement contient les données insérées dans la table.

Pour collecter l’événement déclenché par cet exemple, créez une session d’événements étendue et incluez l’événement user_info , ou créez une trace SQL et incluez l’événement UserConfigurable:0 .

-- Create a table
DROP TABLE IF EXISTS dbo.user_defined_event_example;

CREATE TABLE dbo.user_defined_event_example
(
Id int IDENTITY(1,1) PRIMARY KEY,
Data nvarchar(60) NOT NULL
);

DROP TRIGGER IF EXISTS fire_user_defined_event;
GO

-- Create an insert trigger on the table
CREATE TRIGGER fire_user_defined_event ON dbo.user_defined_event_example
FOR INSERT
AS
DECLARE @EventData varbinary(8000);

-- Convert inserted rows to JSON and cast it as a binary value
SELECT @EventData = CAST((
                         SELECT Id, Data
                         FROM inserted
                         FOR JSON AUTO
                         ) AS varbinary(8000));

-- Fire the event with the payload carrying inserted rows as JSON
EXEC dbo.sp_trace_generateevent
    @eventid = 82,
    @userinfo = N'Inserted rows into dbo.user_defined_event_example',
    @userdata = @EventData;
GO

-- Insert a row into the table. The trigger fires the event.
INSERT INTO dbo.user_defined_event_example (Data)
VALUES (N'Example data');

-- Copy the binary payload from the event and cast it to a string with the JSON value
SELECT CAST(0x5B007B0022004900640022003A0031002C002200440061007400610022003A0022004500780061006D0070006C0065002000640061007400610022007D005D00 AS nvarchar(max));
-- This returns: [{"Id":1,"Data":"Example data"}]

Contenu connexe