Performing Always and Never Sample Steps (#30)

* Performing Always and Never Sample Steps

* Updating examples to remove builder

* Updating examples to remove builder

* Removing builder from always off trace example

README.md

@@ -8,9 +8,9 @@
 - [Tracing](#tracing)
 - [Test](#testing)
 
-Our meetings are held weekly on Wednesdays at 10:30am PST / 1:30pm EST.  
-Please reach out on [gitter.im](https://gitter.im/open-telemetry/community) if you'd like to be invited.  
-The public calendar invite will be shared once it becomes avaiable.  
+Our meetings are held weekly on Wednesdays at 10:30am PST / 1:30pm EST.
+Please reach out on [gitter.im](https://gitter.im/open-telemetry/community) if you'd like to be invited.
+The public calendar invite will be shared once it becomes avaiable.
 
 ## Installation
 The recommended way to install the library is through [Composer](http://getcomposer.org):
@@ -18,37 +18,9 @@ The recommended way to install the library is through [Composer](http://getcompo
 $ composer require open-telemetry/opentelemetry
 ```
 
-## Tracing
-Library is under active development, but simple example should be present in readme.  
-In addition, see tracing tests for full-featured example.
-```php
-<?php
+### Examples
 
-use OpenTelemetry\Tracing\Builder;
-use OpenTelemetry\Tracing\SpanContext;
-
-$spanContext = SpanContext::generate(); // or extract from headers
-
-$tracer = Builder::create()->setSpanContext($spanContext)->getTracer();
-
-// start a span, register some events
-$span = $tracer->createSpan('session.generate');
-
-// set attributes as array
-$span->setAttributes([ 'remote_ip' => '5.23.99.245' ]);
-// set attribute one by one
-$span->setAttribute('country', 'Russia');
-
-$span->addEvent('found_login', [
-  'id' => 67235,
-  'username' => 'nekufa',
-]);
-$span->addEvent('generated_session', [
-  'id' => md5(microtime(true))
-]);
-
-$span->end(); // pass status as an optional argument
-```
+You can use the [examples/AlwaysSampleTraceExample.php](https://github.com/open-telemetry/opentelemetry-php/tree/master/examples/AlwaysSampleTraceExample.php) file to test out the reference implementation we have.  This can be easily executed with docker by running `./resources/example-using-docker` from the root of the repository.
 
 ## Static Analysis
 We use [Phan](https://github.com/phan/phan/) for static analysis.  Currently our phan configuration is just set with a standard default analysis configuration.  You can use our phan docker hook to easily perform static analysis on your changes:
@@ -57,8 +29,8 @@ We use [Phan](https://github.com/phan/phan/) for static analysis.  Currently our
 ## Testing
 To make sure the tests in this repo work as you expect, you can use the included docker test wrapper:
 
-1.)  Make sure that you have docker installed  
+1.)  Make sure that you have docker installed
 2.)  Execute `./resources/test-using-docker` from your bash compatible shell.
 
 ## Caveats
-The Span Links concept is not yet implemented. 
+The Span Links concept is not yet implemented.

examples/AlwaysOffTraceExample.php

@@ -0,0 +1,30 @@
+<?php
+require __DIR__ . '/../vendor/autoload.php';
+
+use OpenTelemetry\Tracing\SpanContext;
+use OpenTelemetry\Tracing\Sampler\AlwaysOffSampler;
+use OpenTelemetry\Tracing\Tracer;
+
+$sampler = AlwaysOffSampler::shouldSample();
+if ($sampler) {
+    $spanContext = SpanContext::generate(); // or extract from headers
+    $tracer = new Tracer($spanContext);
+
+    // start a span, register some events
+    $span = $tracer->createSpan('session.generate');
+    $span->setAttributes(['remote_ip' => '1.2.3.4']);
+    $span->setAttribute('country', 'USA');
+
+    $span->addEvent('found_login', [
+      'id' => 12345,
+      'username' => 'otuser',
+    ]);
+    $span->addEvent('generated_session', [
+      'id' => md5(microtime(true))
+    ]);
+
+    $span->end(); // pass status as an optional argument
+    print_r($span);  // print the span as a resulting output
+} else {
+    echo "Sampling is not enabled";
+}

examples/AlwaysOnTraceExample.php

@@ -0,0 +1,30 @@
+<?php
+require __DIR__ . '/../vendor/autoload.php';
+
+use OpenTelemetry\Tracing\SpanContext;
+use OpenTelemetry\Tracing\Sampler\AlwaysOnSampler;
+use OpenTelemetry\Tracing\Tracer;
+
+$sampler = AlwaysOnSampler::shouldSample();
+if ($sampler) {
+  $spanContext = SpanContext::generate(); // or extract from headers
+  $tracer = new Tracer($spanContext);
+
+  // start a span, register some events
+  $span = $tracer->createSpan('session.generate');
+  $span->setAttributes(['remote_ip' => '1.2.3.4']);
+  $span->setAttribute('country', 'USA');
+
+  $span->addEvent('found_login', [
+    'id' => 12345,
+    'username' => 'otuser',
+  ]);
+  $span->addEvent('generated_session', [
+    'id' => md5(microtime(true))
+  ]);
+
+  $span->end(); // pass status as an optional argument
+  print_r($span);  // print the span as a resulting output
+} else {
+  echo "Sampling is not enabled";
+}

resources/Dockerfile.example

@@ -0,0 +1,4 @@
+FROM php:7.1-buster
+COPY . /usr/src/myapp
+WORKDIR /usr/src/myapp
+ENTRYPOINT ["php", "examples/AlwaysOnTraceExample.php"]

resources/example-using-docker

@@ -0,0 +1,3 @@
+#!/bin/bash
+docker build -f ./resources/Dockerfile.example -t opentelemetry-php-docker-example .
+docker run -it opentelemetry-php-docker-example /bin/bash

src/Tracing/Sampler/AlwaysOffSampler.php

@@ -0,0 +1,22 @@
+<?php
+namespace OpenTelemetry\Tracing\Sampler;
+/**
+ * This implementation of the SamplerInterface always returns false.
+ * Example:
+ * ```
+ * use OpenTelemetry\Traceing\Sampler\NeverSampleSampler;
+ * $sampler = new NeverSampleSampler();
+ * ```
+ */
+class AlwaysOffSampler implements SamplerInterface
+{
+    /**
+     * Returns false because we never want to sample.
+     *
+     * @return bool
+     */
+    public function shouldSample()
+    {
+        return false;
+    }
+} 

src/Tracing/Sampler/AlwaysOnSampler.php

@@ -0,0 +1,22 @@
+<?php
+namespace OpenTelemetry\Tracing\Sampler;
+/**
+ * This implementation of the SamplerInterface always returns true.
+ * Example:
+ * ```
+ * use OpenTelemetry\Traceing\Sampler\AlwaysSampleSampler;
+ * $sampler = new AlwaysSampleSampler();
+ * ```
+ */
+class AlwaysOnSampler implements SamplerInterface
+{
+    /**
+     * Returns true because we always want to sample.
+     *
+     * @return bool
+     */
+    public function shouldSample()
+    {
+        return true;
+    }
+} 

src/Tracing/Sampler/SamplerInterface.php

@@ -0,0 +1,14 @@
+<?php
+namespace OpenTelemetry\Tracing\Sampler;
+/**
+ * This interface is used to organize sampling logic.
+ */
+interface SamplerInterface
+{
+    /**
+     * Returns true if we should sample the request.
+     *
+     * @return bool
+     */
+    public function shouldSample();
+} 

tests/unit/Tracing/Sampler/AlwaysOffSamplerTest.php

@@ -0,0 +1,12 @@
+<?php
+require __DIR__.'/../../../../vendor/autoload.php';
+use OpenTelemetry\Tracing\Sampler\AlwaysOffSampler;
+use PHPUnit\Framework\TestCase;
+class AlwaysOffSamplerTest extends TestCase
+{
+    public function testAlwaysOffSampler()
+    {
+        $sampler = new AlwaysOffSampler();
+        $this->assertFalse($sampler->shouldSample());
+    }
+} 

tests/unit/Tracing/Sampler/AlwaysOnSamplerTest.php

@@ -0,0 +1,12 @@
+<?php
+require __DIR__.'/../../../../vendor/autoload.php';
+use OpenTelemetry\Tracing\Sampler\AlwaysOnSampler;
+use PHPUnit\Framework\TestCase;
+class AlwaysOnTest extends TestCase
+{
+    public function testAlwaysOnSampler()
+    {
+        $sampler = new AlwaysOnSampler();
+        $this->assertTrue($sampler->shouldSample());
+    }
+}