diff --git a/CHANGELOG.md b/CHANGELOG.md index 6fbdec54..b40782b1 100644 --- a/CHANGELOG.md +++ b/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)) diff --git a/azure-monitor-opentelemetry/README.md b/azure-monitor-opentelemetry/README.md index 3b940298..958e7acf 100644 --- a/azure-monitor-opentelemetry/README.md +++ b/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="", + 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 `_config` and value as a dictionary representing `kwargs` for the corresponding instrumentation. - -```python -... -configure_azure_monitor( - 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 diff --git a/azure-monitor-opentelemetry/azure/monitor/opentelemetry/_configure.py b/azure-monitor-opentelemetry/azure/monitor/opentelemetry/_configure.py index 7eefae01..dc4c92ec 100644 --- a/azure-monitor-opentelemetry/azure/monitor/opentelemetry/_configure.py +++ b/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] _config: Specifies a dictionary of kwargs that will be applied to configuration for 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 `/Microsoft/AzureMonitor/opentelemetry-python-`. :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 {"": {"":}} - 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"): diff --git a/azure-monitor-opentelemetry/samples/tracing/http_fastapi.py b/azure-monitor-opentelemetry/samples/tracing/http_fastapi.py index 8d427705..f7a0f4ba 100644 --- a/azure-monitor-opentelemetry/samples/tracing/http_fastapi.py +++ b/azure-monitor-opentelemetry/samples/tracing/http_fastapi.py @@ -11,7 +11,11 @@ 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, ) diff --git a/azure-monitor-opentelemetry/samples/tracing/http_flask.py b/azure-monitor-opentelemetry/samples/tracing/http_flask.py index ca8039ec..a492ba5c 100644 --- a/azure-monitor-opentelemetry/samples/tracing/http_flask.py +++ b/azure-monitor-opentelemetry/samples/tracing/http_flask.py @@ -11,7 +11,11 @@ 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, ) diff --git a/azure-monitor-opentelemetry/samples/tracing/http_requests.py b/azure-monitor-opentelemetry/samples/tracing/http_requests.py index 0ad78e8e..64b4de49 100644 --- a/azure-monitor-opentelemetry/samples/tracing/http_requests.py +++ b/azure-monitor-opentelemetry/samples/tracing/http_requests.py @@ -16,7 +16,11 @@ 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, ) diff --git a/azure-monitor-opentelemetry/tests/configuration/test_configure.py b/azure-monitor-opentelemetry/tests/configuration/test_configure.py index 52be1f3b..be264574 100644 --- a/azure-monitor-opentelemetry/tests/configuration/test_configure.py +++ b/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()