[Core OTel] Add schema version support to OTel plugin (#40161)

This is to support cases where a user might be using the plugin span and
wants to set attributes defined in a later version of the OTel schema.
This allows passing in a specific version and setting the corresponding
schema URL on the tracer instrumentation scope.

Signed-off-by: Paul Van Eck <[email protected]>

Author: pvaneck

sdk/core/azure-core-tracing-opentelemetry/CHANGELOG.md

@@ -5,6 +5,7 @@
 ### Features Added
 
 - If a span exits with an exception, the exception name is now recorded in the `error.type` attribute. ([#34619](https://github.com/Azure/azure-sdk-for-python/pull/34619))
+- Added support for passing a schema version to fetch available attribute mappings and set the schema URL on the tracer's instrumentation scope. ([#40161](https://github.com/Azure/azure-sdk-for-python/pull/40161))
 
 ### Breaking Changes
 

sdk/core/azure-core-tracing-opentelemetry/azure/core/tracing/ext/opentelemetry_span/__init__.py

@@ -27,7 +27,7 @@
 
 from azure.core.tracing import SpanKind, HttpSpanMixin, Link as CoreLink  # type: ignore[attr-defined] # pylint: disable=no-name-in-module
 
-from ._schema import OpenTelemetrySchema
+from ._schema import OpenTelemetrySchema, OpenTelemetrySchemaVersion as _OpenTelemetrySchemaVersion
 from ._version import VERSION
 
 AttributeValue = Union[
@@ -113,6 +113,8 @@ class OpenTelemetrySpan(HttpSpanMixin, object):
     :paramtype links: list[~azure.core.tracing.Link]
     :keyword context: Context headers of parent span that should be used when creating a new span.
     :paramtype context: Dict[str, str]
+    :keyword schema_version: The OpenTelemetry schema version to use for the span.
+    :paramtype schema_version: str
     """
 
     def __init__(
@@ -125,9 +127,7 @@ def __init__(
         **kwargs: Any,
     ) -> None:
         self._current_ctxt_manager: Optional[_SuppressionContextManager] = None
-
-        # TODO: Once we have additional supported versions, we should add a way to specify the version.
-        self._schema_version = OpenTelemetrySchema.get_latest_version()
+        self._schema_version = kwargs.pop("schema_version", _OpenTelemetrySchemaVersion.V1_23_1)
         self._attribute_mappings = OpenTelemetrySchema.get_attribute_mappings(self._schema_version)
 
         if span:

sdk/core/azure-core-tracing-opentelemetry/azure/core/tracing/ext/opentelemetry_span/_schema.py

@@ -53,7 +53,7 @@ def get_latest_version(cls) -> OpenTelemetrySchemaVersion:
 
     @classmethod
     def get_attribute_mappings(cls, version: OpenTelemetrySchemaVersion) -> Dict[str, str]:
-        return cls._ATTRIBUTE_MAPPINGS[version]
+        return cls._ATTRIBUTE_MAPPINGS.get(version, {})
 
     @classmethod
     def get_schema_url(cls, version: OpenTelemetrySchemaVersion) -> str:

sdk/core/azure-core-tracing-opentelemetry/tests/test_schema.py

@@ -7,14 +7,14 @@
 from opentelemetry.trace import SpanKind as OpenTelemetrySpanKind
 
 from azure.core.tracing.ext.opentelemetry_span import OpenTelemetrySpan
-from azure.core.tracing.ext.opentelemetry_span._schema import OpenTelemetrySchema
+from azure.core.tracing.ext.opentelemetry_span._schema import OpenTelemetrySchema, OpenTelemetrySchemaVersion
 
 
 class TestOpenTelemetrySchema:
     def test_latest_schema_attributes_renamed(self, tracing_helper):
         with tracing_helper.tracer.start_as_current_span("Root", kind=OpenTelemetrySpanKind.CLIENT) as parent:
             wrapped_class = OpenTelemetrySpan(span=parent)
-            schema_version = OpenTelemetrySchema.get_latest_version()
+            schema_version = wrapped_class._schema_version
             attribute_mappings = OpenTelemetrySchema.get_attribute_mappings(schema_version)
             attribute_values = {}
             for key, value in attribute_mappings.items():
@@ -42,6 +42,18 @@ def test_latest_schema_attributes_not_renamed(self, tracing_helper):
 
     def test_schema_url_in_instrumentation_scope(self):
         with OpenTelemetrySpan(name="span") as span:
-            schema_version = OpenTelemetrySchema.get_latest_version()
-            schema_url = OpenTelemetrySchema.get_schema_url(schema_version)
+            schema_url = OpenTelemetrySchema.get_schema_url(span._schema_version)
             assert span.span_instance.instrumentation_scope.schema_url == schema_url
+
+    def test_schema_version_argument(self, tracing_helper):
+        with OpenTelemetrySpan(name="span", schema_version="1.0.0") as span:
+            assert span._schema_version == "1.0.0"
+            assert span._attribute_mappings == {}
+            assert span.span_instance.instrumentation_scope.schema_url == "https://opentelemetry.io/schemas/1.0.0"
+
+    def test_schema_version_formats(self, tracing_helper):
+        assert OpenTelemetrySchema.get_attribute_mappings(OpenTelemetrySchemaVersion.V1_19_0)
+        assert OpenTelemetrySchema.get_attribute_mappings(OpenTelemetrySchemaVersion.V1_23_1)
+        assert OpenTelemetrySchema.get_attribute_mappings("1.19.0")
+        assert OpenTelemetrySchema.get_attribute_mappings("1.23.1")
+        assert not OpenTelemetrySchema.get_attribute_mappings("1.0.0")

sdk/core/azure-core-tracing-opentelemetry/tests/test_tracing_implementations.py

@@ -452,9 +452,34 @@ def test_add_attribute(self, tracing_helper):
             assert wrapped_class.span_instance.attributes["test"] == "test2"
             assert parent.attributes["test"] == "test2"
 
-    def test_set_http_attributes(self, tracing_helper):
+    def test_set_http_attributes_v1_19_0(self, tracing_helper):
         with tracing_helper.tracer.start_as_current_span("Root", kind=OpenTelemetrySpanKind.CLIENT) as parent:
-            wrapped_class = OpenTelemetrySpan(span=parent)
+            wrapped_class = OpenTelemetrySpan(span=parent, schema_version="1.19.0")
+            request = mock.Mock()
+            setattr(request, "method", "GET")
+            setattr(request, "url", "https://foo.bar/path")
+            response = mock.Mock()
+            setattr(request, "headers", {})
+            setattr(response, "status_code", 200)
+            wrapped_class.set_http_attributes(request)
+            assert wrapped_class.span_instance.kind == OpenTelemetrySpanKind.CLIENT
+            assert wrapped_class.span_instance.attributes.get("http.method") == request.method
+            assert wrapped_class.span_instance.attributes.get("component") == "http"
+            assert wrapped_class.span_instance.attributes.get("http.url") == request.url
+            assert wrapped_class.span_instance.attributes.get("http.status_code") == 504
+            assert wrapped_class.span_instance.attributes.get("user_agent.original") is None
+
+            request.headers["User-Agent"] = "some user agent"
+            request.url = "http://foo.bar:8080/path"
+            wrapped_class.set_http_attributes(request, response)
+            assert wrapped_class.span_instance.attributes.get("http.status_code") == response.status_code
+            assert wrapped_class.span_instance.attributes.get("user_agent.original") == request.headers.get(
+                "User-Agent"
+            )
+
+    def test_set_http_attributes_v1_23_1(self, tracing_helper):
+        with tracing_helper.tracer.start_as_current_span("Root", kind=OpenTelemetrySpanKind.CLIENT) as parent:
+            wrapped_class = OpenTelemetrySpan(span=parent, schema_version="1.23.1")
             request = mock.Mock()
             setattr(request, "method", "GET")
             setattr(request, "url", "https://foo.bar/path")