Add a simple example using an integration

Changes

@@ -5,6 +5,8 @@ Revision history for OpenTelemetry
     * Switch LWP::UserAgent integration to wrap around that module's
       'simple_request' method instead of its 'request' method. This
       should catch some more cases, and fix GH #13.
+    * Added a minimal example application. See the `examples` directory
+      in the distribution files.
 
 0.019     2023-12-03 14:44:05+00:00 Europe/London
 

examples/integrations/lwp

@@ -0,0 +1,53 @@
+#!/usr/bin/env perl
+
+use strict;
+use warnings;
+use feature 'say';
+
+# This example shows the minimum mount of code needed to generate
+# telemetry data through an integration, in this case using
+# LWP::UserAgent.
+
+# While loading the integration is all that is needed to instrument
+# the client code, in order to see it work we need two more things:
+#
+# 1. Some configured set of propagators, so that we have something
+#    we can propagate data with; and
+#
+# 2. A valid trace span in the current context, so that we have
+#    something to propagate.
+
+# The easiest way to create and install a valid trace span in the
+# current context is with the trace provider's 'in_span' helper
+# method. For taht we need a way to access the tracer provider.
+# We can use OpenTelemetry->tracer_provider, or use this
+# convenience function that we can import.
+use OpenTelemetry qw( otel_tracer_provider );
+
+# The easiest way to set up a set of propagators, on the other hand,
+# is by loading the SDK, which will read the configuration from the
+# environment. By default, this will set up a TraceContext and a
+# Baggage propagator, but we won't see the baggage in the request
+# headers since we are not going to add any baggage to the context.
+use OpenTelemetry::SDK;
+
+# We load the the integration for LWP::UserAgent, which will automatically
+# import that module for us. This automatic loading only happens if we
+# request the integration by name.
+use OpenTelemetry::Integration 'LWP::UserAgent';
+
+# By default we will send a request to an echo server, so we can examine
+# the headers we send. You can override this by passing a URL as an
+# argument when executing this script.
+my $url = shift // 'https://httpbin.org/anything';
+
+# We get a tracer from the tracer provider and use its `in_span` helper
+# to execute some code in a context with a valid span. The code reference
+# we pass will take the created span and the context that contains it
+# as arguments, but we don't need them in this case.
+otel_tracer_provider->tracer->in_span(
+    'some-span' => sub {
+        my $res = LWP::UserAgent->new->get($url);
+        say $res->content;
+    },
+);