Tidying the OpenTelemtry documentation

The Jaeger example is outdated and has bitrotted due to
the OpenTelemetry APIs changing.

But there are dozens of OpenTelemetry backends.  Rather
than providing instructions on connection to just one,
let's instead standardise on one consistent and
simple approach, which is exporting OpenTelemetry traces
in OTLP format.  These can be sent to any OTLP-compatible
backend, which is pretty much all of them, including Jaeger.

Also added some troubleshooting tips.

Author: programmatix

modules/howtos/examples/Tracing.java

@@ -32,28 +32,6 @@ public static void main(String... args) throws Exception {
         CoreEnvironment environment = CoreEnvironment.builder().thresholdLoggingTracerConfig(config).build();
         // end::tracing-configure[]
       }
-
-      {
-        // tag::otel-configure[]
-        // Create a channel towards Jaeger end point
-        ManagedChannel jaegerChannel = ManagedChannelBuilder.forAddress("localhost", 14250).usePlaintext().build();
-
-        // Export traces to Jaeger
-        JaegerGrpcSpanExporter jaegerExporter = JaegerGrpcSpanExporter.builder().setServiceName("YOUR_SERVICE_NAME_HERE")
-            .setChannel(jaegerChannel).setDeadlineMs(30000).build();
-
-        // Set to process the spans by the Jaeger Exporter
-        OpenTelemetrySdk.getGlobalTracerManagement()
-            .addSpanProcessor(SimpleSpanProcessor.builder(jaegerExporter).build());
-        // end::otel-configure[]
-
-        // tag::otel-configure-setup[]
-        // Wrap Tracer
-        RequestTracer tracer = OpenTelemetryRequestTracer.wrap(OpenTelemetry.get());
-
-        ClusterEnvironment environment = ClusterEnvironment.builder().requestTracer(tracer).build();
-        // end::otel-configure-setup[]
-      }
     }
   }
 
@@ -68,12 +46,16 @@ public static void opentelemetryDirect() {
             .setResource(Resource.getDefault()
                     .merge(Resource.builder()
                             // An OpenTelemetry service name generally reflects the name of your microservice,
-                            // e.g. "shopping-cart-service"
+                            // e.g. "shopping-cart-service".
                             .put("service.name", "YOUR_SERVICE_NAME_HERE")
                             .build()))
+            // The BatchSpanProcessor will efficiently batch traces and periodically export them.
+            // This exporter exports traces on the OTLP protocol over GRPC on port 4317.
             .addSpanProcessor(BatchSpanProcessor.builder(OtlpGrpcSpanExporter.builder()
                     .setEndpoint("HOSTNAME_OF_OPENTELEMETRY_BACKEND:4317")
                     .build()).build())
+            // Export every trace: this may be too heavy for production.
+            // An alternative is `.setSampler(Sampler.traceIdRatioBased(0.01))`
             .setSampler(Sampler.alwaysOn())
             .build();
 

modules/howtos/pages/observability-tracing.adoc

@@ -72,7 +72,7 @@ More information will be provided as we get closer to stabilization.
 The built-in tracer is great if you do not have a centralized monitoring system, but if you already plug into the OpenTelemetry ecosystem we want to make sure to provide first-class support.
 
 === Exporting to OpenTelemetry
-This method exports tracing telemetry in OpenTelemetry's standard format (OTLP), which can be sent to any OTLP-compatible backend/processor such as Jaeger, Zipkin or `opentelemetry-collector`.
+This method exports tracing telemetry in OpenTelemetry's standard format (OTLP), which can be sent to any OTLP-compatible receiver such as Jaeger, Zipkin or `opentelemetry-collector`.
 
 Add this to your Maven, or the equivalent to your build tool of choice:
 
@@ -122,53 +122,13 @@ And now:
 include::example$Tracing.java[tag=otel-direct,indent=0]
 ----
 
-=== Exporting directly to Jaeger
-This example outputs tracing telemetry from the SDK directly to Jaeger, or a Jaeger-compatible backend such as Zipkin.
+At this point the SDK will automatically be exporting spans, and you should see them in your receiver of choice.
 
-Add this to your Maven, or the equivalent to your build tool of choice:
-
-[source,xml]
-----
-<dependency>
-    <groupId>com.couchbase.client</groupId>
-    <artifactId>tracing-opentelemetry</artifactId>
-    <version>1.2.0</version>
-</dependency>
-<dependency>
-    <groupId>io.opentelemetry</groupId>
-    <artifactId>opentelemetry-exporter-jaeger</artifactId>
-    <version>0.11.0</version>
-</dependency>
-<dependency>
-    <groupId>io.grpc</groupId>
-    <artifactId>grpc-protobuf</artifactId>
-    <version>1.28.0</version>
-</dependency>
-<dependency>
-    <groupId>io.grpc</groupId>
-    <artifactId>grpc-netty-shaded</artifactId>
-    <version>1.28.0</version>
-</dependency>
-----
-
-Next up, initialize the jaeger tracer:
-
-[source,java]
-----
-include::example$Tracing.java[tag=otel-configure,indent=0]
-----
-
-Once the exporter is set up, it can be wrapped into the `OpenTelemetryRequestTracer` and passed into the environment.
-
-[source,java]
-----
-include::example$Tracing.java[tag=otel-configure-setup,indent=0]
-----
-
-=== Span output
-At this point, whichever method you have used, the SDK will automatically be exporting spans and you should see them in your backend of choice.
-
-(Bear in mind during testing that the exporter may batch spans and hence not export them if the application exits quickly enough.  This can be configured on the `BatchSpanProcessor` or `JaegerGrpcSpanExporter` objects.)
+=== OpenTelemetry Troubleshooting
+* There are many ways to export spans.  The example is exporting OpenTelemetry Protocol (OTLP) spans over GRPC to port 4317, which we believe is the defacto standard for OpenTelemetry.  Make sure that your receiver is compatible with this, e.g. has these ports open and is ready to receive OTLP traffic over GRPC.  With https://www.jaegertracing.io/docs/1.41/getting-started/[Jaeger in Docker] this is achieved with the options `-e COLLECTOR_OTLP_ENABLED=true` and `-p 4317:4317`.
+* The exporter used in this example is `BatchSpanProcessor`, which may not have a chance to export spans if the application exits very quickly (e.g. a test application).  `SimpleSpanProcessor` can be used instead, though is not likely suitable for production.
+* The example above uses `Sampler.alwaysOn()`, which exports every span.  This may need to be reduced to avoid overwhelming the receiver, with e.g. `Sampler.traceIdRatioBased(0.01)` to sample 1% of all traces.
+* It can be worth sending traces into https://opentelemetry.io/docs/collector/[OpenTelemetry Collector], and forwarding them on from there to your receiver of choice.  Among other capabilities the collector can log traces it receives, making for easier debugging.
 
 === Parent spans
 
@@ -199,7 +159,7 @@ You need to include the `tracing-opentracing` module:
 </dependency>
 ----
 
-And then wrap the Tracer:
+And then create an OpenTracing `Tracer` and pass it to the SDK:
 
 [source,java]
 ----