Merge pull request #336 from nr-swilloughby/291_wait_for_connection

added advice on usage of WaitForConnection() call

v3/newrelic/application.go

@@ -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 trivial, short-lived
+// processes. It is better to simply start the application and allow the
+// instrumentation code to handle its 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