Merge pull request #259 from lzchen/instr

Author: lzchen

CHANGELOG.md

@@ -10,6 +10,8 @@
     ([#255](https://github.com/microsoft/ApplicationInsights-Python/pull/255))
 - Add support for Urllib3/Urllib instrumentation
     ([#256](https://github.com/microsoft/ApplicationInsights-Python/pull/256))
+- Change instrumentation config to use TypedDict InstrumentationConfig
+    ([#259](https://github.com/microsoft/ApplicationInsights-Python/pull/259))
 - Change interval params to use `_ms` as suffix
     ([#260](https://github.com/microsoft/ApplicationInsights-Python/pull/260))
 

azure-monitor-opentelemetry/README.md

@@ -8,15 +8,17 @@ This distro automatically installs the following libraries:
 
 ## Officially supported instrumentations
 
-The following OpenTelemetry instrumentations come bundled in with the Azure monitor distro. If you would like to add support for another OpenTelemetry instrumentation, please submit a feature [request][distro_feature_request]. In the meantime, you can use the OpenTelemetry instrumentation manually via it's own APIs (i.e. `instrument()`) in your code. See [this][samples_manual] for an example.
-
-* [OpenTelemetry Django Instrumentation][opentelemetry_instrumentation_django]
-* [OpenTelemetry FastApi Instrumentation][opentelemetry_instrumentation_fastapi]
-* [OpenTelemetry Flask Instrumentation][opentelemetry_instrumentation_flask]
-* [OpenTelemetry Psycopg2 Instrumentation][opentelemetry_instrumentation_psycopg2]
-* [OpenTelemetry Requests Instrumentation][opentelemetry_instrumentation_requests]
-* [OpenTelemetry UrlLib Instrumentation][opentelemetry_instrumentation_urllib]
-* [OpenTelemetry UrlLib3 Instrumentation][opentelemetry_instrumentation_urllib3]
+OpenTelemetry instrumentations allow automatic collection of requests sent from underlying instrumented libraries. The following is a list of OpenTelemetry instrumentations that come bundled in with the Azure monitor distro. If you would like to add support for another OpenTelemetry instrumentation, please submit a feature [request][distro_feature_request]. In the meantime, you can use the OpenTelemetry instrumentation manually via it's own APIs (i.e. `instrument()`) in your code. See [this][samples_manual] for an example.
+
+| Instrumentation                       | Supported library | Supported versions |
+| ------------------------------------- | ----------------- | ------------------ |
+| [OpenTelemetry Django Instrumentation][ot_instrumentation_django] | [django][pypi_django] | [link][ot_instrumentation_django_version]
+| [OpenTelemetry FastApi Instrumentation][ot_instrumentation_fastapi] | [fastapi][pypi_fastapi] | [link][ot_instrumentation_fastapi_version]
+| [OpenTelemetry Flask Instrumentation][ot_instrumentation_flask] | [flask][pypi_flask] | [link][ot_instrumentation_flask_version]
+| [OpenTelemetry Psycopg2 Instrumentation][ot_instrumentation_psycopg2] | [psycopg2][pypi_psycopg2] | [link][ot_instrumentation_psycopg2_version]
+| [OpenTelemetry Requests Instrumentation][ot_instrumentation_requests] | [requests][pypi_requests] | [link][ot_instrumentation_requests_version]
+| [OpenTelemetry UrlLib Instrumentation][ot_instrumentation_urllib] | [urllib][pypi_urllib] | All
+| [OpenTelemetry UrlLib3 Instrumentation][ot_instrumentation_urllib3] | [urllib3][pypi_urllib3] | [link][ot_instrumentation_urllib3_version]
 
 ## Getting started
 
@@ -54,6 +56,21 @@ You can use `configure_azure_monitor` to set up instrumentation for your app to
 * disable_metrics - If set to `True`, disables collection and export of metric telemetry. Defaults to `False`.
 * disable_tracing - If set to `True`, disables collection and export of distributed tracing telemetry. Defaults to `False`.
 * exclude_instrumentations - By default, all supported [instrumentations](#officially-supported-instrumentations) are enabled to collect telemetry. Specify instrumentations you do not want to enable to collect telemetry by passing in a comma separated list of instrumented library names. e.g. `["requests", "flask"]`
+* instrumentation_config - Specifies a dictionary of kwargs that will be applied to instrumentation configuration. You can specify which instrumentation you want to configure by name in the key field and value as a dictionary representing `kwargs` for the corresponding instrumentation.
+    Refer to the `Supported Library` section [above](#officially-supported-instrumentations) for the list of suppoprted library names.
+
+```python
+...
+configure_azure_monitor(
+    connection_string="<your-connection-string>",
+    flask_config={"excluded_urls": "http://localhost:8080/ignore"},
+    requests_config={"excluded_urls": "http://example.com"},
+)
+...
+```
+
+Take a look at the specific [instrumenation][ot_instrumentations] documentation for available configurations.
+
 * resource - Specified the OpenTelemetry [resource][opentelemetry_spec_resource] associated with your application. See [this][ot_sdk_python_resource] for default behavior.
 * logging_level - Specifies the [logging level][logging_level] of the logs you would like to collect for your logging pipeline. Defaults to logging.NOTSET.
 * logger_name = Specifies the [logger name][logger_name_hierarchy_doc] under which logging will be instrumented. Defaults to "" which corresponds to the root logger.
@@ -63,9 +80,9 @@ You can use `configure_azure_monitor` to set up instrumentation for your app to
 * sampling_ratio - Specifies the ratio of distributed tracing telemetry to be [sampled][application_insights_sampling]. Accepted values are in the range [0,1]. Defaults to 1.0, meaning no telemetry is sampled out.
 * tracing_export_interval_ms - Specifies the distributed tracing export interval in milliseconds. Defaults to 5000.
 
-#### Exporter configurations
+#### Azure monitor OpenTelemetry Exporter configurations
 
-You can pass exporter configuration parameters directly into `configure_azure_monitor`. See additional [configuration related to exporting here][exporter_configuration_docs].
+You can pass Azure monitor OpenTelemetry exporter configuration parameters directly into `configure_azure_monitor`. See additional [configuration related to exporting here][exporter_configuration_docs].
 
 ```python
 ...
@@ -76,22 +93,6 @@ configure_azure_monitor(
 ...
 ```
 
-#### Instrumentation configurations
-
-You can pass in instrumentation specific configuration into `configure_azure_monitor` with the key `<instrumented-library-name>_config` and value as a dictionary representing `kwargs` for the corresponding instrumentation.
-
-```python
-...
-configure_azure_monitor(
-    connection_string="<your-connection-string>",
-    flask_config={"excluded_urls": "http://localhost:8080/ignore"},
-    requests_config={"excluded_urls": "http://example.com"},
-)
-...
-```
-
-Take a look at the specific [instrumenation][ot_instrumentations] documentation for available configurations.
-
 ### Samples
 
 Samples are available [here][samples] to demonstrate how to utilize the above configuration options.
@@ -119,16 +120,29 @@ Samples are available [here][samples] to demonstrate how to utilize the above co
 [ot_sdk_python_metric_reader]: https://opentelemetry-python.readthedocs.io/en/stable/sdk/metrics.export.html#opentelemetry.sdk.metrics.export.MetricReader
 [ot_sdk_python_resource]: https://github.com/open-telemetry/opentelemetry-python/blob/main/opentelemetry-sdk/src/opentelemetry/sdk/resources/__init__.py#L153
 [ot_sdk_python_view_examples]: https://github.com/open-telemetry/opentelemetry-python/tree/main/docs/examples/metrics/views
-[opentelemetry_instrumentation_django]: https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-django
-[opentelemetry_instrumentation_fastapi]: https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-fastapi
-[opentelemetry_instrumentation_flask]: https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-flask
-[opentelemetry_instrumentation_psycopg2]: https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-psycopg2
-[opentelemetry_instrumentation_requests]: https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-requests
-[opentelemetry_instrumentation_urllib]: https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-urllib
-[opentelemetry_instrumentation_urllib3]: https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-urllib3
+[ot_instrumentation_django]: https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-django
+[ot_instrumentation_django_version]: https://github.com/open-telemetry/opentelemetry-python-contrib/blob/main/instrumentation/opentelemetry-instrumentation-django/src/opentelemetry/instrumentation/django/package.py#L16
+[ot_instrumentation_fastapi]: https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-fastapi
+[ot_instrumentation_fastapi_version]: https://github.com/open-telemetry/opentelemetry-python-contrib/blob/main/instrumentation/opentelemetry-instrumentation-fastapi/src/opentelemetry/instrumentation/fastapi/package.py#L16
+[ot_instrumentation_flask]: https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-flask
+[ot_instrumentation_flask_version]: https://github.com/open-telemetry/opentelemetry-python-contrib/blob/main/instrumentation/opentelemetry-instrumentation-flask/src/opentelemetry/instrumentation/flask/package.py#L16
+[ot_instrumentation_psycopg2]: https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-psycopg2
+[ot_instrumentation_psycopg2_version]: https://github.com/open-telemetry/opentelemetry-python-contrib/blob/main/instrumentation/opentelemetry-instrumentation-psycopg2/src/opentelemetry/instrumentation/psycopg2/package.py#L16
+[ot_instrumentation_requests]: https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-requests
+[ot_instrumentation_requests_version]: https://github.com/open-telemetry/opentelemetry-python-contrib/blob/main/instrumentation/opentelemetry-instrumentation-requests/src/opentelemetry/instrumentation/requests/package.py#L16
+[ot_instrumentation_urllib]: https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-urllib3
+[ot_instrumentation_urllib3]: https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-urllib3
+[ot_instrumentation_urllib3_version]: https://github.com/open-telemetry/opentelemetry-python-contrib/blob/main/instrumentation/opentelemetry-instrumentation-urllib3/src/opentelemetry/instrumentation/urllib3/package.py#L16
 [opentelemetry_spec_resource]: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/sdk.md#resource-sdk
 [opentelemetry_spec_view]: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#view
-[python]: https://www.python.org/downloads/
 [pip]: https://pypi.org/project/pip/
+[pypi_django]: https://pypi.org/project/Django/
+[pypi_fastapi]: https://pypi.org/project/fastapi/
+[pypi_flask]: https://pypi.org/project/Flask/
+[pypi_psycopg2]: https://pypi.org/project/psycopg2/
+[pypi_requests]: https://pypi.org/project/requests/
+[pypi_urllib]: https://docs.python.org/3/library/urllib.html
+[pypi_urllib3]: https://pypi.org/project/urllib3/
+[python]: https://www.python.org/downloads/
 [samples]: https://github.com/microsoft/ApplicationInsights-Python/tree/main/azure-monitor-opentelemetry/samples
 [samples_manual]: https://github.com/microsoft/ApplicationInsights-Python/tree/main/azure-monitor-opentelemetry/samples/tracing/manual.py

azure-monitor-opentelemetry/azure/monitor/opentelemetry/_configure.py

@@ -4,7 +4,7 @@
 # license information.
 # --------------------------------------------------------------------------
 from logging import NOTSET, getLogger
-from typing import Dict
+from typing import Any, Dict
 
 from azure.monitor.opentelemetry._types import ConfigurationValue
 from azure.monitor.opentelemetry.exporter import (
@@ -33,7 +33,6 @@
 _logger = getLogger(__name__)
 
 
-_INSTRUMENTATION_CONFIG_SUFFIX = "_config"
 _SUPPORTED_INSTRUMENTED_LIBRARIES = (
     "django",
     "fastapi",
@@ -45,6 +44,9 @@
 )
 
 
+InstrumentationConfig = Dict[str, Dict[str, Any]]
+
+
 def configure_azure_monitor(**kwargs) -> None:
     """
     This function works as a configuration layer that allows the
@@ -63,7 +65,9 @@ def configure_azure_monitor(**kwargs) -> None:
     :keyword Sequence[View] views: Specifies the list of views to configure for the metric pipeline.
     :keyword float sampling_ratio: Specifies the ratio of distributed tracing telemetry to be sampled. Accepted values are in the range [0,1]. Defaults to 1.0, meaning no telemetry is sampled out.
     :keyword int tracing_export_interval_ms: Specifies the distributed tracing export interval in milliseconds. Defaults to 5000.
-    :keyword Dict[str, Any] <instrumentation>_config: Specifies a dictionary of kwargs that will be applied to configuration for instrumentation <instrumentation>.
+    :keyword InstrumentationConfig instrumentation_config: Specifies a dictionary of kwargs that will be applied to instrumentation configuration. You can specify which instrumentation you want to
+        configure by name in the key field and value as a dictionary representing `kwargs` for the corresponding instrumentation.
+        Refer to the `Supported Library` section of https://github.com/microsoft/ApplicationInsights-Python/tree/main/azure-monitor-opentelemetry#officially-supported-instrumentations for the list of suppoprted library names.
     :keyword bool disable_offline_storage: Boolean value to determine whether to disable storing failed telemetry records for retry. Defaults to `False`.
     :keyword str storage_directory: Storage directory in which to store retry files. Defaults to `<tempfile.gettempdir()>/Microsoft/AzureMonitor/opentelemetry-python-<your-instrumentation-key>`.
     :rtype: None
@@ -162,14 +166,7 @@ def _setup_instrumentations(configurations: Dict[str, ConfigurationValue]):
     exclude_instrumentations = configurations.get(
         "exclude_instrumentations", []
     )
-    instrumentation_configs = {}
-
-    # Instrumentation specific configs
-    # Format is {"<library_name>": {"<config>":<value>}}
-    for k, v in configurations.items():
-        if k.endswith(_INSTRUMENTATION_CONFIG_SUFFIX):
-            lib_name = k.partition(_INSTRUMENTATION_CONFIG_SUFFIX)[0]
-            instrumentation_configs[lib_name] = v
+    instrumentation_configs = configurations.get("instrumentation_config", {})
 
     # use pkg_resources for now until https://github.com/open-telemetry/opentelemetry-python/pull/3168 is merged
     for entry_point in iter_entry_points("opentelemetry_instrumentor"):

azure-monitor-opentelemetry/samples/tracing/http_fastapi.py

@@ -11,7 +11,11 @@
     connection_string="<your-connection-string>",
     disable_logging=True,
     disable_metrics=True,
-    fastapi_config={"excluded_urls": "http://127.0.0.1:8000/exclude"},
+    instrumentation_config={
+        "fastapi": {
+            "excluded_urls": "http://127.0.0.1:8000/exclude",
+        }
+    },
     tracing_export_interval_ms=15000,
 )
 

azure-monitor-opentelemetry/samples/tracing/http_flask.py

@@ -11,7 +11,11 @@
     connection_string="<your-connection-string>",
     disable_logging=True,
     disable_metrics=True,
-    flask_config={"excluded_urls": "http://localhost:8080/ignore"},
+    instrumentation_config={
+        "flask": {
+            "excluded_urls": "http://localhost:8080/ignore",
+        }
+    },
     tracing_export_interval_ms=15000,
 )
 

azure-monitor-opentelemetry/samples/tracing/http_requests.py

@@ -16,7 +16,11 @@
     connection_string="<your-connection-string>",
     disable_logging=True,
     disable_metrics=True,
-    requests_config={"excluded_urls": "http://example.com"},
+    instrumentation_config={
+        "requests": {
+            "excluded_urls": "http://example.com",
+        }
+    },
     tracing_export_interval_ms=15000,
 )
 

azure-monitor-opentelemetry/tests/configuration/test_configure.py

@@ -544,7 +544,11 @@ def test_setup_instrumentations_custom_configuration(
     ):
         libr_name = _SUPPORTED_INSTRUMENTED_LIBRARIES[0]
         configurations = {
-            libr_name + "_config": {"test_key": "test_value"},
+            "instrumentation_config": {
+                libr_name: {
+                    "test_key": "test_value",
+                }
+            },
         }
         ep_mock = Mock()
         iter_mock.return_value = [ep_mock]
@@ -574,8 +578,14 @@ def test_setup_instrumentations_custom_configuration_excluded(
         libr_name = _SUPPORTED_INSTRUMENTED_LIBRARIES[0]
         libr_name2 = _SUPPORTED_INSTRUMENTED_LIBRARIES[1]
         configurations = {
-            libr_name + "_config": {"test_key": "test_value"},
-            libr_name2 + "_config": {"test_key2": "test_value2"},
+            "instrumentation_config": {
+                libr_name: {
+                    "test_key": "test_value",
+                },
+                libr_name2: {
+                    "test_key2": "test_value2",
+                },
+            },
             "exclude_instrumentations": libr_name,
         }
         ep_mock = Mock()