added advice on usage of WaitForConnection() call
@@ -83,6 +83,15 @@ func (app *Application) RecordCustomMetric(name string, value float64) {
// If Infinite Tracing is enabled, WaitForConnection will block until a
// connection to the Trace Observer is made, a fatal error is reached, or the
// timeout is hit.
+//
+// Note that in most cases, it is not necesary nor recommended to call
+// WaitForConnection() at all, particularly for any but the most short-lived
+// processes. It is better to simply start the application and allow the
+// instrumentation code handle connections on its own, which it will do
+// as needed in the background (and will continue attempting to connect
+// if it wasn't immediately successful, all while allowing your application
+// to proceed with its primary function).
+//
func (app *Application) WaitForConnection(timeout time.Duration) error {
if nil == app {
return nil
