starlette instrumentation (open-telemetry#777)

adding an initial starlette instrumentation.

tox does exact match on fields delimited by a dash. Thus,
any instrumentation that includes "instrumentation" in the name
would collide with testing of the "opentelemetry-instrumentation"
package.

Renaming opentelemetry-instrumentation to opentelemetry-instrumentation-base to fix that.

Co-authored-by: Leighton Chen <lechen@microsoft.com>
Co-authored-by: alrex <aboten@lightstep.com>

Author: 3 people

docs-requirements.txt

@@ -26,3 +26,4 @@ boto~=2.0
 google-cloud-trace >=0.23.0
 google-cloud-monitoring>=0.36.0
 botocore~=1.0
+starlette~=0.13

docs/examples/opentelemetry-example-app/src/opentelemetry_example_app/version.py

@@ -12,4 +12,4 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-__version__ = "0.9.dev0"
+__version__ = "0.10.dev0"

docs/ext/starlette/starlette.rst

@@ -0,0 +1,9 @@
+.. include:: ../../../ext/opentelemetry-instrumentation-starlette/README.rst
+
+API
+---
+
+.. automodule:: opentelemetry.instrumentation.starlette
+    :members:
+    :undoc-members:
+    :show-inheritance:

ext/opentelemetry-ext-asgi/setup.cfg

@@ -40,6 +40,7 @@ package_dir=
 packages=find_namespace:
 install_requires =
     opentelemetry-api == 0.10.dev0
+    opentelemetry-instrumentation == 0.10.dev0
     asgiref ~= 3.0
 
 [options.extras_require]

ext/opentelemetry-ext-asgi/src/opentelemetry/ext/asgi/__init__.py

@@ -22,11 +22,13 @@
 import typing
 import urllib
 from functools import wraps
+from typing import Tuple
 
 from asgiref.compatibility import guarantee_single_callable
 
 from opentelemetry import context, propagators, trace
 from opentelemetry.ext.asgi.version import __version__  # noqa
+from opentelemetry.instrumentation.utils import http_status_to_canonical_code
 from opentelemetry.trace.status import Status, StatusCanonicalCode
 
 
@@ -44,37 +46,6 @@ def get_header_from_scope(scope: dict, header_name: str) -> typing.List[str]:
     ]
 
 
-def http_status_to_canonical_code(code: int, allow_redirect: bool = True):
-    # pylint:disable=too-many-branches,too-many-return-statements
-    if code < 100:
-        return StatusCanonicalCode.UNKNOWN
-    if code <= 299:
-        return StatusCanonicalCode.OK
-    if code <= 399:
-        if allow_redirect:
-            return StatusCanonicalCode.OK
-        return StatusCanonicalCode.DEADLINE_EXCEEDED
-    if code <= 499:
-        if code == 401:  # HTTPStatus.UNAUTHORIZED:
-            return StatusCanonicalCode.UNAUTHENTICATED
-        if code == 403:  # HTTPStatus.FORBIDDEN:
-            return StatusCanonicalCode.PERMISSION_DENIED
-        if code == 404:  # HTTPStatus.NOT_FOUND:
-            return StatusCanonicalCode.NOT_FOUND
-        if code == 429:  # HTTPStatus.TOO_MANY_REQUESTS:
-            return StatusCanonicalCode.RESOURCE_EXHAUSTED
-        return StatusCanonicalCode.INVALID_ARGUMENT
-    if code <= 599:
-        if code == 501:  # HTTPStatus.NOT_IMPLEMENTED:
-            return StatusCanonicalCode.UNIMPLEMENTED
-        if code == 503:  # HTTPStatus.SERVICE_UNAVAILABLE:
-            return StatusCanonicalCode.UNAVAILABLE
-        if code == 504:  # HTTPStatus.GATEWAY_TIMEOUT:
-            return StatusCanonicalCode.DEADLINE_EXCEEDED
-        return StatusCanonicalCode.INTERNAL
-    return StatusCanonicalCode.UNKNOWN
-
-
 def collect_request_attributes(scope):
     """Collects HTTP request attributes from the ASGI scope and returns a
     dictionary to be used as span creation attributes."""
@@ -134,11 +105,19 @@ def set_status_code(span, status_code):
         span.set_status(Status(http_status_to_canonical_code(status_code)))
 
 
-def get_default_span_name(scope):
-    """Default implementation for name_callback"""
+def get_default_span_details(scope: dict) -> Tuple[str, dict]:
+    """Default implementation for span_details_callback
+
+    Args:
+        scope: the asgi scope dictionary
+
+    Returns:
+        a tuple of the span, and any attributes to attach to the
+        span.
+    """
     method_or_path = scope.get("method") or scope.get("path")
 
-    return method_or_path
+    return method_or_path, {}
 
 
 class OpenTelemetryMiddleware:
@@ -149,15 +128,18 @@ class OpenTelemetryMiddleware:
 
     Args:
         app: The ASGI application callable to forward requests to.
-        name_callback: Callback which calculates a generic span name for an
-                       incoming HTTP request based on the ASGI scope.
-                       Optional: Defaults to get_default_span_name.
+        span_details_callback: Callback which should return a string
+            and a tuple, representing the desired span name and a
+            dictionary with any additional span attributes to set.
+            Optional: Defaults to get_default_span_details.
     """
 
-    def __init__(self, app, name_callback=None):
+    def __init__(self, app, span_details_callback=None):
         self.app = guarantee_single_callable(app)
         self.tracer = trace.get_tracer(__name__, __version__)
-        self.name_callback = name_callback or get_default_span_name
+        self.span_details_callback = (
+            span_details_callback or get_default_span_details
+        )
 
     async def __call__(self, scope, receive, send):
         """The ASGI application
@@ -173,13 +155,15 @@ async def __call__(self, scope, receive, send):
         token = context.attach(
             propagators.extract(get_header_from_scope, scope)
         )
-        span_name = self.name_callback(scope)
+        span_name, additional_attributes = self.span_details_callback(scope)
+        attributes = collect_request_attributes(scope)
+        attributes.update(additional_attributes)
 
         try:
             with self.tracer.start_as_current_span(
                 span_name + " asgi",
                 kind=trace.SpanKind.SERVER,
-                attributes=collect_request_attributes(scope),
+                attributes=attributes,
             ):
 
                 @wraps(receive)

ext/opentelemetry-ext-asgi/tests/test_asgi_middleware.py

@@ -176,9 +176,8 @@ def test_override_span_name(self):
         """Test that span_names can be overwritten by our callback function."""
         span_name = "Dymaxion"
 
-        # pylint:disable=unused-argument
-        def get_predefined_span_name(scope):
-            return span_name
+        def get_predefined_span_details(_):
+            return span_name, {}
 
         def update_expected_span_name(expected):
             for entry in expected:
@@ -188,7 +187,7 @@ def update_expected_span_name(expected):
             return expected
 
         app = otel_asgi.OpenTelemetryMiddleware(
-            simple_asgi, name_callback=get_predefined_span_name
+            simple_asgi, span_details_callback=get_predefined_span_details
         )
         self.seed_app(app)
         self.send_default_request()

ext/opentelemetry-ext-boto/tests/test_boto_instrumentation.py

@@ -19,13 +19,13 @@
 import boto.elasticache
 import boto.s3
 import boto.sts
-
 from moto import (  # pylint: disable=import-error
     mock_ec2_deprecated,
     mock_lambda_deprecated,
     mock_s3_deprecated,
     mock_sts_deprecated,
 )
+
 from opentelemetry.ext.boto import BotoInstrumentor
 from opentelemetry.test.test_base import TestBase
 

ext/opentelemetry-ext-botocore/tests/test_botocore_instrumentation.py

@@ -1,6 +1,5 @@
 import botocore.session
 from botocore.exceptions import ParamValidationError
-
 from moto import (  # pylint: disable=import-error
     mock_ec2,
     mock_kinesis,
@@ -9,6 +8,7 @@
     mock_s3,
     mock_sqs,
 )
+
 from opentelemetry.ext.botocore import BotocoreInstrumentor
 from opentelemetry.test.test_base import TestBase
 

ext/opentelemetry-ext-datadog/src/opentelemetry/ext/datadog/exporter.py

@@ -33,6 +33,7 @@
 DEFAULT_AGENT_URL = "http://localhost:8126"
 _INSTRUMENTATION_SPAN_TYPES = {
     "opentelemetry.ext.aiohttp-client": DatadogSpanTypes.HTTP,
+    "opentelemetry.ext.asgi": DatadogSpanTypes.WEB,
     "opentelemetry.ext.dbapi": DatadogSpanTypes.SQL,
     "opentelemetry.ext.django": DatadogSpanTypes.WEB,
     "opentelemetry.ext.flask": DatadogSpanTypes.WEB,

ext/opentelemetry-instrumentation-starlette/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## Unreleased
+
+- Initial release ([#777](https://github.com/open-telemetry/opentelemetry-python/pull/777))