Python: [BREAKING] Observability updates (#2782)

* fixes Python: Add env_file_path parameter to setup_observability() similar to AzureOpenAIChatClient
Fixes #2186

* WIP on updates using configure_azure_monitor

* improved setup and clarity

* fixed root .env.example

* revert changes

* updated files

* updated sample

* updated zero code

* test fixes and fixed links

* fix devui

* removed planning docs

* added enable method and updated readme and samples

* clarified docstring

* add return annotation

* updated naming

* update capatilized version

* updated readme and some fixes

* updated decorator name inline with the rest

* feedback from comments addressed

python/samples/getting_started/observability/.env.example

@@ -1,14 +1,49 @@
-APPLICATIONINSIGHTS_CONNECTION_STRING="..."
-OTLP_ENDPOINT="http://localhost:4317/"
+# Observability Configuration
+# ===========================
+
+# Standard OpenTelemetry environment variables
+# See https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/
+
+# OTLP Endpoint (for Aspire Dashboard, Jaeger, etc.)
+# Default protocol is gRPC (port 4317), HTTP uses port 4318
+OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4317"
+
+# Optional: Override endpoint for specific signals
+# OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="http://localhost:4317"
+# OTEL_EXPORTER_OTLP_METRICS_ENDPOINT="http://localhost:4317"
+# OTEL_EXPORTER_OTLP_LOGS_ENDPOINT="http://localhost:4317"
+
+# Optional: Specify protocol (grpc or http)
+# OTEL_EXPORTER_OTLP_PROTOCOL="grpc"
+
+# Optional: Add headers (e.g., for authentication)
+# OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer token,x-api-key=key"
+
+# Optional: Service identification
+# OTEL_SERVICE_NAME="my-agent-app"
+# OTEL_SERVICE_VERSION="1.0.0"
+# OTEL_RESOURCE_ATTRIBUTES="deployment.environment=dev,host.name=localhost"
+
+# Agent Framework specific settings
+# ==================================
+
+# Enable sensitive data logging (prompts, responses, etc.)
+# WARNING: Only enable in dev/test environments
 ENABLE_SENSITIVE_DATA=true
-# This is not required if you run `setup_observability()` in your code
-ENABLE_OTEL=true
+
+# Optional: Enable console exporters for debugging
+# ENABLE_CONSOLE_EXPORTERS=true
+
+# Optional: Enable observability (automatically enabled if env vars are set or configure_otel_providers() is called)
+# ENABLE_INSTRUMENTATION=true
 
 # OpenAI specific variables
+# ==========================
 OPENAI_API_KEY="..."
 OPENAI_RESPONSES_MODEL_ID="gpt-4o-2024-08-06"
 OPENAI_CHAT_MODEL_ID="gpt-4o-2024-08-06"
 
-# Foundry specific variables
+# Azure AI Foundry specific variables
+# ====================================
 AZURE_AI_PROJECT_ENDPOINT="..."
-AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4o-mini"
+AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4o-mini"