From 59bb15a0d1c4cc43b7132ec394e31abd4d28f2ae Mon Sep 17 00:00:00 2001 From: Yuri Shkuro Date: Wed, 23 Aug 2017 15:56:37 -0400 Subject: [PATCH] Mention UDP buffer size restrictions (#352) --- docs/client_libraries.md | 26 +++++++++++++++++++++++--- 1 file changed, 23 insertions(+), 3 deletions(-) diff --git a/docs/client_libraries.md b/docs/client_libraries.md index e12b7907c36..b8e375e1af6 100644 --- a/docs/client_libraries.md +++ b/docs/client_libraries.md @@ -1,6 +1,6 @@ -#Client Libraries +# Client Libraries -##Official libraries +## Official libraries | Language | Library | | ---------|--------------------------------------------------------------| @@ -11,6 +11,26 @@ For a deep dive into how to instrument a Go service, look at [Tracing HTTP request latency](https://medium.com/@YuriShkuro/tracing-http-request-latency-in-go-with-opentracing-7cc1282a100a). -##OpenTracing Contributions +### Initializing Jaeger Tracer + +The initialization syntax is slightly different in each langauges, please refer to the README's in the respective repositories. +The general pattern is to not create the Tracer explicitly, but use a Configuration class to do that. Configuration allows +simpler parameterization of the Tracer, such as changing the default sampler or the location of Jaeger agent. + +### EMSGSIZE and UDP buffer limits + +By default Jaeger libraries use a UDP sender to report finished spans to `jaeger-agent` sidecar. +The default max packet size is 65,000 bytes, which can be transmitted without segmentation when +connecting to the agent via loopback interface. However, some OSs (in particular, MacOS), limit +the max buffer size for UDP packets, as raised in [this GitHub issue](https://github.com/uber/jaeger-client-node/issues/124). +If you run into issue with `EMSGSIZE` errors, consider raising the limits in your kernel (see the issue for examples). +You can also configure the client libraries to use a smaller max packet size, but that may cause +issues if you have large spans, e.g. if you log big chunks of data. Spans that exceed max packet size +are dropped by the clients (with metrics emitted to indicate that). Another alternative is +to use non-UDP transports, such as [HttpSender in Java][HttpSender] (not currently available for all langauges). + +## OpenTracing Contributions See the OpenTracing contributions repository on [Github](https://github.com/opentracing-contrib) for more libraries. + +[HttpSender]: /https://github.com/uber/jaeger-client-java/blob/master/jaeger-core/src/main/java/com/uber/jaeger/senders/HttpSender.java