Address lint issues.

Author: michaelsafyan

opentelemetry-configurator-gcp/src/opentelemetry/configurator/gcp/__init__.py

@@ -1,3 +1,31 @@
+"""Open Telemetry configurator for Google Cloud
+
+This package provides the 'OpenTelemetryGcpConfigurator' which simplifies configuration of the
+Open Telemetry library to route logs, traces, and metrics to Google Cloud Observability products
+such as Cloud Logging, Cloud Trace, and Cloud Monitoring.
+
+The OpenTelemetryGcpConfigurator can be invoked directly as in:
+
+    from opentelemetry.configurator.gcp import OpenTelemetryGcpConfigurator
+
+    OpenTelemetryGcpConfigurator().configure()
+
+It can also be invoked automatically from the "opentelemetry-instrument" command,
+which is part of the Open Telemetry zero-code instrumentation for Python. To
+invoke it automatically, simply supply "--configurator=gcp" as a commandline
+flag to the "opentelemetry-instrument" command. As an example:
+
+    opentelemetry-instrument \
+        --configurator=gcp \
+        python \
+        the/path/to/your/script.py
+
+This automatic wiring is implemented using the registration mechanism in "pyproject.toml";
+in particular, the "[project.entry-points.opentelemetry_configurator]" entry in that file
+makes this component known to the auto-instrumentation system. And it being a class
+that defines a "configure(self, **kwargs)" method makes it compatible with that API.
+."""
+
 from .configurator import OpenTelemetryGcpConfigurator
 from .version import __version__
 

opentelemetry-configurator-gcp/src/opentelemetry/configurator/gcp/configurator.py

@@ -1,3 +1,4 @@
+"""Defines the 'OpenTelemetryGcpConfigurator' class for simplifying Open Telemetry setup for GCP."""
 from typing import Optional, Callable
 
 from .flags import (
@@ -18,14 +19,52 @@ def _bool_with_flag_default(value: Optional[bool], flag_lookup: Callable[None, b
     return flag_lookup()
 
 
-class OpenTelemetryGcpConfigurator:
+class OpenTelemetryGcpConfigurator:  # pylint: disable=too-few-public-methods
+    """A class that can be used as a configurator in Open Telemetry zero-code instrumentation."""
 
     def __init__(
         self,
         metrics_exporter_enabled:Optional[bool]=None,
         logs_exporter_enabled:Optional[bool]=None,
         traces_exporter_enabled:Optional[bool]=None,
         resource_detector_enabled:Optional[bool]=None):
+        """Initialize the configurator with optional parameters to direct the behavior.
+        
+        No arguments are supplied when invoked from the zero-configuration system.
+
+        Args:
+          metrics_exporter_enabled: whether to enable metrics export. If unset,
+            falls back to an environment variable, allowing this argument to
+            be supplied even in zero-configuration scenarios. If that, too,
+            is unset, then the metrics export will be enabled.
+
+          logs_exporter_enabled: whether to enable logs export. If unset,
+            falls back to an environment variable, allowing this argument to
+            be supplied even in zero-configuration scenarios. If that, too,
+            is unset, then the logs export will be enabled.
+
+          traces_exporter_enabled: whether to enable trace export. If unset,
+            falls back to an environment variable, allowing this argument to
+            be supplied even in zero-configuration scenarios. If that, too,
+            is unset, then the trace export will be enabled.
+
+          resource_detector_enabled: whether to enable the GCP resource
+            detector (which is useful only when the code is running in
+            a GCP environment). If unset, falls back to an environment variable,
+            allowing this argument to be supplied even in zero-configuration
+            scenarios. If that, too, is unset, then the code will attempt
+            to determine if the code is likely deployed in GCP or not
+            based on the environment to enable the detector or not.
+        
+        Environment Variables:
+
+           The following environment variables affect the defaults:
+
+             - OTEL_GCP_METRICS_EXPORTER_ENABLED
+             - OTEL_GCP_LOGS_EXPORTER_ENABLED
+             - OTEL_GCP_TRACES_EXPORTER_ENABLED
+             - OTEL_GCP_RESOURCE_DETECTOR_ENABLED
+        """
         self._metrics_exporter_enabled = _bool_with_flag_default(
             metrics_exporter_enabled, is_metrics_exporter_enabled)
         self._logs_exporter_enabled = _bool_with_flag_default(
@@ -35,12 +74,23 @@ def __init__(
         self._resource_detector_enabled = _bool_with_flag_default(
             resource_detector_enabled, is_resource_detector_enabled)
 
-    def configure(self, **kwargs):
+    def configure(self, **unused_kwargs):
+        """Configure the Open Telemetry library to talk to GCP backends.
+        
+        This function configures the Open Telemetry library to talk to GCP
+        backends, subject to the class initialization parameters.
+
+        Although this class does not inherit any explicit interface, this
+        function should be treated like an inherited method in that its
+        signature is dictated by the Open Telemetry auto-instrumentation.
+
+        Uses **unused_kwargs to allow future iterations of the Open Telemetry
+        library to introduce additional keyword arguments without breaking.
+        """
         resource = get_resource(include_gcp_detector=self._resource_detector_enabled)
         if self._metrics_exporter_enabled:
             configure_metrics_exporter(resource=resource)
         if self._logs_exporter_enabled:
             configure_logs_exporter(resource=resource)
         if self._traces_exporter_enabled:
             configure_traces_exporter(resource=resource)
-

opentelemetry-configurator-gcp/src/opentelemetry/configurator/gcp/flags.py

@@ -1,9 +1,25 @@
+"""Provides functions for querying the configuration of this library.
+
+Other modules in this package use the 'flags' library to obtain default
+behaviors where the behavior has not been explicitly specified.
+"""
+from typing import Optional
+
 import os
 
 from . import gcloud_env
 
 
-def _str_to_optional_bool(s):
+def _str_to_optional_bool(s: str) -> Optional[bool]:
+    """Converts a string to an optional boolean.
+    
+    Args:
+        s: the string to convert to a boolean
+
+    Returns:
+        A boolean if the value is clearly false or clearly true.
+        None if the string does not match a known true/false pattern.
+    """
     lower_s = s.lower()
     if lower_s in ['1', 'true', 't', 'y', 'yes', 'on']:
         return True
@@ -12,7 +28,17 @@ def _str_to_optional_bool(s):
     return None
 
 
-def _get_bool_flag_from_env(env_var_name, default_value=None):
+def _get_bool_flag_from_env(env_var_name: str, default_value:Optional[bool]=None) -> Optional[bool]:
+    """Retrieves a boolean value from an environment variable.
+    
+    Args:
+      env_var_name: The name of the environment variable to retrieve.
+      default_value: The value to return if unset or has a non-bool value.
+    
+    Returns:
+      The boolean value of the environment variable if set and valid.
+      Otherwise, falls back to the supplied default value.
+    """
     s = os.getenv(env_var_name)
     if s is None:
         return default_value
@@ -23,27 +49,31 @@ def _get_bool_flag_from_env(env_var_name, default_value=None):
 
 
 def is_metrics_exporter_enabled():
+    """Returns whether to enable metrics exporting by default."""
     return _get_bool_flag_from_env(
         'OTEL_GCP_METRICS_EXPORTER_ENABLED',
         default_value=True
     )
 
 
 def is_logs_exporter_enabled():
+    """Returns whether to enable logs exporting by default."""
     return _get_bool_flag_from_env(
         'OTEL_GCP_LOGS_EXPORTER_ENABLED',
         default_value=True
     )
 
 
 def is_traces_exporter_enabled():
+    """Returns whether to enable trace exporting by default."""
     return _get_bool_flag_from_env(
         'OTEL_GCP_TRACES_EXPORTER_ENABLED',
         default_value=True
     )
 
 
 def is_resource_detector_enabled():
+    """Returns whether to enable the GCP resource detector by default."""
     result = _get_bool_flag_from_env(
         'OTEL_GCP_RESOURCE_DETECTOR_ENABLED')
     if result is not None:

opentelemetry-configurator-gcp/src/opentelemetry/configurator/gcp/gcloud_env.py

@@ -1,38 +1,90 @@
+"""Provides 'is_running_on_gcp' to determine whether to enable the GCP resource detector."""
 import os
 import os.path
 import socket
 
 
 def _can_resolve_metadata_server():
+    """Returns whether the GCP metadata server address can be resolved.
+    
+    On GCP, there is a special 'metadata.google.internal' DNS name that is
+    used to supply metadata about the environment. Although it is possible
+    to edit "/etc/hosts" to introduce a similarly-named service outside
+    of GCP, the existence of this name is a strong hint of running in GCP.
+    """
     try:
         socket.getaddrinfo('metadata.google.internal', 80)
         return True
-    except:
+    except OSError:
         return False
 
 
 def _is_likely_gae():
+    """Returns whether env vars indicate a GAE environment.
+
+    The Google App Engine documentation calls out several of these
+    environment variables as being automatically setup by the runtime.
+
+    Although it is possible to set these manually outside of GAE, the
+    presence of these in conjunction with the presence of the metadata
+    server provides a strong hint of running within GAE.
+    """
     return (('GAE_APPLICATION' in os.environ) and
             ('GAE_DEPLOYMENT_ID' in os.environ) and
             ('GAE_SERVICE' in os.environ))
 
 
 def _is_likely_cloud_run():
+    """Returns whether env vars indicate a Cloud Run environment.
+
+    The Cloud Run documentation calls out several of these
+    environment variables as being automatically setup by the runtime.
+
+    Some of these may aslo be present when running K-Native in Kubernetes;
+    however, the presence of these environment variables in conjunction
+    with the presence of the metadata server provide a strong hint
+    that the code is running inside of Cloud Run.
+    """
     return (
         ('K_SERVICE' in os.environ) and
         ('K_REVISION' in os.environ) and
         ('K_CONFIGURATION' in os.environ))
 
 
 def _is_likely_gce():
+    """Returns whether there is evidence of running in GCE.
+    
+    The given pre-supplied paths are called out in GCE documentation
+    and are not likely to exist in other environments. In conjunction
+    with the existing of the metadata server, the checks here provide
+    supportive evidence of running within a GCE environment.
+    """
     return os.path.exists('/run/google-mds-mtls')
 
 
 def _is_likely_gke():
-    return ('KUBERNETES_SERVICE_HOST' in os.environ)
+    """Returns whether there is evidence of runing in GKE.
+
+    Although also applicable to Kubernetes outside of GCP,
+    the evidence of Kubernetes in conjunction with the presence
+    of the GCP metadata server strongly hints at GKE.
+    """
+    return 'KUBERNETES_SERVICE_HOST' in os.environ
 
 
 def is_running_on_gcp():
+    """Returns whether the code is probably running on GCP.
+    
+    This is not intended to be 100% bullet proof nor
+    comprehensive of the entire GCP ecosystem; rather, it
+    is intended to be "good enough" to determine whether to
+    pay the additional costs of GCP resource detection.
+
+    That is, it should ideally be light-weight (if it's too
+    expensive, you might as well always do GCP resource
+    detection), and it should ideally cover the subset
+    of GCP environments for which resource detction exists.
+    """
     return (
         _can_resolve_metadata_server() and
         (
@@ -42,4 +94,3 @@ def is_running_on_gcp():
             _is_likely_gae()
         )
     )
-

opentelemetry-configurator-gcp/src/opentelemetry/configurator/gcp/logs.py

@@ -1,4 +1,4 @@
-import sys
+"""Provides a mechanism to configure the Logs Exporter for GCP."""
 import os
 import os.path
 import logging
@@ -19,21 +19,6 @@
 }
 
 
-def _get_entrypoint_script_name():
-    main_script_path = sys.argv[0]
-    if not main_script_path:
-        main_script_path = sys.executable
-    simple_script_name = os.path.basename(main_script_path).rstrip('.py')
-    return simple_script_name
-
-
-def _get_log_name():
-    log_name = os.getenv('OTEL_GCP_LOG_NAME')
-    if log_name:
-        return log_name
-    return _get_entrypoint_script_name()
-
-
 def _get_log_level():
     level = os.getenv(otel_env_vars.OTEL_LOG_LEVEL)
     if level is None:
@@ -45,9 +30,19 @@ def _get_log_level():
 
 
 def configure_logs_exporter(resource=None):
+    """Configures the Cloud Logging exporter.
+    
+    Args:
+        resource: the resource to include in the emitted logs
+
+    Effects:
+        - Invokes the 'set_logger_provider' function with an
+          exporter that will cause OTel logs to get routed to GCP.
+        - Modifies the built-in 'logging' component in Python to
+          route built-in Python logs to Open Telemetry.
+    """
     provider = LoggerProvider(resource=resource)
-    provider.add_log_record_processor(BatchLogRecordProcessor(
-        CloudLoggingExporter(default_log_name=_get_log_name())))
+    provider.add_log_record_processor(BatchLogRecordProcessor(CloudLoggingExporter()))
     set_logger_provider(provider)
     handler = LoggingHandler(level=_get_log_level(), logger_provider=provider)
     logging.getLogger().addHandler(handler)

opentelemetry-configurator-gcp/src/opentelemetry/configurator/gcp/metrics.py

@@ -1,10 +1,20 @@
+"""Provides a mechanism to configure the Metrics Exporter for GCP."""
 from opentelemetry import metrics as otel_metrics
 from opentelemetry.sdk import metrics as otel_metrics_sdk
 from opentelemetry.sdk.metrics import export as otel_metrics_sdk_export
 from opentelemetry.exporter import cloud_monitoring as otel_cloud_monitoring
 
 
 def configure_metrics_exporter(resource=None):
+    """Configures the Open Telemetry metrics library to write to Cloud Monitoring.
+    
+    Args:
+      resource: The resource to use when writing metrics.
+
+    Effects:
+      Calls 'set_meter_provider' with a MeterProvider that will cause
+      Open Telemetry metrics to get routed to Cloud Monitoring.
+    """
     provider = otel_metrics_sdk.MeterProvider(
         metric_readers=[
             otel_metrics_sdk_export.PeriodicExportingMetricReader(

opentelemetry-configurator-gcp/src/opentelemetry/configurator/gcp/resource.py

@@ -1,13 +1,27 @@
+"""Provides a mechanism to configure the Resource Detector for GCP."""
 from opentelemetry.sdk import resources as otel_resources_sdk
 from opentelemetry.resourcedetector import gcp_resource_detector
 
 
 def get_resource(include_gcp_detector=False):
-  detectors = [
-      otel_resources_sdk.OTELResourceDetector(),
-      otel_resources_sdk.ProcessResourceDetector(),
-      otel_resources_sdk.OsResourceDetector(),
-  ]
-  if include_gcp_detector:
-      detectors.append(gcp_resource_detector.GoogleCloudResourceDetector())
-  return otel_resources_sdk.get_aggregated_resources(detectors)
+    """Calculate the resource to use in Open Telemetry signals.
+  
+    Args:
+      include_gcp_detector: Whether to merge in information about
+        the GCP environment in which the code is running.
+
+    Effects:
+      Gathers information about the current environment to produce
+      a resource that summarizes the running environment.
+
+    Returns:
+      A resource that summarizes the environment.
+    """
+    detectors = [
+        otel_resources_sdk.OTELResourceDetector(),
+        otel_resources_sdk.ProcessResourceDetector(),
+        otel_resources_sdk.OsResourceDetector(),
+    ]
+    if include_gcp_detector:
+        detectors.append(gcp_resource_detector.GoogleCloudResourceDetector())
+    return otel_resources_sdk.get_aggregated_resources(detectors)