Add sampler API, use in SDK tracer (#225)

.flake8

@@ -1,3 +1,15 @@
 [flake8]
-ignore = E501,W503,E203
-exclude = .svn,CVS,.bzr,.hg,.git,__pycache__,.tox,ext/opentelemetry-ext-jaeger/src/opentelemetry/ext/jaeger/gen/,ext/opentelemetry-ext-jaeger/build/*
+ignore =
+  E501  # line too long, defer to black
+  F401  # unused import, defer to pylint
+  W503  # allow line breaks after binary ops, not after
+exclude =
+  .bzr
+  .git
+  .hg
+  .svn
+  .tox
+  CVS
+  __pycache__
+  ext/opentelemetry-ext-jaeger/src/opentelemetry/ext/jaeger/gen/
+  ext/opentelemetry-ext-jaeger/build/*

.pylintrc

@@ -68,7 +68,8 @@ disable=missing-docstring,
       ungrouped-imports, # Leave this up to isort
       wrong-import-order, # Leave this up to isort
       bad-continuation, # Leave this up to black
-      line-too-long # Leave this up to black
+      line-too-long, # Leave this up to black
+      exec-used
 
 # Enable the message, report, category or checker with the given id(s). You can
 # either give multiple identifier separated by comma (,) or put this option

docs/conf.py

@@ -19,7 +19,7 @@
 # -- Project information -----------------------------------------------------
 
 project = "OpenTelemetry"
-copyright = "2019, OpenTelemetry Authors"
+copyright = "2019, OpenTelemetry Authors"  # pylint: disable=redefined-builtin
 author = "OpenTelemetry Authors"
 
 

opentelemetry-api/src/opentelemetry/trace/__init__.py

@@ -257,8 +257,8 @@ def __exit__(
 class TraceOptions(int):
     """A bitmask that represents options specific to the trace.
 
-    The only supported option is the "recorded" flag (``0x01``). If set, this
-    flag indicates that the trace may have been recorded upstream.
+    The only supported option is the "sampled" flag (``0x01``). If set, this
+    flag indicates that the trace may have been sampled upstream.
 
     See the `W3C Trace Context - Traceparent`_ spec for details.
 
@@ -267,12 +267,16 @@ class TraceOptions(int):
     """
 
     DEFAULT = 0x00
-    RECORDED = 0x01
+    SAMPLED = 0x01
 
     @classmethod
     def get_default(cls) -> "TraceOptions":
         return cls(cls.DEFAULT)
 
+    @property
+    def sampled(self) -> bool:
+        return bool(self & TraceOptions.SAMPLED)
+
 
 DEFAULT_TRACE_OPTIONS = TraceOptions.get_default()
 
@@ -313,8 +317,8 @@ class SpanContext:
     Args:
         trace_id: The ID of the trace that this span belongs to.
         span_id: This span's ID.
-        options: Trace options to propagate.
-        state: Tracing-system-specific info to propagate.
+        trace_options: Trace options to propagate.
+        trace_state: Tracing-system-specific info to propagate.
     """
 
     def __init__(
@@ -367,6 +371,9 @@ def __init__(self, context: "SpanContext") -> None:
     def get_context(self) -> "SpanContext":
         return self._context
 
+    def is_recording_events(self) -> bool:
+        return False
+
 
 INVALID_SPAN_ID = 0x0000000000000000
 INVALID_TRACE_ID = 0x00000000000000000000000000000000

opentelemetry-api/src/opentelemetry/trace/sampling.py

@@ -0,0 +1,125 @@
+# Copyright 2019, OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import abc
+from typing import Dict, Mapping, Optional, Sequence
+
+# pylint: disable=unused-import
+from opentelemetry.trace import Link, SpanContext
+from opentelemetry.util.types import AttributeValue
+
+
+class Decision:
+    """A sampling decision as applied to a newly-created Span.
+
+    Args:
+        sampled: Whether the `Span` should be sampled.
+        attributes: Attributes to add to the `Span`.
+    """
+
+    def __repr__(self) -> str:
+        return "{}({}, attributes={})".format(
+            type(self).__name__, str(self.sampled), str(self.attributes)
+        )
+
+    def __init__(
+        self,
+        sampled: bool = False,
+        attributes: Mapping[str, "AttributeValue"] = None,
+    ) -> None:
+        self.sampled = sampled  # type: bool
+        if attributes is None:
+            self.attributes = {}  # type: Dict[str, "AttributeValue"]
+        else:
+            self.attributes = dict(attributes)
+
+
+class Sampler(abc.ABC):
+    @abc.abstractmethod
+    def should_sample(
+        self,
+        parent_context: Optional["SpanContext"],
+        trace_id: int,
+        span_id: int,
+        name: str,
+        links: Sequence["Link"] = (),
+    ) -> "Decision":
+        pass
+
+
+class StaticSampler(Sampler):
+    """Sampler that always returns the same decision."""
+
+    def __init__(self, decision: "Decision"):
+        self._decision = decision
+
+    def should_sample(
+        self,
+        parent_context: Optional["SpanContext"],
+        trace_id: int,
+        span_id: int,
+        name: str,
+        links: Sequence["Link"] = (),
+    ) -> "Decision":
+        return self._decision
+
+
+class ProbabilitySampler(Sampler):
+    def __init__(self, rate: float):
+        self._rate = rate
+        self._bound = self.get_bound_for_rate(self._rate)
+
+    # The sampler checks the last 8 bytes of the trace ID to decide whether to
+    # sample a given trace.
+    CHECK_BYTES = 0xFFFFFFFFFFFFFFFF
+
+    @classmethod
+    def get_bound_for_rate(cls, rate: float) -> int:
+        return round(rate * (cls.CHECK_BYTES + 1))
+
+    @property
+    def rate(self) -> float:
+        return self._rate
+
+    @rate.setter
+    def rate(self, new_rate: float) -> None:
+        self._rate = new_rate
+        self._bound = self.get_bound_for_rate(self._rate)
+
+    @property
+    def bound(self) -> int:
+        return self._bound
+
+    def should_sample(
+        self,
+        parent_context: Optional["SpanContext"],
+        trace_id: int,
+        span_id: int,
+        name: str,
+        links: Sequence["Link"] = (),
+    ) -> "Decision":
+        if parent_context is not None:
+            return Decision(parent_context.trace_options.sampled)
+
+        return Decision(trace_id & self.CHECK_BYTES < self.bound)
+
+
+# Samplers that ignore the parent sampling decision and never/always sample.
+ALWAYS_OFF = StaticSampler(Decision(False))
+ALWAYS_ON = StaticSampler(Decision(True))
+
+# Samplers that respect the parent sampling decision, but otherwise
+# never/always sample.
+DEFAULT_OFF = ProbabilitySampler(0.0)
+DEFAULT_ON = ProbabilitySampler(1.0)