2 Commits

• [BREAKING] Python: Enable instrumentation by default (#5865)

  * Enable instrumentation by default
  
  * Update samples
  
  * Optimization when span is not recording
  
  * Address Copilot comments
  
  * Revert uv.lock
  
  * Add warning
  
  * Formatting
  
  * Fix mypy
  
  * Add disable_instrumentation() with sticky user-intent semantics
  
  Add a public disable_instrumentation() entry point so users can explicitly opt
  out of Agent Framework telemetry, with a sticky-disable flag that makes the
  user's intent "leading" — no framework code path (foundry's
  configure_azure_monitor, configure_otel_providers, enable_instrumentation,
  enable_sensitive_telemetry, or direct OBSERVABILITY_SETTINGS.enable_*
  writes) can re-enable instrumentation until the user explicitly clears the
  disable with enable_instrumentation(force=True) /
  enable_sensitive_telemetry(force=True).
  
  Also addresses the two remaining unresolved review threads on the PR:
  1. test_observability_settings_defaults_instrumentation_true pins the new
     "ENABLE_INSTRUMENTATION defaults to True when env unset" behavior.
  2. test_enable_instrumentation_reads_env_sensitive_data restores coverage
     for the post-import load_dotenv() fallback path.
  
  Implementation:
  - ObservabilitySettings.enable_instrumentation / enable_sensitive_data become
    properties backed by _enable_*. While _user_disabled is True, the getters
    return False and the setters drop True writes (defense in depth so third-
    party writes can't subvert the disable).
  - Public is_user_disabled read-only property lets integrations (e.g. foundry's
    configure_azure_monitor) cheaply check the disable state without poking at
    privates.
  - enable_instrumentation() and enable_sensitive_telemetry() short-circuit with
    an info log when disabled; gain a force=True kwarg that clears the disable.
  - configure_otel_providers() still creates providers / exporters / views so a
    later force-enable can use them, but logs an info message when called while
    disabled.
  - Foundry's FoundryChatClient.configure_azure_monitor and
    FoundryAgent.configure_azure_monitor early-return when the user has
    disabled, so Azure Monitor's global providers aren't installed unnecessarily.
  
  Tests: 11 new tests covering default-on, env re-read at call time, sticky
  behavior against each re-enable surface (enable_instrumentation,
  enable_sensitive_telemetry, configure_otel_providers, direct attribute
  writes), force=True override, re-arming the disable, and the __all__ export.
  
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
  
  * docs: document disable_instrumentation() and force=True paths
  
  Add a "Disabling instrumentation" section to the observability sample README
  that walks through:
  
  - The distinction between the ENABLE_INSTRUMENTATION env var (initial,
    non-sticky) and disable_instrumentation() (process-wide, sticky).
  - Why the sticky semantics matter: framework integrations like
    FoundryChatClient.configure_azure_monitor() can call
    enable_instrumentation() as part of their setup, and the user's opt-out
    needs to win.
  - All five surfaces guarded by the sticky disable (property reads, public
    enable functions, configure_otel_providers, direct attribute writes,
    is_user_disabled-aware integrations).
  - The force=True escape hatch on both enable_instrumentation() and
    enable_sensitive_telemetry().
  - How third-party integrations should consult OBSERVABILITY_SETTINGS.is_user_disabled.
  - The limits of the disable (does not tear down existing providers /
    in-flight spans / third-party instrumentation, does not persist across
    processes).
  
  Cross-links the new section from the ENABLE_INSTRUMENTATION row in the env
  vars table.
  
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
  
  * docs: soften disable_instrumentation() overclaim about telemetry guarantees
  
  Replace 'no telemetry will be emitted no matter what' (which is too strong,
  since callers can still pass force=True or mutate private attributes) with
  language framing the disable as a user-intent contract that library and
  framework code is expected to honor: the framework actively short-circuits
  the public enable paths, force=True and private-attribute writes are
  acknowledged as out-of-contract escape hatches that integrations should
  not use on the user's behalf.
  
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
  
  * docs: correct observability Dependencies section
  
  - opentelemetry-sdk is no longer a hard dependency; it is lazily imported by
    create_resource(), create_metric_views(), and configure_otel_providers()
    with a clear ImportError when missing. Day-to-day instrumentation works
    with opentelemetry-api alone provided some other component configures the
    global OpenTelemetry providers (Azure Monitor, an APM agent, application
    bootstrap, etc.).
  - opentelemetry-semantic-conventions-ai is no longer used anywhere in the
    source; remove it from the listed dependencies.
  
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
  
  * docs: replace stale observability migration guide with current PR's only relevant migration
  
  The old guide documented the move away from setup_observability(otlp_endpoint=...)
  which was an earlier-release API change unrelated to this PR and stale enough that
  it's more confusing than helpful at this point. Replace it with a short note on the
  single migration this PR introduces: callers of
  enable_instrumentation(enable_sensitive_data=True) should switch to
  enable_sensitive_telemetry(). Cross-link to the Disabling instrumentation section
  for the rare 'force on without enabling sensitive data' use case where
  enable_instrumentation() still applies.
  
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
  
  ---------
  
  Co-authored-by: Eduard van Valkenburg <eavanvalkenburg@users.noreply.github.com>
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

  Tao Chen · 2026-05-20 11:52:08 +00:00
  72a6157c6a
• Python: restructure: Python samples into progressive 01-05 layout (#3862)

  * restructure: Python samples into progressive 01-05 layout
  
  - 01-get-started/: 6 numbered steps (hello agent → hosting)
  - 02-agents/: all agent concept samples (tools, middleware, providers, etc.)
  - 03-workflows/: ALL existing workflow samples preserved as-is
  - 04-hosting/: azure-functions, durabletask, a2a
  - 05-end-to-end/: demos, evaluation, hosted agents
  - Old files moved to _to_delete/ for review
  - Added AGENTS.md with structure documentation
  - autogen-migration/ and semantic-kernel-migration/ preserved at root
  
  * fix: switch to AzureOpenAI Foundry, fix CI failures
  
  - Switch all 01-get-started samples to AzureOpenAIResponsesClient with
    Azure AI Foundry project endpoint (AZURE_AI_PROJECT_ENDPOINT +
    AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME + AzureCliCredential)
  - Add _to_delete/ and 05-end-to-end/ to pyrightconfig.samples.json excludes
  - Fix test paths in packages/ that referenced old getting_started/ dirs:
    durabletask conftest + streaming test, azurefunctions conftest,
    devui conftest + capture_messages + openai_sdk_integration
  - Fix workflow_as_agent_human_in_the_loop.py import (sibling import)
  - Update hosting READMEs and tool comment paths
  - Replace root README.md with new structure overview
  - Update AGENTS.md to document Azure OpenAI Foundry as default provider
  
  * cleanup: remove _to_delete folder, copy resource files to active dirs
  
  All files in _to_delete/ were either:
  - Exact duplicates of files in the new structure (240 files)
  - Same file with only comment path updates (100 files)
  - One import-fix diff (workflow_as_agent_human_in_the_loop.py)
  - One superseded minimal_sample.py
  
  Resource files (sample.pdf, countries.json, employees.pdf, weather.json)
  copied to 02-agents/sample_assets/ and 02-agents/resources/ since active
  samples reference them.
  
  * fix: address PR review comments, centralize resources, remove root duplicates
  
  - Fix type annotation in 04_memory.py (string union -> proper types)
  - Fix old sample paths in observability files
  - Fix grammar/spelling in observability samples
  - Move sample_assets/ and resources/ to shared/ folder
  - Remove 8 duplicate observability files from 02-agents root
  - Update resource path references in multimodal_input and provider samples
  
  * fix: update broken links from old getting_started paths to new structure
  
  - Update relative paths in READMEs: getting_started/ → 01-get-started/,
    02-agents/, 03-workflows/, 04-hosting/, 05-end-to-end/
  - Fix absolute GitHub URLs in package READMEs
  - Fix broken link in ollama package README
  
  * fix: convert absolute GitHub URLs to relative paths for link checker
  
  Absolute URLs to python/samples/ on main branch 404 until PR merges.
  Converted to relative paths that linkspector can verify locally.
  
  * fix: update link for handoff sample moved to orchestrations/
  
  * fix: update chatkit-integration README path from demos/ to 05-end-to-end/
  
  * fix: update broken links in orchestrations README to match flat directory structure

  Eduard van Valkenburg · 2026-02-12 17:36:36 +00:00
  a2856d3b92