Add pymssql instrumentation

CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- `opentelemetry-instrumentation-pymssql` Add pymssql instrumentation
+  ([#394](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/394))
+
 ### Fixed
 
 - `opentelemetry-instrumentation-boto3sqs` Make propagation compatible with other SQS instrumentations, add 'messaging.url' span attribute, and fix missing package dependencies.

docs/instrumentation/pymssql/pymssql.rst

@@ -0,0 +1,7 @@
+OpenTelemetry pymssql Instrumentation
+=====================================
+
+.. automodule:: opentelemetry.instrumentation.pymssql
+    :members:
+    :undoc-members:
+    :show-inheritance:

instrumentation/opentelemetry-instrumentation-dbapi/src/opentelemetry/instrumentation/dbapi/__init__.py

@@ -336,9 +336,15 @@ def cursor(self, *args, **kwargs):
                 self._connection.cursor(*args, **kwargs), db_api_integration
             )
 
-        # For some reason this is necessary as trying to access the close
-        # method of self._connection via __getattr__ leads to unexplained
-        # errors.
+        # For some reason this is necessary as trying to access some methods
+        # such as commit and close method of self._connection via __getattr__
+        # leads to unexplained errors.
+        def commit(self):
+            self._connection.commit()
+
+        def rollback(self):
+            self._connection.rollback()
+
         def close(self):
             self._connection.close()
 

instrumentation/opentelemetry-instrumentation-pymssql/README.rst

@@ -0,0 +1,21 @@
+OpenTelemetry pymssql Instrumentation
+=====================================
+
+|pypi|
+
+.. |pypi| image:: https://badge.fury.io/py/opentelemetry-instrumentation-pymssql.svg
+   :target: https://pypi.org/project/opentelemetry-instrumentation-pymssql/
+
+Installation
+------------
+
+::
+
+    pip install opentelemetry-instrumentation-pymssql
+
+
+References
+----------
+* `OpenTelemetry pymssql Instrumentation <https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/pymssql/pymssql.html>`_
+* `OpenTelemetry Project <https://opentelemetry.io/>`_
+* `OpenTelemetry Python Examples <https://github.com/open-telemetry/opentelemetry-python/tree/main/docs/examples>`_

instrumentation/opentelemetry-instrumentation-pymssql/setup.cfg

@@ -0,0 +1,55 @@
+# Copyright The 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.
+#
+[metadata]
+name = opentelemetry-instrumentation-pymssql
+description = OpenTelemetry pymssql instrumentation
+long_description = file: README.rst
+long_description_content_type = text/x-rst
+author = OpenTelemetry Authors
+author_email = cncf-opentelemetry-contributors@lists.cncf.io
+url = https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-pymssql
+platforms = any
+license = Apache-2.0
+classifiers =
+    Development Status :: 4 - Beta
+    Intended Audience :: Developers
+    License :: OSI Approved :: Apache Software License
+    Programming Language :: Python
+    Programming Language :: Python :: 3
+    Programming Language :: Python :: 3.7
+    Programming Language :: Python :: 3.8
+    Programming Language :: Python :: 3.9
+    Programming Language :: Python :: 3.10
+
+[options]
+python_requires = >=3.7
+package_dir=
+    =src
+packages=find_namespace:
+install_requires =
+    opentelemetry-api ~= 1.12
+    opentelemetry-instrumentation-dbapi == 0.33b0
+    opentelemetry-instrumentation == 0.33b0
+
+[options.extras_require]
+test =
+    opentelemetry-test-utils == 0.33b0
+
+[options.packages.find]
+where = src
+
+[options.entry_points]
+opentelemetry_instrumentor =
+    pymssql = opentelemetry.instrumentation.pymssql:PyMSSQLInstrumentor

instrumentation/opentelemetry-instrumentation-pymssql/setup.py

@@ -0,0 +1,99 @@
+# Copyright The 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.
+
+
+# DO NOT EDIT. THIS FILE WAS AUTOGENERATED FROM templates/instrumentation_setup.py.txt.
+# RUN `python scripts/generate_setup.py` TO REGENERATE.
+
+
+import distutils.cmd
+import json
+import os
+from configparser import ConfigParser
+
+import setuptools
+
+config = ConfigParser()
+config.read("setup.cfg")
+
+# We provide extras_require parameter to setuptools.setup later which
+# overwrites the extras_require section from setup.cfg. To support extras_require
+# section in setup.cfg, we load it here and merge it with the extras_require param.
+extras_require = {}
+if "options.extras_require" in config:
+    for key, value in config["options.extras_require"].items():
+        extras_require[key] = [v for v in value.split("\n") if v.strip()]
+
+BASE_DIR = os.path.dirname(__file__)
+PACKAGE_INFO = {}
+
+VERSION_FILENAME = os.path.join(
+    BASE_DIR,
+    "src",
+    "opentelemetry",
+    "instrumentation",
+    "pymssql",
+    "version.py",
+)
+with open(VERSION_FILENAME, encoding="utf-8") as f:
+    exec(f.read(), PACKAGE_INFO)
+
+PACKAGE_FILENAME = os.path.join(
+    BASE_DIR,
+    "src",
+    "opentelemetry",
+    "instrumentation",
+    "pymssql",
+    "package.py",
+)
+with open(PACKAGE_FILENAME, encoding="utf-8") as f:
+    exec(f.read(), PACKAGE_INFO)
+
+# Mark any instruments/runtime dependencies as test dependencies as well.
+extras_require["instruments"] = PACKAGE_INFO["_instruments"]
+test_deps = extras_require.get("test", [])
+for dep in extras_require["instruments"]:
+    test_deps.append(dep)
+
+extras_require["test"] = test_deps
+
+
+class JSONMetadataCommand(distutils.cmd.Command):
+
+    description = (
+        "print out package metadata as JSON. This is used by OpenTelemetry dev scripts to ",
+        "auto-generate code in other places",
+    )
+    user_options = []
+
+    def initialize_options(self):
+        pass
+
+    def finalize_options(self):
+        pass
+
+    def run(self):
+        metadata = {
+            "name": config["metadata"]["name"],
+            "version": PACKAGE_INFO["__version__"],
+            "instruments": PACKAGE_INFO["_instruments"],
+        }
+        print(json.dumps(metadata))
+
+
+setuptools.setup(
+    cmdclass={"meta": JSONMetadataCommand},
+    version=PACKAGE_INFO["__version__"],
+    extras_require=extras_require,
+)

instrumentation/opentelemetry-instrumentation-pymssql/src/opentelemetry/instrumentation/pymssql/__init__.py

@@ -0,0 +1,180 @@
+# Copyright The 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 integration with pymssql supports the `pymssql`_ library and can be enabled
+by using ``PyMSSQLInstrumentor``.
+
+.. _pymssql: https://pypi.org/project/pymssql/
+
+Usage
+-----
+
+.. code:: python
+
+    import pymssql
+    from opentelemetry.instrumentation.pymssql import PyMSSQLInstrumentor
+
+    PyMSSQLInstrumentor().instrument()
+
+    cnx = pymssql.connect(database="MSSQL_Database")
+    cursor = cnx.cursor()
+    cursor.execute("INSERT INTO test (testField) VALUES (123)"
+    cnx.commit()
+    cursor.close()
+    cnx.close()
+
+API
+---
+"""
+from typing import Any, Callable, Collection, Dict, NamedTuple, Tuple
+
+import pymssql
+
+from opentelemetry.instrumentation import dbapi
+from opentelemetry.instrumentation.instrumentor import BaseInstrumentor
+from opentelemetry.instrumentation.pymssql.package import _instruments
+from opentelemetry.instrumentation.pymssql.version import __version__
+
+_DATABASE_SYSTEM = "mssql"
+
+
+class PyMSSQLConnectMethodArgsTuple(NamedTuple):
+    server: str = None
+    user: str = None
+    password: str = None
+    database: str = None
+    timeout: int = None
+    login_timeout: int = None
+    charset: str = None
+    as_dict: bool = None
+    host: str = None
+    appname: str = None
+    port: str = None
+    conn_properties: str = None
+    autocommit: bool = None
+    tds_version: str = None
+
+
+class PyMSSQLDatabaseApiIntegration(dbapi.DatabaseApiIntegration):
+    def wrapped_connection(
+        self,
+        connect_method: Callable[..., Any],
+        args: Tuple[Any, Any],
+        kwargs: Dict[Any, Any],
+    ):
+        """Add object proxy to connection object."""
+        connection = connect_method(*args, **kwargs)
+        connect_method_args = PyMSSQLConnectMethodArgsTuple(*args)
+
+        self.name = self.database_system
+        self.database = kwargs.get("database") or connect_method_args.database
+
+        user = kwargs.get("user") or connect_method_args.user
+        if user is not None:
+            self.span_attributes["db.user"] = user
+
+        port = kwargs.get("port") or connect_method_args.port
+        host = kwargs.get("server") or connect_method_args.server
+        if host is None:
+            host = kwargs.get("host") or connect_method_args.host
+            if host is not None:
+                # The host string can include the port, separated by either a coma or
+                # a column
+                for sep in (":", ","):
+                    if sep in host:
+                        tokens = host.rsplit(sep)
+                        host = tokens[0]
+                        if len(tokens) > 1:
+                            port = tokens[1]
+        if host is not None:
+            self.span_attributes["net.peer.name"] = host
+        if port is not None:
+            self.span_attributes["net.peer.port"] = port
+
+        charset = kwargs.get("charset") or connect_method_args.charset
+        if charset is not None:
+            self.span_attributes["db.charset"] = charset
+
+        tds_version = (
+            kwargs.get("tds_version") or connect_method_args.tds_version
+        )
+        if tds_version is not None:
+            self.span_attributes["db.protocol.tds.version"] = tds_version
+
+        return dbapi.get_traced_connection_proxy(connection, self)
+
+
+
+class PyMSSQLInstrumentor(BaseInstrumentor):
+
+    def instrumentation_dependencies(self) -> Collection[str]:
+        return _instruments
+
+    def _instrument(self, **kwargs):
+        """Integrate with the pymssql library.
+        https://github.com/pymssql/pymssql/
+        """
+        tracer_provider = kwargs.get("tracer_provider")
+
+        dbapi.wrap_connect(
+            __name__,
+            pymssql,
+            "connect",
+            _DATABASE_SYSTEM,
+            version=__version__,
+            tracer_provider=tracer_provider,
+            # pymssql does not keep the connection attributes in its connection object;
+            # instead, we get the attributes from the connect method (which is done
+            # via PyMSSQLDatabaseApiIntegration.wrapped_connection)
+            db_api_integration_factory=PyMSSQLDatabaseApiIntegration,
+        )
+
+    def _uninstrument(self, **kwargs):
+        """ "Disable pymssql instrumentation"""
+        dbapi.unwrap_connect(pymssql, "connect")
+
+    @staticmethod
+    def instrument_connection(connection, tracer_provider=None):
+        """Enable instrumentation in a pymssql connection.
+
+        Args:
+            connection: The connection to instrument.
+            tracer_provider: The optional tracer provider to use. If omitted
+                the current globally configured one is used.
+
+        Returns:
+            An instrumented connection.
+        """
+
+        return dbapi.instrument_connection(
+            __name__,
+            connection,
+            _DATABASE_SYSTEM,
+            version=__version__,
+            tracer_provider=tracer_provider,
+        )
+
+    @staticmethod
+    def uninstrument_connection(connection):
+        """Disable instrumentation in a pymssql connection.
+
+        Args:
+            connection: The connection to uninstrument.
+
+        Returns:
+            An uninstrumented connection.
+        """
+        return dbapi.uninstrument_connection(connection)
+