From 073d21ab8f9a2166b80849d971145224c1c1138c Mon Sep 17 00:00:00 2001
From: Dan Rose <rotu@users.noreply.github.com>
Date: Thu, 16 Apr 2020 19:10:29 -0500
Subject: [PATCH] Add debug tips to README.md (#137)

---
 README.md | 52 ++++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 42 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index fec645e..c4803d3 100644
--- a/README.md
+++ b/README.md
@@ -7,23 +7,55 @@ Cyclone DDS is ready to use. It seeks to give the fastest, easiest, and most rob
 
 1. Install:
 
-  ```
-  apt install ros-eloquent-rmw-cyclonedds-cpp
-  ```
-  or
-  ```
-  apt install ros-dashing-rmw-cyclonedds-cpp
-  ```
+   ```
+   apt install ros-eloquent-rmw-cyclonedds-cpp
+   ```
+   or
+   ```
+   apt install ros-dashing-rmw-cyclonedds-cpp
+   ```
 
-2) Set env variable and run ROS2 apps as usual:
+2. Set env variable and run ROS2 apps as usual:
 
-  ```export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp```
+   ```export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp```
 
-3) Confirm RMW: In Eloquent, to confirm which RMW you're using:
+3. Confirm RMW: In Eloquent and later, to confirm which RMW you're using:
 
    ```ros2 doctor --report```
 
 
+## Performance recommendations
+
+With large samples (100s of kilobytes), excessive latency can be caused by running out of space in the OS-level receive buffer. For this reason, on Linux, we recommend increasing the buffer size:
+* Temporarily (until reboot): `sudo sysctl -w net.core.rmem_max=8388608 net.core.rmem_default=8388608`
+* Permanently: `echo "net.core.rmem_max=8388608\nnet.core.rmem_default=8388608\n" | sudo tee /etc/sysctl.d/60-cyclonedds.conf`
+
+## Debugging
+
+So Cyclone isn't playing nice or not giving you the performance you had hoped for? That's not good... Please [file an issue against this repository](https://github.com/ros2/rmw_cyclonedds/issues/new)!
+
+The `ddsperf` tool distributed with Cyclone DDS can be used to check that communication works *without* ROS. Run `ddsperf sanity` on two different machines - if the "mean" value is above `100000us`, there are likely network issues.
+
+If you're having trouble with nodes discovering others or can't use multicast *at all* on your network setup, you can circumvent discovery:
+
+  `export CYCLONEDDS_URI='<Discovery><Peers><Peer Address='myroshost.local' /><Peer Address='myroshost2.local' /></></>'`
+
+Here are some ways to generate additional debugging info that can help identify the problem faster, and are helpful on an issue ticket:
+
+* Configure Cyclone to create richer debugging output:
+
+  * To see the output live:
+    
+    `export CYCLONEDDS_URI='<Tracing><Verbosity>trace</><Out>stderr</></>'`
+
+  * To send to `/var/log/`:
+    
+    `export CYCLONEDDS_URI='<Tracing><Verbosity>trace</><Out>/var/log/cyclonedds.${CYCLONEDDS_PID}.log</></>'`
+
+* Create a Wireshark capture:
+  
+  `wireshark -k -w wireshark.pcap.gz`
+
 ## Building from source and contributing
 
 The following branches are actively maintained: