Chapter 57 Discovery Snapshots
Connext allows you to take discovery snapshots of DomainParticipants, DataWriters, and DataReaders. Discovery snapshots are useful when your applications are not communicating as expected. DomainParticipant discovery snapshots show you useful information about the discovery status between DomainParticipants; DataWriter discovery snapshots show information about matched DataReaders; and DataReader discovery snapshots show information about their matched DataWriters. These snapshots show the information present at the time the functions are called to take them.
57.1 Viewing the Discovery Status
For local DomainParticipants, a discovery snapshot includes information about themselves and discovered remote ones, such as the domain ID, domain tag, participant partitions, entity and role names, GUID prefixes, locators, and security-related information. An example of the output is as follows:
-------------------------------------------------------------------------
-------------------------------------------------------------------------
Participant guid="0x0101F2F1,0xC229B376,0x46572559:0x000001C1"
domain_id=0 domain_tag="testDomainTag" name="participantTestName" role="participantTestRole" participant_partitions="partPartition0,partPartition1"
-------------------------------------------------------------------------
Matched Participants:
-------------------------------------------------------------------------
guid="0x0101D75E,0xB70D1850,0x2B0D229B:0x000001C1"
name="participantTestName" role="participantTestRole" participant_partitions="partPartition0,partPartition1"
unicastLocators="udpv4://10.70.2.68:7413
shmem://CA1B:28DA:1E18:F955:3727:3AFE:0000:0000:7413"
-------------------------------------------------------------------------
-------------------------------------------------------------------------
For local DataWriters/DataReaders, a discovery snapshot includes information about themselves and matched/unmatched remote DataReaders/DataWriters. A local DataWriter/DataReader will match with a remote DataReader/DataWriter if its Topic, type, and QoS are compatible with the remote entity. A remote DataWriter/DataReader will unmatch with the local DataReader/DataWriter (even if it uses the same Topic) if its QoS is incompatible with the local DataReader/DataWriter or if security-related reasons make it incompatible. The discovery snapshot shows information about the remote entity, including the publisher/subscriber partitions, entity names, GUIDs, Topic, type, local and remote entity kinds, locators, liveliness information, and, if the remote entity is incompatible with the local one, the reason why. Some examples of the snapshot output are the following:
For DataWriters:
----------------------------------------------------------------------------
-------------------------------------------------------------------------
Writer guid="0x0101F926,0xBE2B43E8,0x3CF1676B:0x80000003"
topic="FooTopic" type="FooType" keyed_type="false" name="writer1TestName" publisher_partitions="pubsubPartition0,pubsubPartition1"
-------------------------------------------------------------------------
Matched Readers:
-------------------------------------------------------------------------
guid="0x0101588A,0x532B8256,0xFAAB0F1E:0x80000004"
name="reader1TestName" subscriber_partitions="pubsubPartition0,pubsubPartition1" unicastLocators="udpv4://10.70.2.68:7411
shmem://CA1B:28DA:1E18:F955:3727:3AFE:0000:0000:7411"
status="ALIVE"
-------------------------------------------------------------------------
Not matched Readers (on the same Topic):
-------------------------------------------------------------------------
guid="0x0101588A,0x532B8256,0xFAAB0F1E:0x80000104"
name="reader2TestName" subscriber_partitions="pubsubPartition0,pubsubPartition1" unicastLocators="udpv4://10.70.2.68:7411
shmem://CA1B:28DA:1E18:F955:3727:3AFE:0000:0000:7411"
incompatibility="QoS"
-------------------------------------------------------------------------
----------------------------------------------------------------------------
For DataReaders:
-------------------------------------------------------------------------
-------------------------------------------------------------------------
Reader guid="0x010101D1,0xE6695CC6,0xFC4999A6:0x80000004"
topic="FooTopic" type="FooType" keyed_type="false" name="reader1TestName" subscriber_partitions="pubsubPartition0,pubsubPartition1"
-------------------------------------------------------------------------
Matched Writers:
-------------------------------------------------------------------------
guid="0x0101DE39,0x0E87C1C7,0x78039363:0x80000003" name="writer1TestName"
publisher_partitions="pubsubPartition0,pubsubPartition1" unicastLocators="udpv4://10.70.2.68:7413
shmem://CA1B:28DA:1E18:F955:3727:3AFE:0000:0000:7413"
status="ALIVE"
-------------------------------------------------------------------------
guid="0x0101DE39,0x0E87C1C7,0x78039363:0x80002103" name="writer2TestName"
publisher_partitions="pubsubPartition0,pubsubPartition1" unicastLocators="udpv4://10.70.2.68:7413
shmem://CA1B:28DA:1E18:F955:3727:3AFE:0000:0000:7413" status="ALIVE"
-------------------------------------------------------------------------
Not matched Writers (on the same Topic):
-------------------------------------------------------------------------
(Empty)
-------------------------------------------------------------------------
-------------------------------------------------------------------------
This feature is available through the following APIs (in all languages):
- take_snapshot(dds::domain::DomainParticipant participant)
- take_snapshot(dds::pub::DataWriter writer)
- take_snapshot(dds::sub::DataReader reader)
For more information, see the API Reference HTML documentation.
57.2 Using Snapshots to Debug the Discovery Process
Imagine two participants in your network, Participant1 and Participant2. Participant1 has a DataWriter (called Writer), Participant2 has a DataReader (called Reader). You execute the two participants, but the Reader is not receiving data from the Writer. To determine whether it is a discovery issue, use the discovery snapshot feature.
- Check if Participant1 and Participant2 are discovering each other. Take a DomainParticipant discovery snapshot on either the Participant1 or Participant2 side. For example, if you take a snapshot of the discovery information of Participant1, look for Participant2 in the output table. If it is there, you know that Participant1 and Participant2 are discovered on both sides, so the issue is not related to participant discovery. If "Participant2" does not appear in the snapshot, check the domainId and partition on both sides, to see if they are the same; check that the locators on both sides are reachable.
- Check if the Writer and Reader are compatible. Once you know that the participants have successfully discovered each other, check why the Writer and Reader are not communicating. Take a DataWriter/DataReader snapshot on either side. For example, if you take a snapshot of the discovery information of the Writer, look for the Reader in it. If the Reader is not there, then you know that the Writer and Reader do not match. Check the compatibility of their Topic, type, and entity kind. If the Reader is in the Writer discovery snapshot, but labeled "not matched" (but in the same Topic), check the incompatibility reason provided by the snapshot.
Discovery snapshots give you enough information to fix discovery issues and have communication between the endpoints (DataWriters and DataReaders).
Note: If you take a discovery snapshot in the middle of the discovery process, there is a small chance you will get an error that looks like “Failed to take participant discovery snapshot. Please try to take the snapshot later when the discovery process is more advanced”. This error appears because of the way Connext takes snapshots; it needs some stability in discovery registers during the process. If you get this error, execute the snapshot again until the error goes away. If the error persists, take the snapshot later when the discovery process is more advanced. You will not get this error once the discovery process is finished.
57.3 Limitations
Discovery snapshots need to take some Exclusive Areas (see 15.8.8 Exclusive Areas (EAs)) to get all the information that they show consistently. As a result, discovery snapshots should be used cautiously within listener callbacks. Currently, RTI only supports discovery snapshots in a subset of listener callbacks:
- DomainParticipant snapshots are supported in on_publication_matched and on_subscription_matched.
- DataWriter snapshots are supported in on_publication_matched.
- DataReader snapshots are supported in on_subscription_matched and on_liveliness_changed.