Repository navigation
Retire Observability packages and document OpenTelemetry migration - #330
Nikhil Navakiran (nikhilNava) wants to merge 10 commits into
Conversation
Remove the four retired Observability packages and dedicated tests. Preserve the six maintained packages, add consumer migration and owner retirement guidance, and guard fresh release artifacts against retired content. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 9339e0c8-5126-4e42-b471-9dddfb80d4a8
There was a problem hiding this comment.
🟡 Changes recommended
The release instructions omit running node setVersion.js in write mode before building, causing a fresh release commit to produce placeholder-version tarballs that still pass verification.
1 open issue
What changed in this PR
Retires the four Agent365 Observability packages while preserving the six Notifications, Runtime, and Tooling packages. Application telemetry moves to the external Microsoft OpenTelemetry distribution.
Changes:
- Removes retired implementations, exports, dedicated tests, and exclusive dependencies.
- Adds guarded six-package packaging, tarball inspection, and fresh-artifact CI uploads.
- Updates migration links, release instructions, architecture documentation, and contributor guidance.
| File | Description |
|---|---|
| VERSIONING_QUICKREF.md | Uses guarded packaging command. |
| VERSION_MANAGEMENT.md | Updates packaging and release guidance. |
| tests/TEST_PLAN.md | Marks roadmap historical and removes retired scope. |
| tests/runtime/environment-utils.test.ts | Removes retired authentication-helper tests. |
| tests/RUNNING_TESTS.md | Updates test layout and filtering command. |
| tests/release-packages.test.ts | Adds release artifact safeguards. |
| tests/README.md | Documents maintained test scope. |
| tests/package.json | Removes Observability-only dependencies. |
| tests/observability/internal/PerRequestProcessorOverrides.test.ts | Deletes processor override tests. |
| tests/observability/integration/setup.ts | Deletes integration setup. |
| tests/observability/integration/jest.polyfills.js | Deletes integration polyfill. |
| tests/observability/integration/helpers/span-validators.ts | Deletes span validation helpers. |
| tests/observability/integration/conftest.ts | Deletes integration configuration helpers. |
| tests/observability/integration/.env.example | Deletes integration environment template. |
| tests/observability/extension/openai/OpenAIAgentsTraceInstrumentor.test.ts | Deletes OpenAI instrumentation tests. |
| tests/observability/extension/langchain/LangChainTraceInstrumentor.test.ts | Deletes LangChain instrumentation tests. |
| tests/observability/extension/langchain/LangChainMessageContract.test.ts | Deletes message contract tests. |
| tests/observability/extension/hosting/TurnContextUtils.test.ts | Deletes hosting context tests. |
| tests/observability/extension/hosting/observability-hosting-manager.test.ts | Deletes hosting manager tests. |
| tests/observability/extension/hosting/BaggageBuilderUtils.test.ts | Deletes baggage utility tests. |
| tests/observability/extension/helpers/message-schema-validator.ts | Deletes message validation helpers. |
| tests/observability/core/token-context.test.ts | Deletes token context tests. |
| tests/observability/core/span-links.test.ts | Deletes span-link tests. |
| tests/observability/core/payload-chunking.test.ts | Deletes payload chunking tests. |
| tests/observability/core/observabilityManager.test.ts | Deletes manager lifecycle tests. |
| tests/observability/core/observabilityManager-exporter-options.test.ts | Deletes exporter option tests. |
| tests/observability/core/observabilityBuilder-per-request-auth.test.ts | Deletes per-request authentication tests. |
| tests/observability/core/observabilityBuilder-options.test.ts | Deletes builder option tests. |
| tests/observability/core/observabilityBuilder-configProvider.test.ts | Deletes builder configuration tests. |
| tests/observability-extensions-openai/configuration/OpenAIObservabilityConfiguration.test.ts | Deletes OpenAI configuration tests. |
| tests/jest.config.cjs | Removes retired module mappings. |
| setVersion.js | Limits versioning to explicit workspaces. |
| README.md | Highlights migration and maintained SDK scope. |
| pnpm-workspace.yaml | Lists six packages and prunes catalog dependencies. |
| packPackages.js | Adds guarded packing, inspection, and hash receipts. |
| packages/agents-a365-tooling/package.json | Delegates packaging to root guard. |
| packages/agents-a365-tooling-extensions-openai/package.json | Delegates packaging to root guard. |
| packages/agents-a365-tooling-extensions-langchain/package.json | Delegates packaging to root guard. |
| packages/agents-a365-tooling-extensions-claude/package.json | Delegates packaging to root guard. |
| packages/agents-a365-runtime/src/environment-utils.ts | Removes Observability authentication APIs. |
| packages/agents-a365-runtime/package.json | Delegates packaging to root guard. |
| packages/agents-a365-runtime/docs/design.md | Documents removed authentication APIs. |
| packages/agents-a365-observability/tsconfig.json | Deletes retired compiler configuration. |
| packages/agents-a365-observability/tsconfig.esm.json | Deletes retired ESM configuration. |
| packages/agents-a365-observability/tsconfig.cjs.json | Deletes retired CJS configuration. |
| packages/agents-a365-observability/src/tracing/util.ts | Deletes tracing utilities. |
| packages/agents-a365-observability/src/tracing/scopes/OutputScope.ts | Deletes output tracing scope. |
| packages/agents-a365-observability/src/tracing/scopes/InvokeAgentScope.ts | Deletes agent invocation scope. |
| packages/agents-a365-observability/src/tracing/scopes/ExecuteToolScope.ts | Deletes tool execution scope. |
| packages/agents-a365-observability/src/tracing/processors/util.ts | Deletes processor attribute lists. |
| packages/agents-a365-observability/src/tracing/processors/SpanProcessor.ts | Deletes baggage span processor. |
| packages/agents-a365-observability/src/tracing/message-utils.ts | Deletes telemetry message utilities. |
| packages/agents-a365-observability/src/tracing/exporter/ExporterEventNames.ts | Deletes exporter event definitions. |
| packages/agents-a365-observability/src/tracing/exporter/Agent365ExporterOptions.ts | Deletes exporter configuration contract. |
| packages/agents-a365-observability/src/tracing/context/trace-context-propagation.ts | Deletes trace propagation helpers. |
| packages/agents-a365-observability/src/tracing/context/token-context.ts | Deletes export token context helpers. |
| packages/agents-a365-observability/src/tracing/context/parent-span-context.ts | Deletes parent-span context helpers. |
| packages/agents-a365-observability/src/ObservabilityManager.ts | Deletes Observability manager. |
| packages/agents-a365-observability/src/internal/PerRequestProcessorInternalOverrides.ts | Deletes internal processor overrides. |
| packages/agents-a365-observability/src/index.ts | Removes core public exports. |
| packages/agents-a365-observability/src/configuration/PerRequestSpanProcessorConfigurationOptions.ts | Deletes processor configuration options. |
| packages/agents-a365-observability/src/configuration/PerRequestSpanProcessorConfiguration.ts | Deletes processor configuration implementation. |
| packages/agents-a365-observability/src/configuration/ObservabilityConfigurationOptions.ts | Deletes Observability configuration options. |
| packages/agents-a365-observability/src/configuration/ObservabilityConfiguration.ts | Deletes Observability configuration implementation. |
| packages/agents-a365-observability/src/configuration/index.ts | Removes configuration exports and providers. |
| packages/agents-a365-observability/README.md | Deletes retired package usage guide. |
| packages/agents-a365-observability/package.json | Removes core package manifest. |
| packages/agents-a365-observability/jest.config.js | Deletes retired test configuration. |
| packages/agents-a365-observability/.gitignore | Removes generated-version ignore rule. |
| packages/agents-a365-observability-hosting/tsconfig.json | Deletes hosting compiler configuration. |
| packages/agents-a365-observability-hosting/tsconfig.esm.json | Deletes hosting ESM configuration. |
| packages/agents-a365-observability-hosting/tsconfig.cjs.json | Deletes hosting CJS configuration. |
| packages/agents-a365-observability-hosting/src/utils/TurnContextUtils.ts | Deletes telemetry context extraction. |
| packages/agents-a365-observability-hosting/src/utils/BaggageBuilderUtils.ts | Deletes hosting baggage utilities. |
| packages/agents-a365-observability-hosting/src/middleware/OutputLoggingMiddleware.ts | Deletes output tracing middleware. |
| packages/agents-a365-observability-hosting/src/middleware/ObservabilityHostingManager.ts | Deletes middleware registration manager. |
| packages/agents-a365-observability-hosting/src/middleware/BaggageMiddleware.ts | Deletes baggage middleware. |
| packages/agents-a365-observability-hosting/src/index.ts | Removes hosting public exports. |
| packages/agents-a365-observability-hosting/package.json | Removes hosting package manifest. |
| packages/agents-a365-observability-extensions-openai/tsconfig.json | Deletes OpenAI compiler configuration. |
| packages/agents-a365-observability-extensions-openai/tsconfig.esm.json | Deletes OpenAI ESM configuration. |
| packages/agents-a365-observability-extensions-openai/tsconfig.cjs.json | Deletes OpenAI CJS configuration. |
| packages/agents-a365-observability-extensions-openai/src/OpenAIAgentsTraceInstrumentor.ts | Deletes OpenAI tracing instrumentor. |
| packages/agents-a365-observability-extensions-openai/src/index.ts | Removes OpenAI public exports. |
| packages/agents-a365-observability-extensions-openai/src/Constants.ts | Deletes tracing constants. |
| packages/agents-a365-observability-extensions-openai/src/configuration/OpenAIObservabilityConfigurationOptions.ts | Deletes OpenAI configuration options. |
| packages/agents-a365-observability-extensions-openai/src/configuration/OpenAIObservabilityConfiguration.ts | Deletes OpenAI configuration implementation. |
| packages/agents-a365-observability-extensions-openai/src/configuration/index.ts | Removes OpenAI configuration provider. |
| packages/agents-a365-observability-extensions-openai/README.md | Deletes retired OpenAI usage guide. |
| packages/agents-a365-observability-extensions-openai/package.json | Removes OpenAI Observability manifest. |
| packages/agents-a365-observability-extensions-openai/jest.config.json | Deletes OpenAI test configuration. |
| packages/agents-a365-observability-extensions-langchain/tsconfig.json | Deletes LangChain compiler configuration. |
| packages/agents-a365-observability-extensions-langchain/tsconfig.esm.json | Deletes LangChain ESM configuration. |
| packages/agents-a365-observability-extensions-langchain/tsconfig.cjs.json | Deletes LangChain CJS configuration. |
| packages/agents-a365-observability-extensions-langchain/src/tracer.ts | Deletes LangChain tracer. |
| packages/agents-a365-observability-extensions-langchain/src/index.ts | Removes LangChain public exports. |
| packages/agents-a365-observability-extensions-langchain/README.md | Deletes retired LangChain usage guide. |
| packages/agents-a365-observability-extensions-langchain/package.json | Removes LangChain Observability manifest. |
| packages/agents-a365-observability-extensions-langchain/jest.config.json | Deletes LangChain test configuration. |
| packages/agents-a365-notifications/package.json | Delegates packaging to root guard. |
| package.json | Updates workspace scripts and package selection. |
| jest.integration.config.cjs | Deletes Observability integration configuration. |
| HOW_TO_RELEASE.md | Documents receipt-based release packaging. |
| generate-package-dependencies.js | Removes retired diagram categories. |
| eslint.config.mjs | Updates configuration guidance message. |
| docs/prd-configuration-provider.md | Labels retired proposals as historical. |
| DEPENDENCIES.md | Removes retired dependency nodes. |
| .github/workflows/ci.yml | Verifies fresh artifacts; removes retired integration job. |
| .github/CODEOWNERS | Assigns ownership of migration documentation. |
| .claude/agents/test-coverage-reviewer.md | Removes retired test layout examples. |
| .claude/agents/task-implementer.md | Updates implementation and telemetry guidance. |
| .claude/agents/prd-writer.md | Updates architecture and planning examples. |
| .claude/agents/prd-task-generator.md | Replaces retired implementation examples. |
| .claude/agents/pr-comment-resolver.md | Updates example scope and wording. |
| .claude/agents/code-reviewer.md | Replaces retired patterns with configuration guidance. |
| .claude/agents/code-review-manager.md | Updates example review file paths. |
| .claude/agents/architecture-reviewer.md | Updates dependency flow and architecture guidance. |
Review effort: Balanced
Krishnadheeraj (DheerajPannala)
left a comment
Krishnadheeraj (DheerajPannala)
left a comment
There was a problem hiding this comment.
The retirement is a coherent cut: one explicit six-package boundary, a readable packaging guard, and a single migration guide instead of leftover observability entry points. The workspace, CI, and pack path agree on that boundary.
Three minor comments inline.
There was a problem hiding this comment.
🔵 Needs a closer look
The release instructions omit applying the calculated version before building and packing, allowing placeholder-versioned tarballs to pass verification and be published instead of the tagged release version.
1 open issue
Review effort: Balanced
Enforce pnpm packaging, validate resolved dependency specifications, and terminate tar options. Clarify release version stamping and unchanged app-only authentication scope. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 9339e0c8-5126-4e42-b471-9dddfb80d4a8
There was a problem hiding this comment.
🔵 Needs a closer look
Release owners must confirm npm deprecation and independent allowlists for external and old-branch publishing paths because repository safeguards cannot enforce these controls for the four retired packages.
No open issues 🎉
1 resolved since last review
Review effort: Balanced
Krishnadheeraj (DheerajPannala)
left a comment
Krishnadheeraj (DheerajPannala)
left a comment
There was a problem hiding this comment.
The retirement approach is sound: one explicit six-package boundary, a guarded pack path, and a migration guide that treats telemetry as an application change rather than a leftover SDK dependency. The packaging checks are careful and match that allowlist.
One minor comment inline.
Since my last review:
- Fixed: Terminate tar options before passing archive member names (
packPackages.js) - Fixed: Migration guide forbids the app-only scope it then cites as the distro default (
docs/observability-migration.md) - Fixed: Reject non-pnpm callers before using npm_execpath (
packPackages.js)
Continue packaging from the installed and stamped Step 6 checkout so frozen lockfile validation runs only before manifests are rewritten. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 9339e0c8-5126-4e42-b471-9dddfb80d4a8
|
Please resolve the merge conflicts |
Rick Brighenti (rbrighenti)
left a comment
Rick Brighenti (rbrighenti)
left a comment
There was a problem hiding this comment.
Ran this locally at 283bf79: frozen install, lint, build, typecheck, tests (605 passing) and the guarded pnpm run pack + --verify all pass, and I found no leftover references to the retired packages. A few migration-guide accuracy gaps vs. the upstream distro docs and one packaging foot-gun inline. Also note the branch currently has merge conflicts with main.
Preserve upstream dependency security updates without restoring retired Observability packages or catalog entries. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 9339e0c8-5126-4e42-b471-9dddfb80d4a8
|
Merged latest main and resolved the conflicts in 08efab4, preserving its dependency security updates. |
There was a problem hiding this comment.
🔵 Needs a closer look
Package-owner confirmation is required for the breaking public API retirement and publishing restrictions, since repository checks cannot verify that old-branch publishers and cached release artifacts have been disabled.
No open issues 🎉
Review effort: Balanced
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 9339e0c8-5126-4e42-b471-9dddfb80d4a8
There was a problem hiding this comment.
🔵 Needs a closer look
Retiring four published packages and removing Runtime exports requires package-owner validation of downstream migrations and external publishing controls beyond this repository review.
No open issues 🎉
Review effort: Balanced
Krishnadheeraj (DheerajPannala)
left a comment
Krishnadheeraj (DheerajPannala)
left a comment
There was a problem hiding this comment.
The retirement is a clean boundary: six explicit packages, a guarded pack path, and a migration guide that treats telemetry as an application change rather than a leftover SDK dependency. The packaging checks match that allowlist.
One thing to address before this merges; details inline.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 9339e0c8-5126-4e42-b471-9dddfb80d4a8
Krishnadheeraj (DheerajPannala)
left a comment
Krishnadheeraj (DheerajPannala)
left a comment
There was a problem hiding this comment.
The retirement is a coherent cut: one explicit six-package boundary, a packaging guard that matches it, and migration notes that treat telemetry as an application change. The workspace, CI pack path, and remaining public surface agree with that boundary.
Two minor comments inline.
Since my last review:
- Fixed: Recursive pack regression test fails when no package defines pack (
tests/release-packages.test.ts)
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 9339e0c8-5126-4e42-b471-9dddfb80d4a8
|
Thanks for addressing all the review feedback — everything else looks good to me. One remaining ask: since this PR removes public APIs from Runtime ( |
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 9339e0c8-5126-4e42-b471-9dddfb80d4a8
|
Bumped version.json to 3.0.0-preview.{height} in edc0528. Verified version generation for all six maintained packages. |
Krishnadheeraj (DheerajPannala)
left a comment
Krishnadheeraj (DheerajPannala)
left a comment
There was a problem hiding this comment.
The retirement is a coherent package-boundary cut: the observability implementations are gone, the six maintained packages are explicit, and the major version move matches a breaking removal. The packaging guard and migration write-up are careful and consistent with that boundary.
One minor comment below.
Outside the changed lines:
- Minor: Published changelog still tops out at 2.0.0 after the 3.0.0 break (
CHANGELOG.md:8). version.json now targets 3.0.0-preview, and this change removes four published packages plus Runtime getObservabilityAuthenticationScope() and PROD_OBSERVABILITY_SCOPE. CHANGELOG.md still opens on [2.0.0] and describes those retired packages as the latest breaking change. The pack path copies that file into every tarball before pnpm pack, and each package files list ships it. HOW_TO_RELEASE updates the changelog only after publish, so those notes never enter the artifact. Someone installing 3.0.0 therefore gets a changelog that still treats the observability packages as current.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 9339e0c8-5126-4e42-b471-9dddfb80d4a8
|
Added 3.0.0 retirement/API-removal notes and moved changelog updates before release tagging in 2713ee0. Verified the updated changelog in all six tarballs; historical entries are unchanged. |
There was a problem hiding this comment.
🔵 Needs a closer look
Retiring four published packages and removing Runtime exports requires package-owner confirmation of downstream migration readiness and external or old-branch publishing restrictions that cannot be verified from this repository.
No open issues 🎉
Review effort: Balanced
Rick Brighenti (rbrighenti)
left a comment
Rick Brighenti (rbrighenti)
left a comment
There was a problem hiding this comment.
LGTM. Major version is now 3.0.0-preview, the 3.0.0 CHANGELOG entry accurately documents the retired packages and removed Runtime exports, and all earlier review feedback is addressed. CI is green on Node 18/20.
Summary
@microsoft/agents-a365-observability*packages: core, hosting, OpenAI extension, and LangChain extension. Remove their implementations, public exports, dedicated tests, and exclusive dependencies.docs/observability-migration.md, directing consuming applications to@microsoft/opentelemetryand the official distro/migration documentation. Cover verified APIs and Node requirements, CJS/ESM preload ordering, authentication, context propagation, framework instrumentation, shutdown, durability, and unsupported assumptions.Breaking API removal
getObservabilityAuthenticationScope()andPROD_OBSERVABILITY_SCOPE; application telemetry authentication must be configured through the distro.PROD_OBSERVABILITY_CLUSTER_CATEGORYcompatibility alias. Compatible upstream namespaces/API names are not themselves retired dependencies.Validation
pnpm install --frozen-lockfile --ignore-scriptspnpm build(all six maintained packages, CJS and ESM)pnpm test --runInBand: 28 suites / 595 tests passed, including nine release-guard casespnpm lintandpnpm typechecknode setVersion.js --dry-runpnpm run pack artifacts\retirement-validation, followed by independentnode packPackages.js --verify artifacts\retirement-validation: exactly six inspected tarballs; no retired packages, bundled implementations, or dependencies. Validation artifacts retain placeholder versions and are not release-versioned output.Package-owner / external pipeline actions
Repository safeguards do not revoke old-branch pipelines, credentials, or previously cached artifacts. The migration guide includes an owner-operated checklist and ready-to-paste npm deprecation commands covering every version of all four packages. Owners must publish the guide, deprecate the packages, and independently restrict external publishing paths and caches. Deprecation warns consumers; it does not replace dependencies or prevent installation. Do not unpublish.
No npm publishing, deprecation, or registry-setting changes were performed. Unrelated local Rust work and generated validation artifacts are excluded.