Add Microsoft Opentelemetry Distro Configuration

CHANGELOG.md

@@ -10,4 +10,8 @@
 
 ### Other Changes
 - Added `azure-monitor-opentelemetry` package source for Azure Monitor OpenTelemetry distro integration.
+- Added `microsoft.opentelemetry` distro configuration with `use_microsoft_opentelemetry()` entry point for Azure Monitor.
+- Added `azure_monitor_enable_live_metrics` and `azure_monitor_enable_performance_counters` kwargs passed directly to `configure_azure_monitor()`.
+- Renamed `disable_azure_monitor_exporter` kwarg to `enable_azure_monitor` (inverted, defaults to True).
+- Prefixed Azure Monitor-specific kwargs with `azure_monitor_` (e.g. `azure_monitor_connection_string`, `azure_monitor_exporter_credential`).
 - Project metadata, license, and documentation

README.md

@@ -19,15 +19,67 @@ The target package should reduce fragmented setup across multiple observability
 Intended API shape:
 
 ```python
-from microsoft.opentelemetry import configure_microsoft_opentelemetry
+from microsoft.opentelemetry import use_microsoft_opentelemetry
 
-configure_microsoft_opentelemetry(
+use_microsoft_opentelemetry(
 	azure_monitor_connection_string="InstrumentationKey=...;IngestionEndpoint=...",
-	enable_otlp_export=True,
-	enable_genai_openai_instrumentation=True,
 )
 ```
 
+### Available Configuration Options
+
+| Keyword argument | Type | Default | Description |
+|---|---|---|---|
+| `enable_azure_monitor` | `bool` | `True` | Enable Azure Monitor export. |
+| `azure_monitor_connection_string` | `str` | `None` | Connection string for Application Insights. Also read from `APPLICATIONINSIGHTS_CONNECTION_STRING` env var. |
+| `azure_monitor_exporter_credential` | `TokenCredential` | `None` | Azure AD token credential for authentication. |
+| `azure_monitor_enable_live_metrics` | `bool` | `True` | Enable live metrics collection. |
+| `azure_monitor_enable_performance_counters` | `bool` | `True` | Enable performance counter collection. |
+| `azure_monitor_exporter_disable_offline_storage` | `bool` | `False` | Disable offline retry storage for failed telemetry. |
+| `azure_monitor_exporter_storage_directory` | `str` | `None` | Custom directory for offline telemetry storage. |
+| `azure_monitor_browser_sdk_loader_config` | `dict` | `None` | Browser SDK loader configuration. |
+| `disable_logging` | `bool` | `False` | Disable the logging pipeline. |
+| `disable_tracing` | `bool` | `False` | Disable the tracing pipeline. |
+| `disable_metrics` | `bool` | `False` | Disable the metrics pipeline. |
+| `resource` | `Resource` | auto | OpenTelemetry Resource. |
+| `span_processors` | `list` | `[]` | Additional span processors. |
+| `log_record_processors` | `list` | `[]` | Additional log record processors. |
+| `metric_readers` | `list` | `[]` | Additional metric readers. |
+| `views` | `list` | `[]` | Metric views. |
+| `logger_name` | `str` | `None` | Logger name for log collection. |
+| `logging_formatter` | `Formatter` | `None` | Formatter for collected logs. |
+| `instrumentation_options` | `dict` | `None` | Per-library instrumentation enable/disable options. |
+| `enable_trace_based_sampling_for_logs` | `bool` | `False` | Enable trace-based sampling for logs. |
+
+### Sampling Configuration
+
+Sampling is configured via standard OpenTelemetry environment variables:
+
+| Environment variable | Description |
+|---|---|
+| `OTEL_TRACES_SAMPLER` | Sampler type to use (see supported values below). |
+| `OTEL_TRACES_SAMPLER_ARG` | Argument for the sampler (e.g. sample ratio or traces per second). |
+
+**Supported sampler values for `OTEL_TRACES_SAMPLER`:**
+
+| Value | Description |
+|---|---|
+| `always_on` | Sample every trace. |
+| `always_off` | Drop every trace. |
+| `trace_id_ratio` | Sample a fixed percentage based on trace ID. Set ratio with `OTEL_TRACES_SAMPLER_ARG` (0–1). |
+| `parentbased_always_on` | Parent-based, defaults to always on. |
+| `parentbased_always_off` | Parent-based, defaults to always off. |
+| `parentbased_trace_id_ratio` | Parent-based with trace ID ratio fallback. |
+| `microsoft.fixed_percentage` | Azure Monitor fixed-percentage sampler. Set ratio with `OTEL_TRACES_SAMPLER_ARG` (0–1). |
+| `microsoft.rate_limited` | Azure Monitor rate-limited sampler. Set target with `OTEL_TRACES_SAMPLER_ARG` (traces per second, default 5). |
+
+**Example:**
+
+```bash
+export OTEL_TRACES_SAMPLER=trace_id_ratio
+export OTEL_TRACES_SAMPLER_ARG=0.1
+```
+
 ## Planned Scope
 
 - Azure Monitor exporter support
@@ -56,13 +108,6 @@ The POC also describes this execution model:
 6. Enable Microsoft-specific observability instrumentations
 7. Enable GenAI contrib instrumentations
 
-## Current Repository Layout
-
-- `src/` package source
-- `tests/` test suite
-- `pyproject.toml` project metadata and dependencies
-- `PLANNING.md` implementation plan and open questions
-
 ## Development
 
 Create an environment and install the project with test dependencies:
@@ -93,4 +138,4 @@ This project may contain trademarks or logos for projects, products, or services
 
 ## License
 
-[MIT](LICENSE)
+[MIT](LICENSE)

pyproject.toml

@@ -8,7 +8,13 @@ version = "0.1.0"
 description = "Minimal template for the Microsoft OpenTelemetry distro for Python"
 readme = "README.md"
 requires-python = ">=3.10"
-dependencies = []
+dependencies = [
+    "opentelemetry-sdk>=1.0",
+    "opentelemetry-api>=1.0",
+    "opentelemetry-instrumentation>=0.40b0",
+    "azure-monitor-opentelemetry-exporter>=1.0.0b21",
+    "azure-core>=1.28.0",
+]
 
 [project.optional-dependencies]
 test = [
@@ -27,13 +33,15 @@ package-dir = {"" = "src"}
 
 [tool.setuptools.packages.find]
 where = ["src"]
+namespaces = true
 
 [tool.black]
 line-length = 120
 target-version = ["py310"]
 
 [tool.pylint.main]
 py-version = "3.10"
+ignore-paths = ["tests/azureMonitor"]
 
 [tool.pylint.format]
 max-line-length = 120
@@ -42,17 +50,48 @@ max-line-length = 120
 disable = [
     "missing-function-docstring",
     "missing-module-docstring",
+    "missing-class-docstring",
+    "import-outside-toplevel",
+    "import-error",
+    "no-name-in-module",
+    "duplicate-code",
+    "too-few-public-methods",
+    "too-many-arguments",
+    "too-many-positional-arguments",
+    "too-many-locals",
+    "wrong-import-order",
+    "ungrouped-imports",
+    "unknown-option-value",
+    "fixme",
+    "invalid-name",
 ]
 
 [tool.mypy]
 python_version = "3.10"
 warn_return_any = true
 warn_unused_configs = true
 disallow_untyped_defs = true
+namespace_packages = true
+explicit_package_bases = true
+mypy_path = "src"
+
+[[tool.mypy.overrides]]
+module = "microsoft.azureMonitor.*"
+disallow_untyped_defs = false
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = [
+    "django.*",
+    "azure.core.*",
+    "opentelemetry.instrumentation.*",
+]
+ignore_missing_imports = true
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 
 [tool.pyright]
 pythonVersion = "3.10"
 typeCheckingMode = "basic"
+ignore = ["src/microsoft/azureMonitor", "tests/azureMonitor"]

samples/langchain/sample_opentelemetry.py

@@ -15,8 +15,8 @@
 
 configure_azure_monitor()  # Replace with the opentelemetry distro
 
-# configure_microsoft_opentelemetry(
-#     connection_string="InstrumentationKey=...",
+# use_microsoft_opentelemetry(
+#     azure_monitor_connection_string="InstrumentationKey=...",
 #     enable_genai_langchain=True,
 # )
 

src/microsoft/azureMonitor/__init__.py

@@ -0,0 +1,18 @@
+# -------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License in the project root for
+# license information.
+# -------------------------------------------------------------------------
+
+# Extend path so the exporter subpackage (azure-monitor-opentelemetry-exporter)
+# is discoverable when this package is installed in editable/development mode.
+__path__ = __import__("pkgutil").extend_path(__path__, __name__)
+
+from microsoft.azureMonitor._configure import configure_azure_monitor
+
+from ._version import VERSION
+
+__all__ = [
+    "configure_azure_monitor",
+]
+__version__ = VERSION

src/microsoft/azureMonitor/_autoinstrumentation/__init__.py

@@ -0,0 +1,5 @@
+# -------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License in the project root for
+# license information.
+# -------------------------------------------------------------------------

src/microsoft/azureMonitor/_autoinstrumentation/configurator.py

@@ -0,0 +1,69 @@
+# -------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License in the project root for
+# license information.
+# --------------------------------------------------------------------------
+
+
+from os import environ
+from warnings import warn
+
+from opentelemetry.environment_variables import (
+    OTEL_LOGS_EXPORTER,
+    OTEL_METRICS_EXPORTER,
+    OTEL_TRACES_EXPORTER,
+)
+from opentelemetry.sdk._configuration import _OTelSDKConfigurator
+
+from azure.monitor.opentelemetry.exporter import (  # pylint: disable=import-error,no-name-in-module
+    ApplicationInsightsSampler,
+)
+from azure.monitor.opentelemetry.exporter._utils import (  # pylint: disable=import-error,no-name-in-module
+    _is_attach_enabled,
+)
+from microsoft.azureMonitor._constants import (
+    _PREVIEW_ENTRY_POINT_WARNING,
+    LOG_EXPORTER_NAMES_ARG,
+    METRIC_EXPORTER_NAMES_ARG,
+    SAMPLER_ARG,
+    TRACE_EXPORTER_NAMES_ARG,
+)
+from microsoft.azureMonitor._diagnostics.diagnostic_logging import (
+    AzureDiagnosticLogging,
+    _ATTACH_FAILURE_CONFIGURATOR,
+    _ATTACH_SUCCESS_CONFIGURATOR,
+)
+from microsoft.azureMonitor._diagnostics.status_logger import (
+    AzureStatusLogger,
+)
+
+
+class AzureMonitorConfigurator(_OTelSDKConfigurator):
+    def _configure(self, **kwargs):
+        if not _is_attach_enabled():
+            warn(_PREVIEW_ENTRY_POINT_WARNING)
+        try:
+            if environ.get(OTEL_TRACES_EXPORTER, "").lower().strip() != "none":
+                kwargs.setdefault(TRACE_EXPORTER_NAMES_ARG, ["azure_monitor_opentelemetry_exporter"])
+                try:
+                    sample_rate = float(environ.get("OTEL_TRACES_SAMPLER_ARG", 1.0))
+                except ValueError:
+                    sample_rate = 1.0
+                kwargs.setdefault(SAMPLER_ARG, ApplicationInsightsSampler(sample_rate))
+            if environ.get(OTEL_METRICS_EXPORTER, "").lower().strip() != "none":
+                kwargs.setdefault(METRIC_EXPORTER_NAMES_ARG, ["azure_monitor_opentelemetry_exporter"])
+            if environ.get(OTEL_LOGS_EXPORTER, "").lower().strip() != "none":
+                kwargs.setdefault(LOG_EXPORTER_NAMES_ARG, ["azure_monitor_opentelemetry_exporter"])
+            # As of OTel SDK 1.25.0, exporters passed as kwargs will be added to those specified in env vars.
+            super()._configure(**kwargs)
+            AzureStatusLogger.log_status(True)
+            AzureDiagnosticLogging.info(
+                "Azure Monitor Configurator configured successfully.",
+                _ATTACH_SUCCESS_CONFIGURATOR,
+            )
+        except Exception as e:
+            AzureDiagnosticLogging.error(  # pylint: disable=C
+                "Azure Monitor Configurator failed during configuration: %s" % str(e),
+                _ATTACH_FAILURE_CONFIGURATOR,
+            )
+            raise e

src/microsoft/azureMonitor/_autoinstrumentation/distro.py

@@ -0,0 +1,65 @@
+# -------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License in the project root for
+# license information.
+# --------------------------------------------------------------------------
+from os import environ
+from warnings import warn
+
+from opentelemetry.instrumentation.distro import (  # type: ignore
+    BaseDistro,
+)
+from opentelemetry.sdk.environment_variables import (
+    _OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED,
+    OTEL_EXPERIMENTAL_RESOURCE_DETECTORS,
+)
+
+from azure.core.settings import settings
+from azure.core.tracing.ext.opentelemetry_span import OpenTelemetrySpan
+from azure.monitor.opentelemetry.exporter._utils import (  # pylint: disable=import-error,no-name-in-module
+    _is_attach_enabled,
+)
+from microsoft.azureMonitor._constants import (
+    _AZURE_APP_SERVICE_RESOURCE_DETECTOR_NAME,
+    _AZURE_SDK_INSTRUMENTATION_NAME,
+    _PREVIEW_ENTRY_POINT_WARNING,
+)
+from microsoft.azureMonitor._diagnostics.diagnostic_logging import (
+    AzureDiagnosticLogging,
+    _ATTACH_FAILURE_DISTRO,
+    _ATTACH_SUCCESS_DISTRO,
+)
+from microsoft.azureMonitor._diagnostics.status_logger import (
+    AzureStatusLogger,
+)
+from microsoft.azureMonitor._utils.configurations import (
+    _get_otel_disabled_instrumentations,
+)
+
+
+class AzureMonitorDistro(BaseDistro):
+    def _configure(self, **kwargs) -> None:
+        if not _is_attach_enabled():
+            warn(_PREVIEW_ENTRY_POINT_WARNING)
+        try:
+            _configure_auto_instrumentation()
+            AzureStatusLogger.log_status(True)
+            AzureDiagnosticLogging.info(
+                "Azure Monitor OpenTelemetry Distro configured successfully.",
+                _ATTACH_SUCCESS_DISTRO,
+            )
+        except Exception as e:
+            AzureStatusLogger.log_status(False, reason=str(e))
+            AzureDiagnosticLogging.error(  # pylint: disable=C
+                "Azure Monitor OpenTelemetry Distro failed during configuration: %s" % str(e),
+                _ATTACH_FAILURE_DISTRO,
+            )
+            raise e
+
+
+def _configure_auto_instrumentation() -> None:
+    environ.setdefault(_OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED, "true")
+    environ.setdefault(OTEL_EXPERIMENTAL_RESOURCE_DETECTORS, _AZURE_APP_SERVICE_RESOURCE_DETECTOR_NAME)
+    otel_disabled_instrumentations = _get_otel_disabled_instrumentations()
+    if _AZURE_SDK_INSTRUMENTATION_NAME not in otel_disabled_instrumentations:
+        settings.tracing_implementation = OpenTelemetrySpan