diff --git a/docs/conf.py b/docs/conf.py index 538472cf052..aa0b4096bc2 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -12,12 +12,21 @@ import os import sys +from os import listdir +from os.path import isdir, join -sys.path[:0] = [ +source_dirs = [ os.path.abspath("../opentelemetry-api/src/"), - os.path.abspath("../ext/opentelemetry-ext-opentracing-shim/src/"), + os.path.abspath("../opentelemetry-sdk/src/"), ] +ext = "../ext" +ext_dirs = [ + os.path.abspath("/".join(["../ext", f, "src"])) + for f in listdir(ext) + if isdir(join(ext, f)) +] +sys.path[:0] = source_dirs + ext_dirs # -- Project information ----------------------------------------------------- @@ -64,7 +73,12 @@ # Sphinx does not recognize generic type TypeVars # Container supposedly were fixed, but does not work # https://github.com/sphinx-doc/sphinx/pull/3744 -nitpick_ignore = [("py:class", "ValueT"), ("py:class", "typing.Tuple")] +nitpick_ignore = [ + ("py:class", "ValueT"), + ("py:class", "MetricT"), + ("py:class", "typing.Tuple"), + ("py:class", "pymongo.monitoring.CommandListener"), +] # Add any paths that contain templates here, relative to this directory. templates_path = ["_templates"] diff --git a/docs/index.rst b/docs/index.rst index b98ef55316b..c597d4a681f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,24 +3,42 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -OpenTelemetry API -================= +OpenTelemetry +============= -Welcome to OpenTelemetry's API documentation! +Welcome to OpenTelemetry's documentation! -This documentation describes the ``opentelemetry-api`` package, which provides -abstract types for OpenTelemetry implementations. +This documentation describes the ``opentelemetry-api``, ``opentelemetry-sdk`` +and integration packages. .. toctree:: :maxdepth: 1 - :caption: Contents: + :caption: OpenTelemetry API: opentelemetry.context opentelemetry.metrics opentelemetry.trace opentelemetry.util.loader - opentelemetry.ext.opentracing_shim +.. toctree:: + :maxdepth: 1 + :caption: OpenTelemetry SDK: + + opentelemetry.sdk.context + opentelemetry.sdk.metrics + opentelemetry.sdk.trace + + +.. toctree:: + :maxdepth: 1 + :caption: OpenTelemetry Integrations: + + opentelemetry.ext.flask + opentelemetry.ext.http_requests + opentelemetry.ext.jaeger + opentelemetry.ext.opentracing_shim + opentelemetry.ext.pymongo + opentelemetry.ext.wsgi Indices and tables ================== diff --git a/docs/opentelemetry.ext.flask.rst b/docs/opentelemetry.ext.flask.rst new file mode 100644 index 00000000000..87ad93b867f --- /dev/null +++ b/docs/opentelemetry.ext.flask.rst @@ -0,0 +1,10 @@ +opentelemetry.ext.flask package +========================================== + +Module contents +--------------- + +.. automodule:: opentelemetry.ext.flask + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/opentelemetry.ext.http_requests.rst b/docs/opentelemetry.ext.http_requests.rst new file mode 100644 index 00000000000..fbc9bd2a630 --- /dev/null +++ b/docs/opentelemetry.ext.http_requests.rst @@ -0,0 +1,10 @@ +opentelemetry.ext.http_requests package +========================================== + +Module contents +--------------- + +.. automodule:: opentelemetry.ext.http_requests + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/opentelemetry.ext.jaeger.gen.jaeger.ttypes.rst b/docs/opentelemetry.ext.jaeger.gen.jaeger.ttypes.rst new file mode 100644 index 00000000000..8b69e013b42 --- /dev/null +++ b/docs/opentelemetry.ext.jaeger.gen.jaeger.ttypes.rst @@ -0,0 +1,11 @@ +opentelemetry.ext.jaeger.gen.jaeger.ttypes +========================================== + + +Module contents +--------------- + +.. automodule:: opentelemetry.ext.jaeger.gen.jaeger.ttypes + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/opentelemetry.ext.jaeger.rst b/docs/opentelemetry.ext.jaeger.rst new file mode 100644 index 00000000000..74a7fb399e6 --- /dev/null +++ b/docs/opentelemetry.ext.jaeger.rst @@ -0,0 +1,19 @@ +opentelemetry.ext.jaeger package +========================================== + + +Submodules +---------- + +.. toctree:: + + opentelemetry.ext.jaeger.gen.jaeger.ttypes + + +Module contents +--------------- + +.. automodule:: opentelemetry.ext.jaeger + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/opentelemetry.ext.pymongo.rst b/docs/opentelemetry.ext.pymongo.rst new file mode 100644 index 00000000000..e5c262ac162 --- /dev/null +++ b/docs/opentelemetry.ext.pymongo.rst @@ -0,0 +1,10 @@ +opentelemetry.ext.pymongo package +========================================== + +Module contents +--------------- + +.. automodule:: opentelemetry.ext.pymongo + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/opentelemetry.ext.wsgi.rst b/docs/opentelemetry.ext.wsgi.rst new file mode 100644 index 00000000000..506bc1efe43 --- /dev/null +++ b/docs/opentelemetry.ext.wsgi.rst @@ -0,0 +1,10 @@ +opentelemetry.ext.wsgi package +========================================== + +Module contents +--------------- + +.. automodule:: opentelemetry.ext.wsgi + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/opentelemetry.sdk.context.rst b/docs/opentelemetry.sdk.context.rst new file mode 100644 index 00000000000..12b15b1ed8d --- /dev/null +++ b/docs/opentelemetry.sdk.context.rst @@ -0,0 +1,7 @@ +opentelemetry.sdk.context +========================================== + +.. automodule:: opentelemetry.sdk.context + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/opentelemetry.sdk.metrics.rst b/docs/opentelemetry.sdk.metrics.rst new file mode 100644 index 00000000000..6d646c3b15f --- /dev/null +++ b/docs/opentelemetry.sdk.metrics.rst @@ -0,0 +1,7 @@ +opentelemetry.sdk.metrics package +========================================== + +.. automodule:: opentelemetry.sdk.metrics + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/opentelemetry.sdk.trace.export.rst b/docs/opentelemetry.sdk.trace.export.rst new file mode 100644 index 00000000000..b876f366fd7 --- /dev/null +++ b/docs/opentelemetry.sdk.trace.export.rst @@ -0,0 +1,7 @@ +opentelemetry.sdk.trace.export +========================================== + +.. automodule:: opentelemetry.sdk.trace.export + :members: + :undoc-members: + :show-inheritance: \ No newline at end of file diff --git a/docs/opentelemetry.sdk.trace.rst b/docs/opentelemetry.sdk.trace.rst new file mode 100644 index 00000000000..7bb3569fe63 --- /dev/null +++ b/docs/opentelemetry.sdk.trace.rst @@ -0,0 +1,14 @@ +opentelemetry.sdk.trace package +========================================== + +Submodules +---------- + +.. toctree:: + + opentelemetry.sdk.trace.export + +.. automodule:: opentelemetry.sdk.trace + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/opentelemetry.trace.rst b/docs/opentelemetry.trace.rst index a57b5dcbff8..bfef5839bf0 100644 --- a/docs/opentelemetry.trace.rst +++ b/docs/opentelemetry.trace.rst @@ -6,9 +6,10 @@ Submodules .. toctree:: + opentelemetry.trace.sampling opentelemetry.trace.status Module contents --------------- -.. automodule:: opentelemetry.trace \ No newline at end of file +.. automodule:: opentelemetry.trace diff --git a/docs/opentelemetry.trace.sampling.rst b/docs/opentelemetry.trace.sampling.rst new file mode 100644 index 00000000000..09a77b166ea --- /dev/null +++ b/docs/opentelemetry.trace.sampling.rst @@ -0,0 +1,7 @@ +opentelemetry.trace.sampling +============================ + +.. automodule:: opentelemetry.trace.sampling + :members: + :undoc-members: + :show-inheritance: diff --git a/ext/opentelemetry-ext-opentracing-shim/src/opentelemetry/ext/opentracing_shim/__init__.py b/ext/opentelemetry-ext-opentracing-shim/src/opentelemetry/ext/opentracing_shim/__init__.py index a9e74dbc58f..0f2328a6519 100644 --- a/ext/opentelemetry-ext-opentracing-shim/src/opentelemetry/ext/opentracing_shim/__init__.py +++ b/ext/opentelemetry-ext-opentracing-shim/src/opentelemetry/ext/opentracing_shim/__init__.py @@ -303,14 +303,15 @@ class ScopeShim(opentracing.Scope): It is necessary to have both ways for constructing `ScopeShim` objects because in some cases we need to create the object from an OpenTelemetry - `Span` context manager (as returned by + `opentelemetry.trace.Span` context manager (as returned by :meth:`opentelemetry.trace.Tracer.use_span`), in which case our only way of - retrieving a `Span` object is by calling the ``__enter__()`` method on the - context manager, which makes the span active in the OpenTelemetry tracer; - whereas in other cases we need to accept a `SpanShim` object and wrap it in - a `ScopeShim`. The former is used mainly when the instrumentation code - retrieves the currently-active span using `ScopeManagerShim.active`. The - latter is mainly used when the instrumentation code activates a span using + retrieving a `opentelemetry.trace.Span` object is by calling the + ``__enter__()`` method on the context manager, which makes the span active + in the OpenTelemetry tracer; whereas in other cases we need to accept a + `SpanShim` object and wrap it in a `ScopeShim`. The former is used mainly + when the instrumentation code retrieves the currently-active span using + `ScopeManagerShim.active`. The latter is mainly used when the + instrumentation code activates a span using :meth:`ScopeManagerShim.activate`. Args: @@ -318,12 +319,14 @@ class ScopeShim(opentracing.Scope): :class:`ScopeShim`. span: The :class:`SpanShim` this :class:`ScopeShim` controls. span_cm(:class:`contextlib.AbstractContextManager`, optional): A - Python context manager which yields an OpenTelemetry `Span` from - its ``__enter__()`` method. Used by :meth:`from_context_manager` to - store the context manager as an attribute so that it can later be - closed by calling its ``__exit__()`` method. Defaults to `None`. - - TODO: Is :class:`contextlib.AbstractContextManager` the correct type for *span_cm*? + Python context manager which yields an OpenTelemetry + `opentelemetry.trace.Span` from its ``__enter__()`` method. Used + by :meth:`from_context_manager` to store the context manager as + an attribute so that it can later be closed by calling its + ``__exit__()`` method. Defaults to `None`. + + TODO: Is :class:`contextlib.AbstractContextManager` the correct + type for *span_cm*? """ def __init__(self, manager, span, span_cm=None): @@ -334,12 +337,13 @@ def __init__(self, manager, span, span_cm=None): # need to get rid of `manager.tracer` for this. @classmethod def from_context_manager(cls, manager, span_cm): - """Constructs a :class:`ScopeShim` from an OpenTelemetry `Span` context + """Constructs a :class:`ScopeShim` from an OpenTelemetry + `opentelemetry.trace.Span` context manager. - The method extracts a `Span` object from the context manager by calling - the context manager's ``__enter__()`` method. This causes the span to - start in the OpenTelemetry tracer. + The method extracts a `opentelemetry.trace.Span` object from the + context manager by calling the context manager's ``__enter__()`` + method. This causes the span to start in the OpenTelemetry tracer. Example usage:: @@ -353,7 +357,7 @@ def from_context_manager(cls, manager, span_cm): Args: manager: The :class:`ScopeManagerShim` that created this :class:`ScopeShim`. - span_cm: An OpenTelemetry `Span` context manager as returned by + span_cm: A context manager as returned by :meth:`opentelemetry.trace.Tracer.use_span`. """ @@ -396,7 +400,7 @@ def close(self): class ScopeManagerShim(opentracing.ScopeManager): """Implements :class:`opentracing.ScopeManager` by setting and getting the - active `Span` in the OpenTelemetry tracer. + active `opentelemetry.trace.Span` in the OpenTelemetry tracer. This class keeps a reference to a :class:`TracerShim` as an attribute. This reference is used to communicate with the OpenTelemetry tracer. It is diff --git a/ext/opentelemetry-ext-pymongo/src/opentelemetry/ext/pymongo/__init__.py b/ext/opentelemetry-ext-pymongo/src/opentelemetry/ext/pymongo/__init__.py index fa1cc1583e1..8c49892e0f3 100644 --- a/ext/opentelemetry-ext-pymongo/src/opentelemetry/ext/pymongo/__init__.py +++ b/ext/opentelemetry-ext-pymongo/src/opentelemetry/ext/pymongo/__init__.py @@ -42,6 +42,7 @@ def __init__(self, tracer): self._span_dict = {} def started(self, event: monitoring.CommandStartedEvent): + """ Method to handle a pymongo CommandStartedEvent """ command = event.command.get(event.command_name, "") name = DATABASE_TYPE + "." + event.command_name statement = event.command_name @@ -77,6 +78,7 @@ def started(self, event: monitoring.CommandStartedEvent): self._remove_span(event) def succeeded(self, event: monitoring.CommandSucceededEvent): + """ Method to handle a pymongo CommandSucceededEvent """ span = self._get_span(event) if span is not None: span.set_attribute( @@ -87,6 +89,7 @@ def succeeded(self, event: monitoring.CommandSucceededEvent): self._remove_span(event) def failed(self, event: monitoring.CommandFailedEvent): + """ Method to handle a pymongo CommandFailedEvent """ span = self._get_span(event) if span is not None: span.set_attribute( diff --git a/opentelemetry-api/src/opentelemetry/trace/sampling.py b/opentelemetry-api/src/opentelemetry/trace/sampling.py index e0f5f17c756..2425c27c072 100644 --- a/opentelemetry-api/src/opentelemetry/trace/sampling.py +++ b/opentelemetry-api/src/opentelemetry/trace/sampling.py @@ -24,8 +24,8 @@ 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`. + sampled: Whether the `opentelemetry.trace.Span` should be sampled. + attributes: Attributes to add to the `opentelemetry.trace.Span`. """ def __repr__(self) -> str: diff --git a/opentelemetry-sdk/src/opentelemetry/sdk/__init__.py b/opentelemetry-sdk/src/opentelemetry/sdk/__init__.py index 0f3bff4571e..7b87f0d8f6a 100644 --- a/opentelemetry-sdk/src/opentelemetry/sdk/__init__.py +++ b/opentelemetry-sdk/src/opentelemetry/sdk/__init__.py @@ -12,6 +12,10 @@ # See the License for the specific language governing permissions and # limitations under the License. +""" +The OpenTelemetry SDK package is an implementation of the OpenTelemetry +API +""" from . import metrics, trace, util __all__ = ["metrics", "trace", "util"] diff --git a/opentelemetry-sdk/src/opentelemetry/sdk/metrics/__init__.py b/opentelemetry-sdk/src/opentelemetry/sdk/metrics/__init__.py index 753c35a32e7..f0c3e0e6d33 100644 --- a/opentelemetry-sdk/src/opentelemetry/sdk/metrics/__init__.py +++ b/opentelemetry-sdk/src/opentelemetry/sdk/metrics/__init__.py @@ -24,7 +24,7 @@ # pylint: disable=redefined-outer-name class LabelSet(metrics_api.LabelSet): - """See `opentelemetry.metrics.LabelSet.""" + """See `opentelemetry.metrics.LabelSet`.""" def __init__(self, labels: Dict[str, str] = None): self.labels = labels diff --git a/opentelemetry-sdk/src/opentelemetry/sdk/trace/__init__.py b/opentelemetry-sdk/src/opentelemetry/sdk/trace/__init__.py index 70f7d3f2b04..140626aa94d 100644 --- a/opentelemetry-sdk/src/opentelemetry/sdk/trace/__init__.py +++ b/opentelemetry-sdk/src/opentelemetry/sdk/trace/__init__.py @@ -25,7 +25,7 @@ from opentelemetry.context import Context from opentelemetry.sdk import util from opentelemetry.sdk.util import BoundedDict, BoundedList -from opentelemetry.trace import sampling +from opentelemetry.trace import SpanContext, sampling from opentelemetry.trace.status import Status, StatusCanonicalCode from opentelemetry.util import time_ns, types @@ -37,36 +37,36 @@ class SpanProcessor: - """Interface which allows hooks for SDK's `Span`s start and end method + """Interface which allows hooks for SDK's `Span` start and end method invocations. Span processors can be registered directly using - :func:`~Tracer:add_span_processor` and they are invoked in the same order + :func:`Tracer.add_span_processor` and they are invoked in the same order as they were registered. """ def on_start(self, span: "Span") -> None: - """Called when a :class:`Span` is started. + """Called when a :class:`opentelemetry.trace.Span` is started. This method is called synchronously on the thread that starts the span, therefore it should not block or throw an exception. Args: - span: The :class:`Span` that just started. + span: The :class:`opentelemetry.trace.Span` that just started. """ def on_end(self, span: "Span") -> None: - """Called when a :class:`Span` is ended. + """Called when a :class:`opentelemetry.trace.Span` is ended. This method is called synchronously on the thread that ends the span, therefore it should not block or throw an exception. Args: - span: The :class:`Span` that just ended. + span: The :class:`opentelemetry.trace.Span` that just ended. """ def shutdown(self) -> None: - """Called when a :class:`Tracer` is shutdown.""" + """Called when a :class:`opentelemetry.sdk.trace.Tracer` is shutdown.""" class MultiSpanProcessor(SpanProcessor): @@ -101,7 +101,8 @@ def shutdown(self) -> None: class Span(trace_api.Span): """See `opentelemetry.trace.Span`. - Users should create `Span`s via the `Tracer` instead of this constructor. + Users should create `Span` objects via the `Tracer` instead of this + constructor. Args: name: The name of the operation this span represents @@ -376,7 +377,7 @@ def start_span( # pylint: disable=too-many-locals links: Sequence[trace_api.Link] = (), start_time: Optional[int] = None, set_status_on_exception: bool = True, - ) -> "Span": + ) -> trace_api.Span: """See `opentelemetry.trace.Tracer.start_span`.""" if parent is Tracer.CURRENT_SPAN: diff --git a/opentelemetry-sdk/src/opentelemetry/sdk/trace/export/__init__.py b/opentelemetry-sdk/src/opentelemetry/sdk/trace/export/__init__.py index 442b2b2bac2..36459c5b73a 100644 --- a/opentelemetry-sdk/src/opentelemetry/sdk/trace/export/__init__.py +++ b/opentelemetry-sdk/src/opentelemetry/sdk/trace/export/__init__.py @@ -38,15 +38,15 @@ class SpanExporter: Interface to be implemented by services that want to export recorded in its own format. - To export data this MUST be registered to the :class`..Tracer` using a - `SimpleExportSpanProcessor` or a `BatchSpanProcessor`. + To export data this MUST be registered to the :class`opentelemetry.sdk.trace.Tracer` using a + `SimpleExportSpanProcessor` or a `BatchExportSpanProcessor`. """ def export(self, spans: typing.Sequence[Span]) -> "SpanExportResult": """Exports a batch of telemetry data. Args: - spans: The list of `Span`s to be exported + spans: The list of `opentelemetry.trace.Span` objects to be exported Returns: The result of the export diff --git a/tox.ini b/tox.ini index 520d6ee3944..2ded7d1b753 100644 --- a/tox.ini +++ b/tox.ini @@ -117,6 +117,9 @@ deps = sphinx-autodoc-typehints opentracing~=2.2.0 Deprecated>=1.2.6 + thrift>=0.10.0 + pymongo ~= 3.1 + flask~=1.0 changedir = docs