Merge pull request #218 from jeremydvoss/logging

Author: lzchen

CHANGELOG.md

@@ -2,20 +2,22 @@
 
 ## Unreleased
 
-- Added Status Logger
-    ([#217](https://github.com/microsoft/ApplicationInsights-Python/pull/217))
-- Added Diagnostic Logging for App Service
-    ([#212](https://github.com/microsoft/ApplicationInsights-Python/pull/212))
 - Updated main and distro READMEs
     ([#205](https://github.com/microsoft/ApplicationInsights-Python/pull/205))
 - Update CONTRIBUTING.md, support Py3.11
     ([#210](https://github.com/microsoft/ApplicationInsights-Python/pull/210))
+- Added Diagnostic Logging for App Service
+    ([#212](https://github.com/microsoft/ApplicationInsights-Python/pull/212))
 - Updated setup.py, directory structure
     ([#214](https://github.com/microsoft/ApplicationInsights-Python/pull/214))
 - Introduce Distro API
     ([#215](https://github.com/microsoft/ApplicationInsights-Python/pull/215))
 - Rename to `configure_azure_monitor`, add sampler to config
     ([#216](https://github.com/microsoft/ApplicationInsights-Python/pull/216))
+- Added Status Logger
+    ([#217](https://github.com/microsoft/ApplicationInsights-Python/pull/217))
+- Add Logging configuration to Distro API
+    ([#218](https://github.com/microsoft/ApplicationInsights-Python/pull/218))
 
 ## [1.0.0b8](https://github.com/microsoft/ApplicationInsights-Python/releases/tag/v1.0.0b8) - 2022-09-26
 

azure-monitor-opentelemetry-distro/README.md

@@ -14,7 +14,7 @@ This distro automatically installs the following libraries:
 
 ### Key Concepts
 
-This package is simply a collection of OpenTelemetry and Azure Monitor components bundled together to enable the collection and sending of telemetry to Azure Monitor. For MANUAL instrumentation, it is equivalent to installing the above packages individually. AUTOMATIC instrumentation is not yet supported.
+This package bundles a series of OpenTelemetry and Azure Monitor components to enable the collection and sending of telemetry to Azure Monitor. For MANUAL instrumentation, use the `configure_azure_monitor` function. AUTOMATIC instrumentation is not yet supported.
 
 The [Azure Monitor OpenTelemetry exporters][azure_monitor_opentelemetry_exporters] are the main components in accomplishing this. You will be able to use the exporters and their APIs directly through this package. Please go the exporter documentation to understand how OpenTelemetry and Azure Monitor components work in enabling telemetry collection and exporting.
 
@@ -28,6 +28,23 @@ Install the Azure Monitor Opentelemetry Distro with [pip][pip]:
 pip install azure-monitor-opentelemetry-distro --pre
 ```
 
+### Usage
+
+You can use `configure_azure_monitor` to set up instrumentation for your app to Azure Monitor. `configure_azure_monitor` supports the following optional arguments:
+
+* connection_string - The [connection string][connection_string_doc] for your Application Insights resource. The connection string will be automatically populated from the `APPLICATIONINSIGHTS_CONNECTION_STRING` environment variable if not explicitly passed in.
+* service_name = Specifies the [service][service_semantic_convention_doc] name. 
+* service_namespace = Specifies the [service][service_semantic_convention_doc] namespace.
+* service_instance_id = Specifies the [service][service_semantic_convention_doc] instance id.
+* disable_logging = If set to `True`, disables collection and export of logging telemetry.
+* logging_level = Specifies the [logging level][logging_level] of the Opentelemetry Logging Handler. Ex: logging.WARNING.
+* logging_export_interval_millis = Specifies the export interval of the logging exporter in milliseconds. Defaults to 30,000.
+* disable_tracing = If set to `True`, disables collection and export of distributed tracing telemetry.
+* 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_millis = Specifies the export interval of the distributed tracing exporter in milliseconds. Defaults to 30,000.
+
+See additional [configuration related to exporting here][exporter_configuration_docs].
+
 ### Prerequisites:
 To use this package, you must have:
 * Azure subscription - [Create a free account][azure_sub]
@@ -44,12 +61,17 @@ To use this package, you must have:
 [azure_monitor_opentelemetry_exporters]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/monitor/azure-monitor-opentelemetry-exporter#microsoft-opentelemetry-exporter-for-azure-monitor
 [azure_portal]: https://portal.azure.com
 [azure_sub]: https://azure.microsoft.com/free/
-[application_insights_namespace]: https://docs.microsoft.com/azure/azure-monitor/app/
-[pip]: https://pypi.org/project/pip/
+[application_insights_namespace]: https://learn.microsoft.com/en-us/azure/azure-monitor/app/app-insights-overview
+[application_insights_sampling]: https://learn.microsoft.com/en-us/azure/azure-monitor/app/sampling
+[connection_string_doc]: https://learn.microsoft.com/en-us/azure/azure-monitor/app/sdk-connection-string
+[exporter_configuration_docs]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/monitor/azure-monitor-opentelemetry-exporter#configuration
+[logging_level]: https://docs.python.org/3/library/logging.html#levels
 [ot_python_docs]: https://opentelemetry.io/docs/instrumentation/python/
 [ot_sdk_python]: https://github.com/open-telemetry/opentelemetry-python
 [opentelemetry_instrumentation_requests]: https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-requests
 [opentelemetry_instrumentation_django]: https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-django
 [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
 [python]: https://www.python.org/downloads/
+[pip]: https://pypi.org/project/pip/
+[service_semantic_convention_doc]: https://github.com/open-telemetry/opentelemetry-specification/tree/main/specification/resource/semantic_conventions#service

azure-monitor-opentelemetry-distro/azure/monitor/opentelemetry/distro/__init__.py

@@ -3,16 +3,26 @@
 # Licensed under the MIT License. See License in the project root for
 # license information.
 # --------------------------------------------------------------------------
+from logging import NOTSET, getLogger
+
 from azure.monitor.opentelemetry.distro.util import get_configurations
 from azure.monitor.opentelemetry.exporter import (
     ApplicationInsightsSampler,
+    AzureMonitorLogExporter,
     AzureMonitorTraceExporter,
 )
-from opentelemetry import trace
+from opentelemetry.sdk._logs import (
+    LoggerProvider,
+    LoggingHandler,
+    get_logger_provider,
+    set_logger_provider,
+)
+from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
 from opentelemetry.sdk.resources import Resource
 from opentelemetry.sdk.trace import TracerProvider
 from opentelemetry.sdk.trace.export import BatchSpanProcessor
 from opentelemetry.semconv.resource import ResourceAttributes
+from opentelemetry.trace import get_tracer_provider, set_tracer_provider
 
 
 def configure_azure_monitor(**kwargs):
@@ -23,31 +33,51 @@ def configure_azure_monitor(**kwargs):
     """
 
     configurations = get_configurations(**kwargs)
-    disable_tracing = configurations.get("disable_tracing", False)
     service_name = configurations.get("service_name", "")
     service_namespace = configurations.get("service_namespace", "")
     service_instance_id = configurations.get("service_instance_id", "")
+    disable_logging = configurations.get("disable_logging", False)
+    logging_level = configurations.get("logging_level", NOTSET)
+    logging_export_interval_millis = configurations.get(
+        "logging_export_interval_millis", 30000
+    )
+    disable_tracing = configurations.get("disable_tracing", False)
     sampling_ratio = configurations.get("sampling_ratio", 1.0)
     tracing_export_interval_millis = configurations.get(
         "tracing_export_interval_millis", 30000
     )
 
-    if not disable_tracing:
+    resource = None
+    if not disable_logging or not disable_tracing:
         resource = Resource.create(
             {
                 ResourceAttributes.SERVICE_NAME: service_name,
                 ResourceAttributes.SERVICE_NAMESPACE: service_namespace,
                 ResourceAttributes.SERVICE_INSTANCE_ID: service_instance_id,
             }
         )
+    if not disable_logging:
+        logger_provider = LoggerProvider(resource=resource)
+        set_logger_provider(logger_provider)
+        log_exporter = AzureMonitorLogExporter(**kwargs)
+        log_record_processor = BatchLogRecordProcessor(
+            log_exporter,
+            export_timeout_millis=logging_export_interval_millis,
+        )
+        get_logger_provider().add_log_record_processor(log_record_processor)
+        handler = LoggingHandler(
+            level=logging_level, logger_provider=get_logger_provider()
+        )
+        getLogger().addHandler(handler)
+    if not disable_tracing:
         tracer_provider = TracerProvider(
             sampler=ApplicationInsightsSampler(sampling_ratio=sampling_ratio),
             resource=resource,
         )
-        trace.set_tracer_provider(tracer_provider)
-        exporter = AzureMonitorTraceExporter(**kwargs)
+        set_tracer_provider(tracer_provider)
+        trace_exporter = AzureMonitorTraceExporter(**kwargs)
         span_processor = BatchSpanProcessor(
-            exporter,
+            trace_exporter,
             export_timeout_millis=tracing_export_interval_millis,
         )
-        trace.get_tracer_provider().add_span_processor(span_processor)
+        get_tracer_provider().add_span_processor(span_processor)

azure-monitor-opentelemetry-distro/azure/monitor/opentelemetry/distro/distro.py

@@ -13,6 +13,7 @@
     AzureStatusLogger,
 )
 from opentelemetry.environment_variables import (
+    OTEL_LOGS_EXPORTER,
     OTEL_METRICS_EXPORTER,
     OTEL_TRACES_EXPORTER,
 )
@@ -55,6 +56,9 @@ def _configure_auto_instrumentation() -> None:
         environ.setdefault(
             OTEL_TRACES_EXPORTER, "azure_monitor_opentelemetry_exporter"
         )
+        environ.setdefault(
+            OTEL_LOGS_EXPORTER, "azure_monitor_opentelemetry_exporter"
+        )
         AzureStatusLogger.log_status(True)
         _logger.info(
             "Azure Monitor OpenTelemetry Distro configured successfully."

azure-monitor-opentelemetry-distro/samples/logging/simple.py

@@ -0,0 +1,30 @@
+# -------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License in the project root for
+# license information.
+# --------------------------------------------------------------------------
+
+from logging import WARN, getLogger
+
+from azure.monitor.opentelemetry.distro import configure_azure_monitor
+from opentelemetry import trace
+
+configure_azure_monitor(
+    connection_string="<your-connection-string>",
+    service_name="foo_service",
+    logging_level=WARN,
+    disable_tracing=True,
+)
+
+logger = getLogger(__name__)
+tracer = trace.get_tracer(__name__)
+
+logger.info("info log")
+logger.warning("warning log")
+logger.error("error log")
+
+with tracer.start_as_current_span("hello"):
+    print("Hello, World!")
+    logger.info("Correlated info log")
+    logger.warning("Correlated warning log")
+    logger.error("Correlated error log")

azure-monitor-opentelemetry-distro/samples/tracing/simple.py

@@ -11,6 +11,7 @@
     connection_string="<your-connection-string>",
     service_name="foo_service",
     tracing_export_interval_millis=15000,
+    disable_logging=True,
 )
 
 tracer = trace.get_tracer(__name__)