Add instrumentation for click based CLI apps

Co-authored-by: Anuraag (Rag) Agrawal <[email protected]>

Author: xrmx

instrumentation/README.md

@@ -15,6 +15,7 @@
 | [opentelemetry-instrumentation-botocore](./opentelemetry-instrumentation-botocore) | botocore ~= 1.0 | No | experimental
 | [opentelemetry-instrumentation-cassandra](./opentelemetry-instrumentation-cassandra) | cassandra-driver ~= 3.25,scylla-driver ~= 3.25 | No | experimental
 | [opentelemetry-instrumentation-celery](./opentelemetry-instrumentation-celery) | celery >= 4.0, < 6.0 | No | experimental
+| [opentelemetry-instrumentation-click](./opentelemetry-instrumentation-click) | click < 9.0.0 | No | experimental
 | [opentelemetry-instrumentation-confluent-kafka](./opentelemetry-instrumentation-confluent-kafka) | confluent-kafka >= 1.8.2, <= 2.4.0 | No | experimental
 | [opentelemetry-instrumentation-dbapi](./opentelemetry-instrumentation-dbapi) | dbapi | No | experimental
 | [opentelemetry-instrumentation-django](./opentelemetry-instrumentation-django) | django >= 1.10 | Yes | experimental

instrumentation/opentelemetry-instrumentation-click/README.rst

@@ -0,0 +1,24 @@
+OpenTelemetry click Instrumentation
+===========================
+
+|pypi|
+
+.. |pypi| image:: https://badge.fury.io/py/opentelemetry-instrumentation-click.svg
+   :target: https://pypi.org/project/opentelemetry-instrumentation-click/
+
+This library allows tracing requests made by the click library.
+
+Installation
+------------
+
+
+::
+
+    pip install opentelemetry-instrumentation-click
+
+
+References
+----------
+
+* `OpenTelemetry click/ Tracing <https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/click/click.html>`_
+* `OpenTelemetry Project <https://opentelemetry.io/>`_

instrumentation/opentelemetry-instrumentation-click/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "opentelemetry-instrumentation-click"
+dynamic = ["version"]
+description = "Click instrumentation for OpenTelemetry"
+readme = "README.rst"
+license = "Apache-2.0"
+requires-python = ">=3.8"
+authors = [
+  { name = "OpenTelemetry Authors", email = "[email protected]" },
+]
+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.8",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+  "opentelemetry-api ~= 1.12",
+  "opentelemetry-semantic-conventions ~= 0.50b0",
+]
+
+[project.optional-dependencies]
+instruments = [
+  "click < 9.0.0",
+]
+
+[project.entry-points.opentelemetry_instrumentor]
+click = "opentelemetry.instrumentation.click:ClickInstrumentor>"
+
+[project.urls]
+Homepage = "https://github.com/open-telemetry/opentelemetry-python-contrib/instrumentation/opentelemetry-instrumentation-click"
+
+[tool.hatch.version]
+path = "src/opentelemetry/instrumentation/click/version.py"
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "/src",
+  "/tests",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/opentelemetry"]

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

@@ -0,0 +1,105 @@
+# 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.
+
+"""
+Instrument `click`_ CLI applications.
+
+.. _click: https://pypi.org/project/click/
+
+Usage
+-----
+
+.. code-block:: python
+
+    import click
+    from opentelemetry.instrumentation.click import ClickInstrumentor
+
+    ClickInstrumentor().instrument()
+
+    @click.command()
+    def hello():
+       click.echo(f'Hello world!')
+
+    if __name__ == "__main__":
+        hello()
+
+API
+---
+"""
+
+from functools import partial
+from logging import getLogger
+from typing import Collection
+
+import click
+from wrapt import wrap_function_wrapper
+
+from opentelemetry import trace
+from opentelemetry.instrumentation.click.package import _instruments
+from opentelemetry.instrumentation.click.version import __version__
+from opentelemetry.instrumentation.instrumentor import BaseInstrumentor
+from opentelemetry.instrumentation.utils import (
+    unwrap,
+)
+from opentelemetry.semconv.attributes.error_attributes import ERROR_TYPE
+from opentelemetry.trace.status import StatusCode
+
+_logger = getLogger(__name__)
+
+
+def _command_invoke_wrapper(wrapped, instance, args, kwargs, tracer):
+    # Subclasses of Command include groups and CLI runners, but
+    # we only want to instrument the actual commands which are
+    # instances of Command itself.
+    if instance.__class__ != click.Command:
+        return wrapped(*args, **kwargs)
+
+    ctx = args[0]
+    span_name = ctx.info_name
+    span_attributes = {}
+
+    with tracer.start_as_current_span(
+        name=span_name,
+        kind=trace.SpanKind.INTERNAL,
+        attributes=span_attributes,
+    ) as span:
+        try:
+            return wrapped(*args, **kwargs)
+        except Exception as exc:
+            span.set_status(StatusCode.ERROR, str(exc))
+            span.set_attribute(ERROR_TYPE, exc.__class__.__qualname__)
+            raise
+
+
+class ClickInstrumentor(BaseInstrumentor):
+    """An instrumentor for click"""
+
+    def instrumentation_dependencies(self) -> Collection[str]:
+        return _instruments
+
+    def _instrument(self, **kwargs):
+        tracer = trace.get_tracer(
+            __name__,
+            __version__,
+            kwargs.get("tracer_provider"),
+        )
+
+        wrap_function_wrapper(
+            click.core.Command,
+            "invoke",
+            partial(_command_invoke_wrapper, tracer=tracer),
+        )
+
+    def _uninstrument(self, **kwargs):
+        unwrap(click.core.Command, "invoke")

instrumentation/opentelemetry-instrumentation-click/src/opentelemetry/instrumentation/click/package.py

@@ -0,0 +1,16 @@
+# 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.
+
+
+_instruments = ("click < 9.0.0",)

instrumentation/opentelemetry-instrumentation-click/src/opentelemetry/instrumentation/click/version.py

@@ -0,0 +1,15 @@
+# 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.
+
+__version__ = "0.50b0.dev"

instrumentation/opentelemetry-instrumentation-click/test-requirements.txt

@@ -0,0 +1,15 @@
+asgiref==3.8.1
+click==8.1.7
+Deprecated==1.2.14
+iniconfig==2.0.0
+packaging==24.0
+pluggy==1.5.0
+py-cpuinfo==9.0.0
+pytest==7.4.4
+pytest-asyncio==0.23.5
+tomli==2.0.1
+typing_extensions==4.12.2
+wrapt==1.16.0
+zipp==3.19.2
+-e opentelemetry-instrumentation
+-e instrumentation/opentelemetry-instrumentation-click

instrumentation/opentelemetry-instrumentation-click/tests/test_click.py

@@ -0,0 +1,70 @@
+# 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.
+
+import click
+from click.testing import CliRunner
+
+from opentelemetry.instrumentation.click import ClickInstrumentor
+from opentelemetry.test.test_base import TestBase
+from opentelemetry.trace.status import StatusCode
+
+
+class TestAutomatic(TestBase):
+    def setUp(self):
+        super().setUp()
+
+        ClickInstrumentor().instrument()
+
+    def tearDown(self):
+        super().tearDown()
+        ClickInstrumentor().uninstrument()
+
+    def test_cli_command_wrapping(self):
+        @click.command()
+        def command():
+            pass
+
+        runner = CliRunner()
+        result = runner.invoke(command, ["command"])
+        self.assertEqual(result.exit_code, 0)
+
+        (span,) = self.memory_exporter.get_finished_spans()
+        self.assertEqual(span.status.status_code, StatusCode.UNSET)
+        self.assertEqual(span.name, "command")
+
+    def test_cli_command_wrapping_with_name(self):
+        @click.command("mycommand")
+        def renamedcommand():
+            pass
+
+        runner = CliRunner()
+        result = runner.invoke(renamedcommand, ["mycommand"])
+        self.assertEqual(result.exit_code, 0)
+
+        (span,) = self.memory_exporter.get_finished_spans()
+        self.assertEqual(span.status.status_code, StatusCode.UNSET)
+        self.assertEqual(span.name, "mycommand")
+
+    def test_cli_command_raises_error(self):
+        @click.command()
+        def command_raises():
+            raise ValueError()
+
+        runner = CliRunner()
+        result = runner.invoke(command_raises, ["command-raises"])
+        self.assertEqual(result.exit_code, 2)
+
+        (span,) = self.memory_exporter.get_finished_spans()
+        self.assertEqual(span.status.status_code, StatusCode.ERROR)
+        self.assertEqual(span.name, "command_raises")

opentelemetry-contrib-instrumentations/pyproject.toml

@@ -43,6 +43,7 @@ dependencies = [
     "opentelemetry-instrumentation-botocore==0.50b0.dev",
     "opentelemetry-instrumentation-cassandra==0.50b0.dev",
     "opentelemetry-instrumentation-celery==0.50b0.dev",
+    "opentelemetry-instrumentation-click==0.50b0.dev",
     "opentelemetry-instrumentation-confluent-kafka==0.50b0.dev",
     "opentelemetry-instrumentation-dbapi==0.50b0.dev",
     "opentelemetry-instrumentation-django==0.50b0.dev",

opentelemetry-instrumentation/src/opentelemetry/instrumentation/bootstrap_gen.py

@@ -68,6 +68,10 @@
         "library": "celery >= 4.0, < 6.0",
         "instrumentation": "opentelemetry-instrumentation-celery==0.50b0.dev",
     },
+    {
+        "library": "click < 9.0.0",
+        "instrumentation": "opentelemetry-instrumentation-click==0.50b0.dev",
+    },
     {
         "library": "confluent-kafka >= 1.8.2, <= 2.4.0",
         "instrumentation": "opentelemetry-instrumentation-confluent-kafka==0.50b0.dev",