When you generate an event you can include detailed information about the event by passing event parameters. The more details you provide about an event, the more useful the event is likely to be for the Visual Studio Analyzer user who is trying to analyze performance or isolate faults.
Among the most important parameters you can provide are the identities of the source machine (where the event originated) and the target machine (where the event ended up). In a distributed application — where business logic, a database, or a transaction server are on different machines from the application client — events such as function call or return, database query send and return, and transaction start and commit will provide more useful information if the source and target machine identities are provided.
The event parameters that describe the event source and target (machine, process, process name, thread, component, session, and handle) are individually optional, but at least one of the group is required. The Block Diagram view depends on these values to properly connect the parts of the diagram. If you cannot provide any of these values for your application, synthesize unique values for SourceHandle and TargetHandle. They represent your application's view of unique identifiers for the event source and event target. These synthesized values must be constant for all calls to FireEvent for the same source or target.
You can choose to provide default values for either the source parameters or the target parameters; however, the default values are unlikely to be correct for both source and target, because you will normally know the identity of only one. Thus the VSAEventFlags parameter of FireEvent allows you to specify default values separately for the source and target parameters.
You must try to provide as much information as possible about the source and the target. This increases the chance that the Visual Studio Analyzer user will be able to correlate calls to the same object that arrive by different channels. At a minimum, you must maintain the integrity of SourceHandle and TargetHandle, so it is clear that multiple calls are from the same source to the same target. If you cannot preserve this integrity, the number of entities in the block diagram will increase to an unacceptable level, affecting performance.
As an example, consider calls to FireEvent from SQL Server. When SQL Server receives a query, it can generate an event. SQL Server would probably know its machine, process, and possibly thread, so it could supply values for TargetMachine, TargetProcess, and possibly TargetThread. However, SQL Server probably does not know where the query came from, unless ODBC provides this information, so this call would specify the ODBC connection handle as a value for the SourceHandle parameter (if provided by ODBC) and specify default values for the target event parameters.