Documentation + shutdown handling in examples (#792)

* documentation tidy

* fixing links

* more doco

* more readme work

* adding span processor shutdown handling to examples

* reorg

* bump heading level

* wordsmithing readme

* simplify fqn

* call tracer provider directly in examples

Author: brettmc

CONTRIBUTING.md

@@ -1,12 +1,15 @@
-Maintainers ([@open-telemetry/php-maintainers](https://github.com/orgs/open-telemetry/teams/php-maintainers)):
+## Maintainers
+[@open-telemetry/php-maintainers](https://github.com/orgs/open-telemetry/teams/php-maintainers)
 
 - [Bob Strecansky](https://github.com/bobstrecansky)
 - [Timo Michna](https://github.com/tidal/)
 - [Brett McBride](https://github.com/brettmc/)
 
 Find more about the maintainer role in [community repository](https://github.com/open-telemetry/community/blob/master/community-membership.md#maintainer)
 
-Approvers ([@open-telemetry/php-approvers](https://github.com/orgs/open-telemetry/teams/php-approvers)):
+
+## Approvers
+[@open-telemetry/php-approvers](https://github.com/orgs/open-telemetry/teams/php-approvers)
 
 - [Levi Morrison](https://github.com/morrisonlevi)
 - [Beniamin Calota](https://github.com/beniamin)
@@ -15,18 +18,30 @@ Approvers ([@open-telemetry/php-approvers](https://github.com/orgs/open-telemetr
 
 Find more information about the approver role in the [community repository](https://github.com/open-telemetry/community/blob/master/community-membership.md#approver)
 
-Triagers ([@open-telemetry/php-triagers](https://github.com/orgs/open-telemetry/teams/php-triagers)):
+## Triagers
+[@open-telemetry/php-triagers](https://github.com/orgs/open-telemetry/teams/php-triagers)
 
 - [Jodee Varney](https://github.com/jodeev)
 
 Find more information about the triager role in the [community repository](https://github.com/open-telemetry/community/blob/master/community-membership.md#triager)
 
-Members:
+## Members
 
 - [Kishan Sangani](https://github.com/kishannsangani)
 
 Find more information about the member role in the [community repository](https://github.com/open-telemetry/community/blob/master/community-membership.md#member)
 
+## Communication
+
+Most of our communication is done on CNCF Slack in the channel [otel-php](https://cloud-native.slack.com/archives/C01NFPCV44V).
+To sign up, create a CNCF Slack account [here](http://slack.cncf.io/)
+
+Our meetings are held weekly on zoom on Wednesdays at 10:30am PST / 1:30pm EST.
+A Google calendar invite with the included zoom link can be found [here](https://calendar.google.com/event?action=TEMPLATE&tmeid=N2VtZXZmYnVmbzZkYjZkbTYxdjZvYTdxN21fMjAyMDA5MTZUMTczMDAwWiBrYXJlbnlyeHVAbQ&tmsrc=google.com_b79e3e90j7bbsa2n2p5an5lf60%40group.calendar.google.com&scp=ALL)
+
+Our open issues can all be found in the [GitHub issues tab](https://github.com/open-telemetry/opentelemetry-php/issues).  Feel free to reach out on Slack if you have any additional questions about these issues; we are always happy to talk through implementation details.
+
+
 #### Thanks to all the people who already contributed!
 
 <a href="https://github.com/open-telemetry/opentelemetry-php/graphs/contributors">

README.md

@@ -13,6 +13,7 @@
 use OpenTelemetry\API\Trace\SpanKind;
 use OpenTelemetry\API\Trace\StatusCode;
 use OpenTelemetry\Context\Context;
+use OpenTelemetry\SDK\Common\Util\ShutdownHandler;
 use OpenTelemetry\SDK\Trace\Tracer;
 use OpenTelemetry\SDK\Trace\TracerProviderFactory;
 use Psr\Http\Message\RequestInterface;
@@ -22,6 +23,7 @@
 use Slim\Routing\RouteContext;
 
 $tracerProvider = (new TracerProviderFactory('example'))->create();
+ShutdownHandler::register([$tracerProvider, 'shutdown']);
 $tracer = $tracerProvider->getTracer('io.opentelemetry.contrib.php');
 
 $cb = new ContainerBuilder();
@@ -38,13 +40,15 @@
                     ->setAttribute('http.method', $request->getMethod())
                     ->setAttribute('http.url', $request->getUri())
                     ->startSpan();
+
                 $ctx = $span->storeInContext(Context::getCurrent());
                 $carrier = [];
                 TraceContextPropagator::getInstance()->inject($carrier, null, $ctx);
                 //inject traceparent and tracestate headers
                 foreach ($carrier as $name => $value) {
                     $request = $request->withAddedHeader($name, $value);
                 }
+
                 $promise = $handler($request, $options);
                 $promise->then(function (Response $response) use ($span) {
                     $span->setAttribute('http.status_code', $response->getStatusCode())
@@ -78,10 +82,15 @@
         ->setParent($parent)
         ->setSpanKind(SpanKind::KIND_SERVER)
         ->startSpan();
-    $root->activate();
-    $response = $handler->handle($request);
-    $root->setStatus($response->getStatusCode() < 500 ? StatusCode::STATUS_OK : StatusCode::STATUS_ERROR);
-    $root->end();
+    $scope = $root->activate();
+
+    try {
+        $response = $handler->handle($request);
+        $root->setStatus($response->getStatusCode() < 500 ? StatusCode::STATUS_OK : StatusCode::STATUS_ERROR);
+    } finally {
+        $root->end();
+        $scope->detach();
+    }
 
     return $response;
 });

examples/traces/demo/src/index.php

@@ -12,7 +12,7 @@
 echo 'Starting ConsoleSpanExporter with BatchSpanProcessor' . PHP_EOL;
 echo sprintf('Sending batches every %dms and on shutdown', $delayMillis) . PHP_EOL;
 
-$tracerProvider =  new TracerProvider(
+$tracerProvider = new TracerProvider(
     new BatchSpanProcessor(
         new ConsoleSpanExporter(),
         null,
@@ -36,3 +36,4 @@
 $rootSpan->end();
 $scope->detach();
 sleep(1);
+$tracerProvider->shutdown();

examples/traces/features/always_off_trace_example.php

@@ -44,3 +44,4 @@
     $scope->detach();
     $rootSpan->end();
 }
+$tracerProvider->shutdown();

examples/traces/features/batch_exporting.php

@@ -25,6 +25,12 @@
 
 $rootSpan = $tracer->spanBuilder('root')->startSpan();
 $scope = $rootSpan->activate();
-$rootSpan->addEvent('my_event')->setAttribute('fruit', 'apple');
-$rootSpan->end();
-$scope->detach();
+
+try {
+    $rootSpan->addEvent('my_event')->setAttribute('fruit', 'apple');
+} finally {
+    $rootSpan->end();
+    $scope->detach();
+}
+
+$tracerProvider->shutdown();

examples/traces/features/concurrent_spans.php

@@ -8,11 +8,12 @@
 use OpenTelemetry\SDK\Trace\TracerProvider;
 
 // Boilerplate setup to create a new tracer with console output
-$tracer = (new TracerProvider(
+$tracerProvider = new TracerProvider(
     new SimpleSpanProcessor(
         new ConsoleSpanExporter()
     )
-))->getTracer('io.opentelemetry.contrib.php');
+);
+$tracer = $tracerProvider->getTracer('io.opentelemetry.contrib.php');
 
 // This creates a span and sets it as the current parent (and root) span
 $rootSpan = $tracer->spanBuilder('foo')->startSpan();
@@ -32,3 +33,4 @@
 
 $span->end();
 $scope->detach();
+$tracerProvider->shutdown();

examples/traces/features/configuration_from_environment.php

@@ -12,11 +12,12 @@
 $storage = new ArrayObject();
 
 // Boilerplate setup to create a new tracer with an in-memory exporter
-$tracer = (new TracerProvider(
+$tracerProvider = new TracerProvider(
     new SimpleSpanProcessor(
         new InMemoryExporter($storage)
     )
-))->getTracer('io.opentelemetry.contrib.php');
+);
+$tracer = $tracerProvider->getTracer('io.opentelemetry.contrib.php');
 
 // This creates a span and sets it as the current parent (and root) span
 $rootSpan = $tracer->spanBuilder('foo')->startSpan();
@@ -41,3 +42,5 @@
     );
 }
 echo PHP_EOL;
+
+$tracerProvider->shutdown();

examples/traces/features/creating_a_new_trace_in_the_same_process.php

@@ -55,3 +55,5 @@
 echo PHP_EOL . 'Jaeger example complete!  See the results at http://localhost:16686/';
 
 echo PHP_EOL;
+
+$tracerProvider->shutdown();