Skip to content

feat: telemetry for removed v2 interface imports (stacked on #6004)#6006

Open
jam-jee wants to merge 2 commits into
aws:masterfrom
jam-jee:feat/v3-removed-interface-telemetry
Open

feat: telemetry for removed v2 interface imports (stacked on #6004)#6006
jam-jee wants to merge 2 commits into
aws:masterfrom
jam-jee:feat/v3-removed-interface-telemetry

Conversation

@jam-jee

@jam-jee jam-jee commented Jul 9, 2026

Copy link
Copy Markdown
Collaborator

Issue #, if available: N/A

⚠️ Stacked PR. This is based on #6004 (actionable guidance for removed v2 interfaces), not directly on master. The base branch is jam-jee:feat/v3-removed-module-guidance, so this PR's diff shows only the telemetry delta. Merge #6004 first, then this will be retargeted to master. Telemetry has nothing to instrument without the guidance code, hence the stack.

Description of changes:

Adds usage telemetry for the removed-v2-interface imports introduced in #6004 — so we can measure how often each removed interface (sagemaker.estimator, etc.) is still being imported in v3 and prioritize migration support.

  • New Feature.DEPRECATED_V2_INTERFACE (code 21); the specific removed module name travels in x-extra, so one feature code covers all removed interfaces and you slice by module.
  • Removed imports have no sagemaker_session, so a session-less emit resolves account id + region best-effort and sends the same field to the same endpoint as the existing session-based emitter (no new data category — this is the same account-id field already collected on normal operations).
  • Strictly best-effort: hard time-bounded via a daemon worker (a slow/hung STS/S3 call can never delay the ModuleNotFoundError), once per module per process, and never raises.
  • Opt-out honors the standard TelemetryOptOut SDK-defaults config (loaded session-lessly via load_sagemaker_config()), with SAGEMAKER_DEPRECATION_TELEMETRY_OPT_OUT as an additional env-var fallback.
  • Wired into raise_removed_in_v3 and the fallback finder via a lazily-imported, fully-guarded hook.

Testing done:

  • Extends tests/unit/test_removed_v2_modules.py (+8 telemetry tests, 44 total, all pass): dedup, opt-out via config and env var, time-bounding under a simulated 5s hang, never-raises, account fallback to NotAvailable, and the end-to-end import→hook path.
  • Verified end-to-end: a simulated 10s STS hang still lets the import raise in ~1.5s; a real TelemetryOptOut: true config file opts the emit out.
  • black + flake8 (repo tox.ini) clean.

Merge Checklist

General

  • I have read the CONTRIBUTING doc
  • I certify that the changes I am introducing will be backward compatible, and I have discussed concerns about this, if any, with the Python SDK team
    • Note for reviewers: account-id resolution happens on the import path (session-less). It is consistent with the existing telemetry's data collection, opt-out is honored, and it is hard-timeout-bounded. Data-quality caveat: account id will be NotAvailable in credential-less import environments.
  • I used the commit message format described in CONTRIBUTING
  • I have passed the region in to all S3 and STS clients that I've initialized as part of this change. (STS client uses tight timeouts; region resolved from the boto session, default us-west-2.)
  • I have updated any necessary documentation

Tests

  • I have added tests that prove my feature works
  • I have added unit tests as appropriate
  • I have checked that my tests are not configured for a specific region or account
  • I have used unique_name_from_base for integ resource names (N/A — unit tests only)
  • If adding any dependency in requirements.txt files, I have spell checked and ensured they exist in PyPi (N/A — botocore.config already a transitive dep)

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

jam-jee added 2 commits July 8, 2026 20:42
In v3 the v2 top-level modules (sagemaker.estimator, sagemaker.model, ...)
were removed, so importing them fails with a bare
"ModuleNotFoundError: No module named 'sagemaker.estimator'" that gives the
caller no path forward. This adds an actionable migration experience.

- raise_removed_in_v3() helper in sagemaker.core.deprecations: emits a
  DeprecationWarning and raises a ModuleNotFoundError naming the v3
  replacement (and the exact import where the migration guide publishes
  one), plus the migration-guide link.
- 12 curated "tombstone" modules under sagemaker/ for the high-traffic
  removed interfaces (estimator, model, predictor, base_predictor,
  predictor_async, transformer, tuner, processing, pipeline,
  multidatamodel, automl, algorithm). These ship with sagemaker-core.
- A fallback meta-path finder (_RemovedV2ModuleFinder) registered from
  sagemaker.core.__init__ as a last resort: any other removed
  sagemaker.<name> gets a generic "not available in v3, see migration
  guide" message instead of a bare error. Appended to sys.meta_path so it
  never shadows real v3 packages or the tombstones, with a
  _KNOWN_V3_TOPLEVEL guard protecting real packages
  (core/train/serve/mlops/lineage/ai_registry).

Adds tests/unit/test_removed_v2_modules.py (36 tests) covering tombstone
messages and the fallback finder (registration, ordering, non-shadowing of
real packages, pass-through of non-sagemaker and nested names).
Track how often removed v2 interfaces are imported in v3, building on the
actionable-guidance change (raise_removed_in_v3 + the fallback finder).

- New Feature.DEPRECATED_V2_INTERFACE (code 21); the specific removed
  module name travels in x-extra so one feature code covers all of them.
- Removed imports have no sagemaker_session, so a session-less emit
  resolves account id + region best-effort and sends the same field to the
  same endpoint as the existing session-based emitter (no new data
  category).
- Strictly best-effort: hard time-bounded via a daemon worker so it can
  never delay the import, once-per-module-per-process, and never raises.
- Opt-out honors the standard TelemetryOptOut SDK-defaults config (loaded
  session-lessly), with SAGEMAKER_DEPRECATION_TELEMETRY_OPT_OUT as an
  additional env-var fallback.
- Wires the emit into raise_removed_in_v3 and the fallback finder via a
  lazily-imported, fully-guarded hook.

Extends tests/unit/test_removed_v2_modules.py (+8 tests, 44 total) covering
dedup, opt-out via config and env var, time-bounding under a simulated
hang, never-raises, account fallback, and the end-to-end import hook.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant