From c863d37cff57b7f4a32144b3be9918728bc667d0 Mon Sep 17 00:00:00 2001
From: Bob Strecansky <bob.strecansky@gmail.com>
Date: Tue, 10 Dec 2019 13:48:22 -0500
Subject: [PATCH] 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                                     | 42 ++++---------------
 examples/AlwaysOffTraceExample.php            | 30 +++++++++++++
 examples/AlwaysOnTraceExample.php             | 30 +++++++++++++
 resources/Dockerfile.example                  |  4 ++
 resources/example-using-docker                |  3 ++
 src/Tracing/Sampler/AlwaysOffSampler.php      | 22 ++++++++++
 src/Tracing/Sampler/AlwaysOnSampler.php       | 22 ++++++++++
 src/Tracing/Sampler/SamplerInterface.php      | 14 +++++++
 .../Tracing/Sampler/AlwaysOffSamplerTest.php  | 12 ++++++
 .../Tracing/Sampler/AlwaysOnSamplerTest.php   | 12 ++++++
 10 files changed, 156 insertions(+), 35 deletions(-)
 create mode 100644 examples/AlwaysOffTraceExample.php
 create mode 100644 examples/AlwaysOnTraceExample.php
 create mode 100644 resources/Dockerfile.example
 create mode 100755 resources/example-using-docker
 create mode 100644 src/Tracing/Sampler/AlwaysOffSampler.php
 create mode 100644 src/Tracing/Sampler/AlwaysOnSampler.php
 create mode 100644 src/Tracing/Sampler/SamplerInterface.php
 create mode 100644 tests/unit/Tracing/Sampler/AlwaysOffSamplerTest.php
 create mode 100644 tests/unit/Tracing/Sampler/AlwaysOnSamplerTest.php

diff --git a/README.md b/README.md
index fb950762..a0c54ee7 100644
--- a/README.md
+++ b/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.
\ No newline at end of file
diff --git a/examples/AlwaysOffTraceExample.php b/examples/AlwaysOffTraceExample.php
new file mode 100644
index 00000000..9ac7197c
--- /dev/null
+++ b/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";
+}
diff --git a/examples/AlwaysOnTraceExample.php b/examples/AlwaysOnTraceExample.php
new file mode 100644
index 00000000..1ee9b72f
--- /dev/null
+++ b/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";
+}
diff --git a/resources/Dockerfile.example b/resources/Dockerfile.example
new file mode 100644
index 00000000..fe44abf4
--- /dev/null
+++ b/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"]
diff --git a/resources/example-using-docker b/resources/example-using-docker
new file mode 100755
index 00000000..d2e0aa5b
--- /dev/null
+++ b/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
diff --git a/src/Tracing/Sampler/AlwaysOffSampler.php b/src/Tracing/Sampler/AlwaysOffSampler.php
new file mode 100644
index 00000000..d1346d7c
--- /dev/null
+++ b/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;
+    }
+} 
diff --git a/src/Tracing/Sampler/AlwaysOnSampler.php b/src/Tracing/Sampler/AlwaysOnSampler.php
new file mode 100644
index 00000000..3b9b3782
--- /dev/null
+++ b/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;
+    }
+} 
diff --git a/src/Tracing/Sampler/SamplerInterface.php b/src/Tracing/Sampler/SamplerInterface.php
new file mode 100644
index 00000000..77b8b1b5
--- /dev/null
+++ b/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();
+} 
diff --git a/tests/unit/Tracing/Sampler/AlwaysOffSamplerTest.php b/tests/unit/Tracing/Sampler/AlwaysOffSamplerTest.php
new file mode 100644
index 00000000..54fad0a8
--- /dev/null
+++ b/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());
+    }
+} 
diff --git a/tests/unit/Tracing/Sampler/AlwaysOnSamplerTest.php b/tests/unit/Tracing/Sampler/AlwaysOnSamplerTest.php
new file mode 100644
index 00000000..3b1ecbf0
--- /dev/null
+++ b/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());
+    }
+}