From fe4e2d93f276cbd5d978a4e62121239e03a3d38c Mon Sep 17 00:00:00 2001 From: Chris Kleinknecht Date: Mon, 3 Jun 2019 16:56:48 -0700 Subject: [PATCH 01/24] Add initial tracer API --- opentelemetry/__init__.py | 0 opentelemetry/api/__init__.py | 0 opentelemetry/api/trace/__init__.py | 190 ++++++++++++++++++++++++++++ 3 files changed, 190 insertions(+) create mode 100644 opentelemetry/__init__.py create mode 100644 opentelemetry/api/__init__.py create mode 100644 opentelemetry/api/trace/__init__.py diff --git a/opentelemetry/__init__.py b/opentelemetry/__init__.py new file mode 100644 index 0000000000..e69de29bb2 diff --git a/opentelemetry/api/__init__.py b/opentelemetry/api/__init__.py new file mode 100644 index 0000000000..e69de29bb2 diff --git a/opentelemetry/api/trace/__init__.py b/opentelemetry/api/trace/__init__.py new file mode 100644 index 0000000000..590ae03de0 --- /dev/null +++ b/opentelemetry/api/trace/__init__.py @@ -0,0 +1,190 @@ +# 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. + +""" +The OpenTelemetry tracing API describes the classes used to generate +distributed traces. + +The :class:`.Tracer` class controls access to the execution context, and +manages span creation. Each operation in a trace is represented by a +:class:`.Span`, which records the start, end time, and metadata associated with +the operation. + +This module provides abstract (i.e. unimplemented) classes required for +tracing, and a concrete no-op ``BlankSpan`` that allows applications to use the +API package alone without a supporting implementation. + +The tracer supports implicit and explicit context propagation. By default spans +are created as children of the currently active span, and the newly-created +span becomes the new active span:: + + from opentelemetry.sdk.trace import tracer + + # Create a new root span, set it as the current span in context + with tracer.span("parent"): + # Attach a new child and update the current span + with tracer.span("child"): + do_work(): + # Close child span, set parent as current + # Close parent span, set default span as current + +Under explicit context propagation there is no concept of an active span, and +the caller is responsible for managing the span's lifetime:: + + from opentelemetry.sdk.trace import tracer + from your.integration import deserialize_span + + parent = deserialize_span(serialized_span) + # Explicit parent span assignment + with tracer.span("child", parent=parent) as child: + do_work(span=child) + +Applications should generally use a single global tracer, and use either +implicit or explicit context propagation consistently throughout. + +.. versionadded:: 0.1.0 +""" + +from __future__ import annotations + +from typing import Iterator +from contextlib import contextmanager + + +class Tracer(object): + """Handles span creation and in-process context propagation. + + This class provides methods for manipulating the context, creating spans, + and controlling spans' lifecycles. + """ + + def get_current_span(self) -> Span: + """Get the currently active span from the context. + + Returns: + The currently active :class:`.Span`. + """ + raise NotImplementedError + + @contextmanager + def span(self, name: str, parent: Span=None) -> Iterator[None]: + """Context manager for span creation. + + Create a new child of the current span, or create a root span if no + current span exists. Start the span and set it as the current span in + this tracer's context. + + On exiting the context manager stop the span and set its parent as the + current span. + + Example:: + + with tracer.span("one") as parent: + parent.add_event("parent's event") + with tracer.span("two") as child: + child.add_event("child's event") + tracer.get_current_span() # returns child + tracer.get_current_span() # returns parent + tracer.get_current_span() # returns the previously active span + + Args: + name: The name of the span to be created. + parent: This span's parent. + + Raises: + ValueError: if ``name`` is null. + """ + raise NotImplementedError + + def create_span(self, name: str, parent: Span=None) -> Span: + """Create a new span as a child of the currently active span. + + If called with ``parent`` this method won't affect the tracer's + context. + + See ``span`` for a context manager that controls the span's lifetime. + + Args: + name: The name of the span to be created. + parent: This span's parent. + + Raises: + ValueError: if ``name`` is null. + """ + raise NotImplementedError + + +class Span(object): + """A span represents a single operation within a trace. + """ + + def start(self) -> None: + """Set the current time as the span's start time. + + Each span represents a single operation. The span's start time is the + wall time at which the operation started. + + Only the first call to ``start`` should modify the span, and + implementations are free to ignore or raise on further calls. + """ + raise NotImplementedError + + def end(self) -> None: + """Set the current time as the span's end time. + + The span's end time is the wall time at which the operation finished. + + Only the first call to ``end`` should modify the span, and + implementations are free to ignore or raise on further calls. + """ + raise NotImplementedError + + def get_context(self) -> SpanContext: + """Get an immutable snapshot of this span. + + Returns: + A :class:`.SpanContext` with a copy of this span's immutable state. + """ + raise NotImplementedError + + +class SpanContext(object): + """The state of a Span to propagate between processes. + + This class includes the immutable attributes of a :class:`.Span` that must + be propagated to a span's children and across process boundaries. + + Args: + trace_id: The ID of the trace that this span belongs to. + span_id: This span's ID. + options: Global trace options to propagate. + state: Global tracing-system-specific info to propagate. + """ + + def __init__(self, + trace_id: str, + span_id: str, + options: TraceOptions, + state: TraceState) -> SpanContext: + pass + + +# TODO +class TraceOptions(int): + pass + + +# TODO +class TraceState(dict): + pass From 4456ea1bfb339fec755d32c099b4bcdd454e5f6b Mon Sep 17 00:00:00 2001 From: Chris Kleinknecht Date: Tue, 4 Jun 2019 15:09:31 -0700 Subject: [PATCH 02/24] Fix context manager type hint --- opentelemetry/api/trace/__init__.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/opentelemetry/api/trace/__init__.py b/opentelemetry/api/trace/__init__.py index 590ae03de0..833cbc507e 100644 --- a/opentelemetry/api/trace/__init__.py +++ b/opentelemetry/api/trace/__init__.py @@ -78,7 +78,7 @@ def get_current_span(self) -> Span: raise NotImplementedError @contextmanager - def span(self, name: str, parent: Span=None) -> Iterator[None]: + def span(self, name: str, parent: Span=None) -> Iterator[Span]: """Context manager for span creation. Create a new child of the current span, or create a root span if no From 49a9db1c9cba0e99c15fc2c554fa271e05f4363b Mon Sep 17 00:00:00 2001 From: Chris Kleinknecht Date: Wed, 5 Jun 2019 13:10:56 -0700 Subject: [PATCH 03/24] Update opentelemetry/api/trace/__init__.py MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Christian Neumüller --- opentelemetry/api/trace/__init__.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/opentelemetry/api/trace/__init__.py b/opentelemetry/api/trace/__init__.py index 590ae03de0..263eda4fef 100644 --- a/opentelemetry/api/trace/__init__.py +++ b/opentelemetry/api/trace/__init__.py @@ -100,7 +100,7 @@ def span(self, name: str, parent: Span=None) -> Iterator[None]: Args: name: The name of the span to be created. - parent: This span's parent. + parent: The new span's parent. Raises: ValueError: if ``name`` is null. From 750a8d3226db108d0fe776445d9508a14a882067 Mon Sep 17 00:00:00 2001 From: Chris Kleinknecht Date: Wed, 5 Jun 2019 13:13:46 -0700 Subject: [PATCH 04/24] Add "Yields" to span docstring, remove "Raises" --- opentelemetry/api/trace/__init__.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/opentelemetry/api/trace/__init__.py b/opentelemetry/api/trace/__init__.py index d75163ec19..4e52c1d682 100644 --- a/opentelemetry/api/trace/__init__.py +++ b/opentelemetry/api/trace/__init__.py @@ -100,10 +100,10 @@ def span(self, name: str, parent: Span=None) -> Iterator[Span]: Args: name: The name of the span to be created. - parent: The new span's parent. + parent: This span's parent. - Raises: - ValueError: if ``name`` is null. + Yields: + The newly-created span. """ raise NotImplementedError From dd8fab2683bd4ce44a3cbf7baeabd84db5266d11 Mon Sep 17 00:00:00 2001 From: Chris Kleinknecht Date: Wed, 5 Jun 2019 13:17:06 -0700 Subject: [PATCH 05/24] Change get_context docstring --- opentelemetry/api/trace/__init__.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/opentelemetry/api/trace/__init__.py b/opentelemetry/api/trace/__init__.py index 4e52c1d682..d1366b15bf 100644 --- a/opentelemetry/api/trace/__init__.py +++ b/opentelemetry/api/trace/__init__.py @@ -151,7 +151,10 @@ def end(self) -> None: raise NotImplementedError def get_context(self) -> SpanContext: - """Get an immutable snapshot of this span. + """Get the span's SpanContext. + + Get an immutable, serializable identifier for this span that can be + used to create new child spans. Returns: A :class:`.SpanContext` with a copy of this span's immutable state. From e89b8ea119bf55e2914c8d116244d46ffe014b5f Mon Sep 17 00:00:00 2001 From: Chris Kleinknecht Date: Wed, 5 Jun 2019 13:22:31 -0700 Subject: [PATCH 06/24] Sort imports --- opentelemetry/api/trace/__init__.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/opentelemetry/api/trace/__init__.py b/opentelemetry/api/trace/__init__.py index d1366b15bf..51308d6b7e 100644 --- a/opentelemetry/api/trace/__init__.py +++ b/opentelemetry/api/trace/__init__.py @@ -58,8 +58,8 @@ from __future__ import annotations -from typing import Iterator from contextlib import contextmanager +from typing import Iterator class Tracer(object): From eb32db0617aff68412c7fdfbdb2774578a1cb1a6 Mon Sep 17 00:00:00 2001 From: Chris Kleinknecht Date: Wed, 5 Jun 2019 13:26:53 -0700 Subject: [PATCH 07/24] Remove "global" from span context docstring --- opentelemetry/api/trace/__init__.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/opentelemetry/api/trace/__init__.py b/opentelemetry/api/trace/__init__.py index 51308d6b7e..536a34bcbf 100644 --- a/opentelemetry/api/trace/__init__.py +++ b/opentelemetry/api/trace/__init__.py @@ -171,8 +171,8 @@ class SpanContext(object): Args: trace_id: The ID of the trace that this span belongs to. span_id: This span's ID. - options: Global trace options to propagate. - state: Global tracing-system-specific info to propagate. + options: Trace options to propagate. + state: Tracing-system-specific info to propagate. """ def __init__(self, From 3ca5e78fe4745bc9639761a26514d3678ca1c959 Mon Sep 17 00:00:00 2001 From: Chris Kleinknecht Date: Wed, 5 Jun 2019 16:26:29 -0700 Subject: [PATCH 08/24] Split up span creation managers --- opentelemetry/api/trace/__init__.py | 96 +++++++++++++++++++++-------- 1 file changed, 72 insertions(+), 24 deletions(-) diff --git a/opentelemetry/api/trace/__init__.py b/opentelemetry/api/trace/__init__.py index 536a34bcbf..a0c7a95a17 100644 --- a/opentelemetry/api/trace/__init__.py +++ b/opentelemetry/api/trace/__init__.py @@ -25,30 +25,35 @@ tracing, and a concrete no-op ``BlankSpan`` that allows applications to use the API package alone without a supporting implementation. -The tracer supports implicit and explicit context propagation. By default spans -are created as children of the currently active span, and the newly-created -span becomes the new active span:: +The tracer supports creating spans that are "attached" or "detached" from the +context. By default, new spans are "attached" to the context in that they are +created as children of the currently active span, and the newly-created span +becomes the new active span:: from opentelemetry.sdk.trace import tracer # Create a new root span, set it as the current span in context - with tracer.span("parent"): + with tracer.start_span("parent"): # Attach a new child and update the current span - with tracer.span("child"): + with tracer.start_span("child"): do_work(): # Close child span, set parent as current # Close parent span, set default span as current -Under explicit context propagation there is no concept of an active span, and -the caller is responsible for managing the span's lifetime:: +When creating a span that's "detached" from the context the active span doesn't +change, and the caller is responsible for managing the span's lifetime:: from opentelemetry.sdk.trace import tracer - from your.integration import deserialize_span - parent = deserialize_span(serialized_span) # Explicit parent span assignment - with tracer.span("child", parent=parent) as child: + span = tracer.create_span("child", parent=parent) as child: + + # The caller is responsible for starting and ending the span + span.start() + try: do_work(span=child) + finally: + span.end() Applications should generally use a single global tracer, and use either implicit or explicit context propagation consistently throughout. @@ -72,13 +77,18 @@ class Tracer(object): def get_current_span(self) -> Span: """Get the currently active span from the context. + If there is no current span, return a placeholder span with an invalid + context. + Returns: - The currently active :class:`.Span`. + The currently active :class:`.Span`, or a placeholder span with an + invalid :class:`.SpanContext`. """ raise NotImplementedError + @contextmanager - def span(self, name: str, parent: Span=None) -> Iterator[Span]: + def start_span(self, name: str, parent: Span) -> Iterator[Span]: """Context manager for span creation. Create a new child of the current span, or create a root span if no @@ -98,36 +108,74 @@ def span(self, name: str, parent: Span=None) -> Iterator[Span]: tracer.get_current_span() # returns parent tracer.get_current_span() # returns the previously active span + This is a convenience method for creating spans attached to the + tracer's context. Applications that need more control over the span + lifetime should use :meth:`create_span` instead. For example:: + + with tracer.start_span(name) as span: + do_work() + + is equivalent to:: + + span = tracer.create_span(name, parent=tracer.get_current_span()) + with tracer.use_span(span): + do_work() + Args: name: The name of the span to be created. - parent: This span's parent. + parent: The span's parent. Yields: The newly-created span. """ raise NotImplementedError - def create_span(self, name: str, parent: Span=None) -> Span: - """Create a new span as a child of the currently active span. + def create_span(self, name: str, parent: Span) -> Span: + """Creates a new child span of the given parent. - If called with ``parent`` this method won't affect the tracer's - context. + Creating the span does not start it, and should not affect the tracer's + context. To start the span and update the tracer's context to make it + the currently active span, see :meth:`use_span`. + + Applications that need to explicitly set spans' parents or create spans + detached from the tracer's context should use this method. - See ``span`` for a context manager that controls the span's lifetime. + with tracer.start_span(name) as span: + do_work() + + This is equivalent to:: + + span = tracer.create_span(name, parent=tracer.get_current_span()) + with tracer.use_span(span): + do_work() Args: name: The name of the span to be created. - parent: This span's parent. + parent: The span's parent. + + Returns: + The newly-created span. + """ + raise NotImplementedError - Raises: - ValueError: if ``name`` is null. + @contextmanager + def use_span(self, span: Span) -> Iterator[None]: + """Context manager for controlling a span's lifetime. + + Start the given span and set it as the current span in this tracer's + context. + + On exiting the context manager stop the span and set its parent as the + current span. + + Args: + span: The span to start and make current. """ raise NotImplementedError class Span(object): - """A span represents a single operation within a trace. - """ + """A span represents a single operation within a trace.""" def start(self) -> None: """Set the current time as the span's start time. @@ -179,7 +227,7 @@ def __init__(self, trace_id: str, span_id: str, options: TraceOptions, - state: TraceState) -> SpanContext: + state: TraceState) -> None: pass From c3da103945f67200bad6abfc1b6a39f928e818b0 Mon Sep 17 00:00:00 2001 From: Chris Kleinknecht Date: Wed, 5 Jun 2019 17:14:27 -0700 Subject: [PATCH 09/24] Get declarative --- opentelemetry/api/trace/__init__.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/opentelemetry/api/trace/__init__.py b/opentelemetry/api/trace/__init__.py index a0c7a95a17..19029a9741 100644 --- a/opentelemetry/api/trace/__init__.py +++ b/opentelemetry/api/trace/__init__.py @@ -75,7 +75,7 @@ class Tracer(object): """ def get_current_span(self) -> Span: - """Get the currently active span from the context. + """Gets the currently active span from the context. If there is no current span, return a placeholder span with an invalid context. @@ -178,7 +178,7 @@ class Span(object): """A span represents a single operation within a trace.""" def start(self) -> None: - """Set the current time as the span's start time. + """Sets the current time as the span's start time. Each span represents a single operation. The span's start time is the wall time at which the operation started. @@ -189,7 +189,7 @@ def start(self) -> None: raise NotImplementedError def end(self) -> None: - """Set the current time as the span's end time. + """Sets the current time as the span's end time. The span's end time is the wall time at which the operation finished. @@ -199,7 +199,7 @@ def end(self) -> None: raise NotImplementedError def get_context(self) -> SpanContext: - """Get the span's SpanContext. + """Gets the span's SpanContext. Get an immutable, serializable identifier for this span that can be used to create new child spans. From 946f57df6dddd43cc6d3efb1d2fcc2eb20186590 Mon Sep 17 00:00:00 2001 From: Chris Kleinknecht Date: Thu, 6 Jun 2019 22:04:24 -0700 Subject: [PATCH 10/24] Update tracer method names in docstring --- opentelemetry/api/trace/__init__.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/opentelemetry/api/trace/__init__.py b/opentelemetry/api/trace/__init__.py index 19029a9741..70dd645d4a 100644 --- a/opentelemetry/api/trace/__init__.py +++ b/opentelemetry/api/trace/__init__.py @@ -100,9 +100,9 @@ def start_span(self, name: str, parent: Span) -> Iterator[Span]: Example:: - with tracer.span("one") as parent: + with tracer.start_span("one") as parent: parent.add_event("parent's event") - with tracer.span("two") as child: + with tracer.start_span("two") as child: child.add_event("child's event") tracer.get_current_span() # returns child tracer.get_current_span() # returns parent From dd72455f75b0068bdf87e7415c4e35e4b53ef28d Mon Sep 17 00:00:00 2001 From: Chris Kleinknecht Date: Tue, 18 Jun 2019 19:19:18 -0700 Subject: [PATCH 11/24] Remove references to SDK from API comments --- opentelemetry/api/trace/__init__.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/opentelemetry/api/trace/__init__.py b/opentelemetry/api/trace/__init__.py index 70dd645d4a..00a3ac2c45 100644 --- a/opentelemetry/api/trace/__init__.py +++ b/opentelemetry/api/trace/__init__.py @@ -30,7 +30,8 @@ created as children of the currently active span, and the newly-created span becomes the new active span:: - from opentelemetry.sdk.trace import tracer + # TODO (#15): which module holds the global tracer? + from opentelemetry.api.trace import tracer # Create a new root span, set it as the current span in context with tracer.start_span("parent"): @@ -43,7 +44,7 @@ When creating a span that's "detached" from the context the active span doesn't change, and the caller is responsible for managing the span's lifetime:: - from opentelemetry.sdk.trace import tracer + from opentelemetry.api.trace import tracer # Explicit parent span assignment span = tracer.create_span("child", parent=parent) as child: From 02d810569155e2af0433aecf210d09e59251932b Mon Sep 17 00:00:00 2001 From: Chris Kleinknecht Date: Tue, 18 Jun 2019 19:25:15 -0700 Subject: [PATCH 12/24] s/raise/pass/ --- opentelemetry/api/trace/__init__.py | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/opentelemetry/api/trace/__init__.py b/opentelemetry/api/trace/__init__.py index 00a3ac2c45..6e4fc80f42 100644 --- a/opentelemetry/api/trace/__init__.py +++ b/opentelemetry/api/trace/__init__.py @@ -85,7 +85,7 @@ def get_current_span(self) -> Span: The currently active :class:`.Span`, or a placeholder span with an invalid :class:`.SpanContext`. """ - raise NotImplementedError + pass @contextmanager @@ -129,7 +129,7 @@ def start_span(self, name: str, parent: Span) -> Iterator[Span]: Yields: The newly-created span. """ - raise NotImplementedError + pass def create_span(self, name: str, parent: Span) -> Span: """Creates a new child span of the given parent. @@ -157,7 +157,7 @@ def create_span(self, name: str, parent: Span) -> Span: Returns: The newly-created span. """ - raise NotImplementedError + pass @contextmanager def use_span(self, span: Span) -> Iterator[None]: @@ -172,7 +172,7 @@ def use_span(self, span: Span) -> Iterator[None]: Args: span: The span to start and make current. """ - raise NotImplementedError + pass class Span(object): @@ -187,7 +187,7 @@ def start(self) -> None: Only the first call to ``start`` should modify the span, and implementations are free to ignore or raise on further calls. """ - raise NotImplementedError + pass def end(self) -> None: """Sets the current time as the span's end time. @@ -197,7 +197,7 @@ def end(self) -> None: Only the first call to ``end`` should modify the span, and implementations are free to ignore or raise on further calls. """ - raise NotImplementedError + pass def get_context(self) -> SpanContext: """Gets the span's SpanContext. @@ -208,7 +208,7 @@ def get_context(self) -> SpanContext: Returns: A :class:`.SpanContext` with a copy of this span's immutable state. """ - raise NotImplementedError + pass class SpanContext(object): From de53bbe243297cbac902f8f1cb20c492d8b30360 Mon Sep 17 00:00:00 2001 From: Chris Kleinknecht Date: Mon, 3 Jun 2019 22:54:18 -0700 Subject: [PATCH 13/24] Add files generated by sphinx-quickstart --- docs/Makefile | 19 ++++++++++++++++++ docs/conf.py | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 20 +++++++++++++++++++ docs/make.bat | 35 +++++++++++++++++++++++++++++++++ 4 files changed, 126 insertions(+) create mode 100644 docs/Makefile create mode 100644 docs/conf.py create mode 100644 docs/index.rst create mode 100644 docs/make.bat diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000000..298ea9e213 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,19 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000000..db5c03b847 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,52 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# http://www.sphinx-doc.org/en/master/config + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- Project information ----------------------------------------------------- + +project = 'OpenTelemetry' +copyright = '2019, OpenTelemetry Authors' +author = 'OpenTelemetry Authors' + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'alabaster' + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000000..3632a68a22 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,20 @@ +.. OpenTelemetry documentation master file, created by + sphinx-quickstart on Mon Jun 3 22:48:38 2019. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to OpenTelemetry's documentation! +========================================= + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000000..27f573b87a --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% + +:end +popd From cc889ccb0cc3cf577a25a76dbeceee81050c0173 Mon Sep 17 00:00:00 2001 From: Chris Kleinknecht Date: Mon, 3 Jun 2019 22:55:38 -0700 Subject: [PATCH 14/24] Add files generated by sphinx-apidoc --- docs/modules.rst | 7 +++++++ docs/opentelemetry.api.rst | 17 +++++++++++++++++ docs/opentelemetry.api.trace.rst | 10 ++++++++++ docs/opentelemetry.rst | 17 +++++++++++++++++ 4 files changed, 51 insertions(+) create mode 100644 docs/modules.rst create mode 100644 docs/opentelemetry.api.rst create mode 100644 docs/opentelemetry.api.trace.rst create mode 100644 docs/opentelemetry.rst diff --git a/docs/modules.rst b/docs/modules.rst new file mode 100644 index 0000000000..aa8a3ab502 --- /dev/null +++ b/docs/modules.rst @@ -0,0 +1,7 @@ +opentelemetry +============= + +.. toctree:: + :maxdepth: 4 + + opentelemetry diff --git a/docs/opentelemetry.api.rst b/docs/opentelemetry.api.rst new file mode 100644 index 0000000000..6230957774 --- /dev/null +++ b/docs/opentelemetry.api.rst @@ -0,0 +1,17 @@ +opentelemetry.api package +========================= + +Subpackages +----------- + +.. toctree:: + + opentelemetry.api.trace + +Module contents +--------------- + +.. automodule:: opentelemetry.api + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/opentelemetry.api.trace.rst b/docs/opentelemetry.api.trace.rst new file mode 100644 index 0000000000..775c1e9619 --- /dev/null +++ b/docs/opentelemetry.api.trace.rst @@ -0,0 +1,10 @@ +opentelemetry.api.trace package +=============================== + +Module contents +--------------- + +.. automodule:: opentelemetry.api.trace + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/opentelemetry.rst b/docs/opentelemetry.rst new file mode 100644 index 0000000000..8a52823567 --- /dev/null +++ b/docs/opentelemetry.rst @@ -0,0 +1,17 @@ +opentelemetry package +===================== + +Subpackages +----------- + +.. toctree:: + + opentelemetry.api + +Module contents +--------------- + +.. automodule:: opentelemetry + :members: + :undoc-members: + :show-inheritance: From 229ee1fdc6cd2949db017bff0f905ff162e715f4 Mon Sep 17 00:00:00 2001 From: Chris Kleinknecht Date: Mon, 3 Jun 2019 22:58:17 -0700 Subject: [PATCH 15/24] Add path to conf for autodoc --- docs/conf.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index db5c03b847..773c906b56 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -9,10 +9,10 @@ # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. -# -# import os -# import sys -# sys.path.insert(0, os.path.abspath('.')) + +import os +import sys +sys.path.insert(0, os.path.abspath('..')) # -- Project information ----------------------------------------------------- From 8c1af066341b70f05b9c90cbcc317918edd65ce4 Mon Sep 17 00:00:00 2001 From: Chris Kleinknecht Date: Mon, 3 Jun 2019 22:58:34 -0700 Subject: [PATCH 16/24] Use RTD theme --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 773c906b56..f180b81aa8 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -44,7 +44,7 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = 'alabaster' +html_theme = 'sphinx_rtd_theme' # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, From ad4fa036148c2249d836d06bc9d31b5083f72cff Mon Sep 17 00:00:00 2001 From: Chris Kleinknecht Date: Mon, 3 Jun 2019 22:58:52 -0700 Subject: [PATCH 17/24] Add extensions --- docs/conf.py | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index f180b81aa8..73b1c5fa04 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -28,6 +28,11 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.napoleon', + 'sphinx_autodoc_typehints', + 'sphinx.ext.viewcode', + 'sphinx.ext.intersphinx', ] # Add any paths that contain templates here, relative to this directory. From 0f5b940703f97c0eaf47ff92128986ff7d436b15 Mon Sep 17 00:00:00 2001 From: Chris Kleinknecht Date: Mon, 3 Jun 2019 23:06:58 -0700 Subject: [PATCH 18/24] Touch makefile --- docs/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Makefile b/docs/Makefile index 298ea9e213..51285967a7 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -16,4 +16,4 @@ help: # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) From e67fff7455101167af73cc0dcb89997bf8037cb6 Mon Sep 17 00:00:00 2001 From: Chris Kleinknecht Date: Mon, 3 Jun 2019 23:07:18 -0700 Subject: [PATCH 19/24] Add generated modules to index --- docs/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/index.rst b/docs/index.rst index 3632a68a22..ff4b831484 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -10,6 +10,7 @@ Welcome to OpenTelemetry's documentation! :maxdepth: 2 :caption: Contents: + modules Indices and tables From 8bb8e2fa00a4c9a0e651e3b8fa4cbf1de41cc417 Mon Sep 17 00:00:00 2001 From: Chris Kleinknecht Date: Mon, 3 Jun 2019 23:38:42 -0700 Subject: [PATCH 20/24] Add comments to extensions --- docs/conf.py | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index 73b1c5fa04..163a8f15c2 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -28,10 +28,15 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ + # API doc generation 'sphinx.ext.autodoc', + # Support for google-style docstrings 'sphinx.ext.napoleon', + # Infer types from hints instead of docstrings 'sphinx_autodoc_typehints', + # Add links to source from generated docs 'sphinx.ext.viewcode', + # Link to other sphinx docs 'sphinx.ext.intersphinx', ] From add9fb80537923165f100bbee5091bcab80221b7 Mon Sep 17 00:00:00 2001 From: Chris Kleinknecht Date: Thu, 20 Jun 2019 11:55:54 -0700 Subject: [PATCH 21/24] Move autodoc options to conf --- docs/conf.py | 5 +++++ docs/opentelemetry.api.rst | 3 --- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 163a8f15c2..5782a7bcb4 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -48,6 +48,11 @@ # This pattern also affects html_static_path and html_extra_path. exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] +autodoc_default_options = { + 'members': True, + 'undoc-members': True, + 'show-inheritance': True +} # -- Options for HTML output ------------------------------------------------- diff --git a/docs/opentelemetry.api.rst b/docs/opentelemetry.api.rst index 6230957774..5e42a144c7 100644 --- a/docs/opentelemetry.api.rst +++ b/docs/opentelemetry.api.rst @@ -12,6 +12,3 @@ Module contents --------------- .. automodule:: opentelemetry.api - :members: - :undoc-members: - :show-inheritance: From bb690694d21eb3572b26897d54896cc971e47180 Mon Sep 17 00:00:00 2001 From: Chris Kleinknecht Date: Thu, 20 Jun 2019 11:56:34 -0700 Subject: [PATCH 22/24] Keep source member order in docs --- docs/conf.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 5782a7bcb4..b404887576 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -51,7 +51,8 @@ autodoc_default_options = { 'members': True, 'undoc-members': True, - 'show-inheritance': True + 'show-inheritance': True, + 'member-order': 'bysource' } # -- Options for HTML output ------------------------------------------------- From ed97cf930b11c0a70b974d654caefde0bc359e85 Mon Sep 17 00:00:00 2001 From: Chris Kleinknecht Date: Fri, 21 Jun 2019 12:25:06 -0700 Subject: [PATCH 23/24] Update docs for package move and remove generated API docs other than opencensus.trace. --- docs/conf.py | 2 +- docs/index.rst | 13 +++++++++---- docs/modules.rst | 2 +- docs/opentelemetry.api.rst | 14 -------------- docs/opentelemetry.api.trace.rst | 10 ---------- docs/opentelemetry.rst | 17 ----------------- docs/opentelemetry.trace.rst | 4 ++++ 7 files changed, 15 insertions(+), 47 deletions(-) delete mode 100644 docs/opentelemetry.api.rst delete mode 100644 docs/opentelemetry.api.trace.rst delete mode 100644 docs/opentelemetry.rst create mode 100644 docs/opentelemetry.trace.rst diff --git a/docs/conf.py b/docs/conf.py index b404887576..5e5dbb8576 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -12,7 +12,7 @@ import os import sys -sys.path.insert(0, os.path.abspath('..')) +sys.path.insert(0, os.path.abspath('../opentelemetry-api/')) # -- Project information ----------------------------------------------------- diff --git a/docs/index.rst b/docs/index.rst index ff4b831484..aed678db96 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,14 +3,19 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Welcome to OpenTelemetry's documentation! -========================================= +OpenTelemetry API +================= + +Welcome to OpenTelemetry's API documentation! + +This documentation describes the ``opentelemetry-api`` package, which provides +abstract types for OpenTelemetry implementations. .. toctree:: - :maxdepth: 2 + :maxdepth: 1 :caption: Contents: - modules + opentelemetry.trace Indices and tables diff --git a/docs/modules.rst b/docs/modules.rst index aa8a3ab502..b795cd4515 100644 --- a/docs/modules.rst +++ b/docs/modules.rst @@ -4,4 +4,4 @@ opentelemetry .. toctree:: :maxdepth: 4 - opentelemetry + opentelemetry.trace diff --git a/docs/opentelemetry.api.rst b/docs/opentelemetry.api.rst deleted file mode 100644 index 5e42a144c7..0000000000 --- a/docs/opentelemetry.api.rst +++ /dev/null @@ -1,14 +0,0 @@ -opentelemetry.api package -========================= - -Subpackages ------------ - -.. toctree:: - - opentelemetry.api.trace - -Module contents ---------------- - -.. automodule:: opentelemetry.api diff --git a/docs/opentelemetry.api.trace.rst b/docs/opentelemetry.api.trace.rst deleted file mode 100644 index 775c1e9619..0000000000 --- a/docs/opentelemetry.api.trace.rst +++ /dev/null @@ -1,10 +0,0 @@ -opentelemetry.api.trace package -=============================== - -Module contents ---------------- - -.. automodule:: opentelemetry.api.trace - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/opentelemetry.rst b/docs/opentelemetry.rst deleted file mode 100644 index 8a52823567..0000000000 --- a/docs/opentelemetry.rst +++ /dev/null @@ -1,17 +0,0 @@ -opentelemetry package -===================== - -Subpackages ------------ - -.. toctree:: - - opentelemetry.api - -Module contents ---------------- - -.. automodule:: opentelemetry - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/opentelemetry.trace.rst b/docs/opentelemetry.trace.rst new file mode 100644 index 0000000000..cec44bd817 --- /dev/null +++ b/docs/opentelemetry.trace.rst @@ -0,0 +1,4 @@ +opentelemetry.trace package +=========================== + +.. automodule:: opentelemetry.trace From 8c0a19ba8e986fed773ac9c6a82b89187d60b0c2 Mon Sep 17 00:00:00 2001 From: Chris Kleinknecht Date: Fri, 21 Jun 2019 12:25:27 -0700 Subject: [PATCH 24/24] Remove missing static dir in conf --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 5e5dbb8576..414c33d3df 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -65,4 +65,4 @@ # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] +html_static_path = []