APM SSI: agentic onboarding rewrite#38294
Draft
brett0000FF wants to merge 14 commits into
Draft
Conversation
Rename Application Instrumentation to Set Up APM in the nav. Rework the entry page as a task-oriented routing page. Rewrite the Kubernetes SSI page with a clear onboarding flow, verification steps, agent-only diagnostic content, and tighter advanced configuration sections. Add a symptom-first triage section to SSI troubleshooting.
Per AI readability guidelines, page descriptions in frontmatter are critical for retrieval. Adds specific, action-oriented descriptions to the Set Up APM entry page, SSI index page, and SSI troubleshooting page.
Fix broken link to dynamic instrumentation (use canonical path). Fix label vs annotation mismatch in troubleshooting triage. Add build.gradle to troubleshooting grep command. Fix agent-only tab reference to name all three tabs. Add opt-out label check to K8s agent-only diagnostic block. Add shell language tags to grep code blocks. Expand collapse titles to use full Unified Service Tags name. Fix Datadog app vale warning.
Add full install-from-scratch steps (Helm repo, namespace, secret, site/clusterName) to the Helm and Operator tabs so new users don't need to cross-reference other pages. Add outage warnings before pod restart commands. Clarify Alpine/musl support nuance (Ruby requires glibc). Improve agent-only guidance to check existing Agent state before modifying config.
Ask for language before platform in the APM setup routing block so unsupported SSI languages (Go, C++, Rust) bail early. Add a node discovery step before the troubleshooting triage commands so NODE_HOSTNAME is resolved before it is used.
Rewrite Alpine/musl bullet as a constraint ("Ruby: glibc only") to
match the pattern of neighboring bullets. Move "already installed"
shortcut before the full YAML blocks in Helm and Operator tabs so
existing users can skip early. Standardize restart warning text
across all three tabs.
1. Add platform-specific triage sections (Kubernetes, Linux) to troubleshooting — was K8s-only despite page covering all platforms. Added Linux checks: /etc/ld.so.preload, musl/glibc, SELinux/AppArmor. 2. Add dd-java-agent and javaagent to tracer grep commands on K8s and troubleshooting pages. Add note about checking Dockerfiles and JAVA_TOOL_OPTIONS for Java. 3. Fix stale python: "2" in agent-only SDK version defaults — should be python: "3" to match current docs and best-practice examples. 4. Update footnote and further_reading links from old alias paths (/automatic_instrumentation/single-step-apm/) to canonical paths (/single-step-apm/) on SSI index and troubleshooting pages. Preserves aliases in frontmatter for redirects.
Split prerequisites into three clear sections: requirements (bullet list), tracer dependency check (own heading with code block), and compatibility notes (clean bullet list). Removes inconsistent bold- header-paragraph formatting mixed with list items.
The agent-only triage block assumed Kubernetes only. Split into platform-labeled sections: all-platforms pup commands, Kubernetes kubectl diagnostics with signal table, and Linux host diagnostics (ld.so.preload, /proc/maps, libc check, SELinux/AppArmor). Silent failure modes now labeled by platform.
…arding-ia-restructure # Conflicts: # content/en/tracing/trace_collection/single-step-apm/kubernetes.md # content/en/tracing/trace_collection/single-step-apm/troubleshooting.md
… setup, promoted diagnostics
brett0000FF
changed the title
Contributor
brett0000FF
changed the base branch from
brett.blue/apm-onboarding-ia-restructure
to
master
July 17, 2026 21:51
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What does this PR do? What is the motivation?
Reorganizes the APM setup entry point and rewrites the Single Step Instrumentation (SSI) documentation to be crisp, standalone, and easy to follow for both people and agents.
The SSI enable commands are documented directly instead of existing only in the in-app installer. This closes an important gap for non-UI workflows while keeping the wizard as an alternate path.
Key changes:
This PR incorporates and supersedes the information architecture work from #36370 and targets
masterdirectly.Validation
Merge instructions
Merge readiness:
Additional notes