docs: document Flush method, and when to call it

[axw]

The elastic.co docs are missing any mention of the Tracer.Flush method. In a typical web app this isn't needed, but for short-lived applications it should be called before the process exits, to ensure queued events are flushed to the server.

[avestuk]

@axw Any chance you could point me in the direction of some documentation about how to flush the tracer? I have tried something naive like the below but I saw no messages from the APM agent about sending requests when I had the debug logging enabled.

mainLog.Error().Err(err).Msg("error while running main loop")
mainLog.Info().Msg("flushing traces before exit 1...")
apm.DefaultTracer().Flush(nil)

What I see in the logs when APM debug logging is enabled

{"level":"debug","time":"2024-10-31T16:03:40Z","message":"sent request with 12 transactions, 30 spans, 0 errors, 0 metricsets"}

APM debug logging enabled and attempting to flush gives no sending requests.

..."package":"main","function":"main","message":"error while running main loop"}
..."package":"main","function":"main","message":"flushing traces before exit 1..."}

[axw]

@avestuk the way you're calling Flush looks correct. Are you saying that if you wait long enough during normal operation then you do see a message in the logs that the agent is sending data, but if you attempt to flush then you do not?

If that's the case, I would suppose you're not flushing the same tracer. Are you using apm.DefaultTracer() everywhere?

[avestuk]

@axw Sadly not unusually it was due to me not understanding how exactly our tracing was setup. We are using your APM-gRPC interceptors which create the default tracer when the first gRPC request is recieved.

The route through the stack of this particular call did not go via gRPC so no transactions/spans were being created so there was nothing to flush.

Thanks for your swift response!