docs: Add more documentation for the instrumentor base class (open-telemetry#638)

Fixes open-telemetry#637

Co-authored-by: Yusuke Tsutsumi <tsutsumi.yusuke@gmail.com>
Co-authored-by: Chris Kleinknecht <libc@google.com>

Author: 3 people

opentelemetry-api/src/opentelemetry/configuration/__init__.py

@@ -74,9 +74,18 @@
 
 To use the meter provider above, then the
 ``OPENTELEMETRY_PYTHON_METER_PROVIDER`` should be set to
-"default_meter_provider" (this is not actually necessary since the
+``"default_meter_provider"`` (this is not actually necessary since the
 OpenTelemetry API provided providers are the default ones used if no
 configuration is found in the environment variables).
+
+This object can be used by any OpenTelemetry component, native or external.
+For that reason, the ``Configuration`` object is designed to be immutable.
+If a component would change the value of one of the ``Configuration`` object
+attributes then another component that relied on that value may break, leading
+to bugs that are very hard to debug. To avoid this situation, the preferred
+approach for components that need a different value than the one provided by
+the ``Configuration`` object is to implement a mechanism that allows the user
+to override this value instead of changing it.
 """
 
 from os import environ

opentelemetry-auto-instrumentation/src/opentelemetry/auto_instrumentation/instrumentor.py

@@ -24,7 +24,17 @@
 
 
 class BaseInstrumentor(ABC):
-    """An ABC for instrumentors"""
+    """An ABC for instrumentors
+
+    Child classes of this ABC should instrument specific third
+    party libraries or frameworks either by using the
+    ``opentelemetry-auto-instrumentation`` command or by calling their methods
+    directly.
+
+    Since every third party library or framework is different and has different
+    instrumentation needs, more methods can be added to the child classes as
+    needed to provide practical instrumentation to the end user.
+    """
 
     _instance = None
     _is_instrumented = False
@@ -38,14 +48,30 @@ def __new__(cls):
 
     @abstractmethod
     def _instrument(self, **kwargs):
-        """Instrument"""
+        """Instrument the library"""
 
     @abstractmethod
     def _uninstrument(self, **kwargs):
-        """Uninstrument"""
+        """Uninstrument the library"""
 
     def instrument(self, **kwargs):
-        """Instrument"""
+        """Instrument the library
+
+        This method will be called without any optional arguments by the
+        ``opentelemetry-auto-instrumentation`` command. The configuration of
+        the instrumentation when done in this way should be done by previously
+        setting the configuration (using environment variables or any other
+        mechanism) that will be used later by the code in the ``instrument``
+        implementation via the global ``Configuration`` object.
+
+        The ``instrument`` methods ``kwargs`` should default to values from the
+        ``Configuration`` object.
+
+        This means that calling this method directly without passing any
+        optional values should do the very same thing that the
+        ``opentelemetry-auto-instrumentation`` command does. This approach is
+        followed because the ``Configuration`` object is immutable.
+        """
 
         if not self._is_instrumented:
             result = self._instrument(**kwargs)
@@ -57,7 +83,11 @@ def instrument(self, **kwargs):
         return None
 
     def uninstrument(self, **kwargs):
-        """Uninstrument"""
+        """Uninstrument the library
+
+        See ``BaseInstrumentor.instrument`` for more information regarding the
+        usage of ``kwargs``.
+        """
 
         if self._is_instrumented:
             result = self._uninstrument(**kwargs)