APM onboarding: Set Up APM + K8s SSI rewrite w/ Agent Execution Context#36370
Draft
brett0000FF wants to merge 10 commits into
Draft
APM onboarding: Set Up APM + K8s SSI rewrite w/ Agent Execution Context#36370brett0000FF wants to merge 10 commits into
brett0000FF wants to merge 10 commits into
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.
Contributor
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.
brett0000FF
changed the title
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
1 task
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?
Summary: This PR is an experiment showing how docs and agent skills can work together, with docs as the single source of truth for domain knowledge. It restructures the APM onboarding flow, rewrites the K8s SSI page, and incorporates the most valuable content from the dd-apm skills directly into our docs. The
agent-onlyshortcode handles content that helps agents but would clutter the page for humans.The ICP squad's skills contain great domain knowledge (silent failure modes, verification steps, diagnostic commands, troubleshooting flows) that fills real gaps in our docs. This PR brings that knowledge into the docs pages where it can be reviewed, versioned, and kept current alongside the product content.
Changes follow the Writing Guidelines for AI Readability.
Changes
1. Nav rename: "Application Instrumentation" → "Set Up APM" (
config/_default/menus/main.en.yaml)2. Entry page rework (
content/en/tracing/trace_collection/_index.md)agent-onlyshortcode with routing context (platform detection, language compatibility)3. Kubernetes SSI page rewrite (
content/en/tracing/trace_collection/single-step-apm/kubernetes.md)Structural improvements:
descriptionto frontmatter for AI retrieval (guideline 1.4)-javaagentadded to tracer dependency grep (also checks Dockerfiles,JAVA_TOOL_OPTIONS)Content incorporated from skills:
k8s-ssi/enable-ssik8s-ssi/enable-ssik8s-ssi/troubleshoot-ssik8s-ssi/troubleshoot-ssik8s-ssi/verify-ssik8s-ssi/verify-ssik8s-ssi/troubleshoot-ssik8s-ssi/enable-ssik8s-ssi/troubleshoot-ssiNot incorporated because it's agent behavior instructions (how to interact with users, when to execute commands, how to format output), not Datadog product documentation:
### Claude runs)4. Troubleshooting triage section (
content/en/tracing/trace_collection/single-step-apm/troubleshooting.md)agent-onlyshortcode with platform-labeled diagnostics: all-platforms pup commands, Kubernetes kubectl triage with signal table, Linux host checks5. Page descriptions and link cleanup
descriptionfrontmatter to all pages in the onboarding pathfurther_readinglinks to canonical paths (preserving aliases for redirects)How agent-only shortcodes are used
The
agent-onlyshortcode renders content hidden from human readers (display: none) but available to AI agents parsing the page source. Each block has a clear reason for being agent-only rather than human-visible:Why a single source of truth matters
While reviewing the skills content, we found that the skills repo recommended
python: "2"as the default SDK version, while the live docs and best-practice examples usepython: "3". Maintaining domain knowledge in two places creates drift that undermines the agent's accuracy. By incorporating the domain knowledge directly into docs pages, it stays current through the normal review process, and every agent consuming the docs benefits automatically.Merge instructions
Merge readiness:
Additional notes
This is an experiment for the ICP squad meeting.