[APM Basic] Integrate APM Basic docs into existing APM sections by domalessi · Pull Request #35777 · DataDog/documentation

domalessi · 2026-04-06T20:47:24Z

What does this PR do? What is the motivation?

Universal Service Monitoring (USM) was rebranded to APM Basic with a new pricing structure. This PR migrates USM docs to APM Basic and integrates the content into the existing APM doc structure.

Editorial review guidance

Most content in this PR is moved or minimally edited, not net new. Focus review effort accordingly.

Needs full editorial review:

content/en/tracing/apm_basic/_index.md — New overview page, written from scratch. Covers what APM Basic monitors, how eBPF works, when to use vs. full APM, automatic service tagging, and exploring services.

Light review (moved content with targeted edits):

content/en/tracing/apm_basic/setup.md — Moved from /universal_service_monitoring/setup/. Only edits: terminology updated from "USM" to "APM Basic" and operation names updated. Structure and instructions are unchanged from the original USM page.
content/en/tracing/apm_basic/metrics.md — Moved almost verbatim from the USM metrics guide. Only edits: metric name references updated. No new instructions; no structural changes.

Spot-check only (minor additions to existing pages):

content/en/account_management/billing/apm_tracing_profiler.md — One new introductory sentence + one new table row for the APM Basic tier.
content/en/getting_started/tracing/_index.md — One new paragraph added at the end of the page.
content/en/tracing/_index.md — One new row added to the use cases table.
content/en/tracing/metrics/_index.md — One new cross-reference sentence.
content/en/tracing/services/services_map.md — One updated sentence mentioning APM Basic.

Please also spot-check redirects for the old USM pages!

No review needed:

config/_default/menus/main.en.yaml — Nav YAML only; no prose.
content/en/universal_service_monitoring/ files — Deleted pages.
content/en/tracing/glossary/_index.md — Trailing newline fix only; no content change.

Context for reviewers

Framing throughout: APM Basic is written as a supplement to full APM, not a parallel entry point. SSI leads everywhere; APM Basic is the aside.
Nav position (weight 14.5, after Error Tracking, before Guides): Intentional. The nav reads: concepts → instrumentation options → APM capabilities → APM Basic → guides → troubleshooting. APM Basic comes after the main capabilities so SSI stays the primary path and APM Basic reads as supplementary.

Merge instructions

Merge readiness:

Ready for merge

Additional notes

Server-side 301 redirects should be coordinated with the web team as belt-and-suspenders alongside the Hugo aliases.

Add templated pages for the new APM Basic section under /tracing/apm_basic/. This is a structural proposal for review — most pages contain TODO comments marking where content will be migrated from the existing USM docs. Pages added: - /tracing/apm_basic/_index.md (overview, partially written) - /tracing/apm_basic/setup.md (template with migration instructions) - /tracing/apm_basic/guide/_index.md (guide index) - /tracing/apm_basic/guide/using_apm_basic_metrics.md (template) Nav entry added under APM at weight 1.5 (between glossary and instrumentation). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

github-actions · 2026-04-06T20:52:06Z

Preview links (active after the `build_preview` check completes)

New or renamed files

https://docs-staging.datadoghq.com/domalessi/apm-basic-docs/tracing/apm_basic/

Removed or renamed files (these should redirect)

Renamed files

Modified Files

- Overview page: expanded eBPF explanation, billing callout with auto-upgrade note, blog posts in further reading, cleaned up TODOs - Setup page: fully migrated all platform tabs from USM setup (Helm, Operator, K8s, Docker, ECS, Windows IIS/non-IIS, Chef, Puppet, Ansible), service name detection, path exclusion rules - Metrics guide: fully migrated from USM guide with APM Basic terminology, metric tables, syntax comparison, monitor/SLO/ dashboard workflows - Billing page: added APM Basic tier description and auto-upgrade billing rule, updated USM reference to point to APM Basic - Glossary: added APM Basic entry with operation names and SSI note - APM landing page: added use cases table row for APM Basic - Getting Started: added APM Basic section near bottom - Service Map: added mention of APM Basic discovered services Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Billing page: replace paragraph with table row (with TODO for PM to confirm pricing details), keep intro concise - Overview page: trim "How it works" to one practical paragraph, remove kernel tutorial detail Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

The HTML comment inside the Markdown table was breaking rendering. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Instead of a standalone /tracing/apm_basic/ section (which frames APM Basic as a parallel product), integrate content into existing APM pages where users already look: - Overview + setup → /tracing/trace_collection/apm_basic/ - Metrics guide → /tracing/metrics/apm_basic_metrics/ Removes old USM pages and the standalone APM Basic section. Hugo aliases preserve all old URLs (USM and apm_basic paths). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

APM Basic lives at /tracing/apm_basic/ as a single page (not a section) between the glossary and Application Instrumentation. Framing is capability-first ("monitor services without instrumentation") rather than tier-first. Moved out of trace_collection since that section is "Application Instrumentation" and APM Basic is explicitly no-instrumentation. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

When upgrading from APM Basic to full APM, existing monitors, dashboards, and SLOs using universal.http.* metrics continue working. This was called out in the PM proposal's "Product Experience" section. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Remove space around em dash (Datadog style) - Remove repeated upgrade-path sentence from overview - "virtual machine" → "VM" - Fix outdated in-app nav path in metrics guide - Fix glossary link text to match page title - Improve Service Map sentence flow - Add trailing newline to glossary file Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add APM Basic as the first option (requires the least setup), followed by SSI, then custom instrumentation. Also removes "seamless" per style guidelines. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…for APM Basic Setup requires explicit enablement via Agent config; reframe as capability-first. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Reframe APM Basic as entry-level tier, add when-to-use context, and frame SSI as the upgrade path to full distributed tracing. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Lead overview with entry-level tier framing - Add when-to-use bullet lists in comparison section - Reinforce SSI as recommended path to full APM - Clarify universal.http.* vs trace.* namespace distinction - Rename 'How it works' to 'How APM Basic works (eBPF)' for scannability - Soften 'automatic baseline monitoring' claim pending PM confirmation Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- APM landing page: SSI leads Getting Started, APM Basic moved to end as aside for uninstrumented services - APM Basic page: drop 'entry-level tier' framing; clarify it is the option when instrumentation is not used, not a replacement for it - Nav: move APM Basic from weight 1.5 to 14.5 (after Error Tracking, before Guides) to signal supplementary capability, not primary path Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- apm_basic.md: fix ambiguous 'it' in overview, 'this' → 'eBPF' in eBPF section, add periods to full-sentence list items - getting_started: remove vague 'automatic service visibility' and 'not applicable' SSI language; replace with concrete use cases - glossary: same fix — replace 'automatic baseline monitoring' claim with concrete use-case framing - billing: remove orphaned [15] link reference (duplicate of [17]) - tracing index: 'not yet instrumented' → 'not instrumented' - apm_basic_metrics: 'a lot of' → 'many'; tighten overview sentence Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…s sub-pages - Split apm_basic.md into _index.md (overview), setup.md, and metrics.md - Move metrics guide from tracing/metrics/apm_basic_metrics/ to tracing/apm_basic/metrics/ - Add Hugo aliases on each page to preserve old URL redirects - Update nav: add Setup and Metrics as children of APM Basic; remove old APM Basic Metrics entry from tracing_metrics - Update tracing/metrics/_index.md link to point to new metrics URL Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

- Remove duplicate alert callout in setup.md - Fix nav YAML indentation for Trace Pipeline Configuration entry - Fix broken anchor in glossary (link to setup/ page, not nonexistent #setup) - Fix ambiguous pronoun in _index.md overview (It → APM Basic) - Fix sentence structure in _index.md overview paragraph - Fix weak link text in setup.md prerequisites (instructions here → Additional configuration) - Add newline at end of injectors.md Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Remove internal system-probe component reference and redundant parsing/aggregation sentence. Keep the language-agnostic statement (the most user-relevant part) and simplify the Windows note to focus on the IIS limitation without naming the internal ETW provider. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…ication - Billing: set APM Basic price to $18/host/month; reframe spans column to clarify no spans exist (not instrumented) rather than spans not covered - APM Basic overview: make staging/non-production use case explicit - APM landing page: add staging context to Getting Started paragraph - Remove TODO comment now that pricing is confirmed Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

- Fix ambiguous "It" pronouns in overview and glossary (replace with "APM Basic") - Remove em dashes: split sentences or replace with commas/periods - Fix capability table: "No code instrumentation required" -> "No instrumentation required" - Fix "like" -> "such as" in setup page callout - Simplify "non-business-critical" and "without any instrumentation required" in landing page Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-authored-by: domalessi <111786334+domalessi@users.noreply.github.com>

- Fix sentence case on "Further reading" heading in metrics.md - Revert unintentional Docker volume path change (/etc/dnf/vars, not /etc/dnf) - Combine repeated "kernel level" phrase into single sentence - Fix ambiguous pronoun: "assigns them" → "assigns each service" - Fix informal phrasing: "Click into" → "Click" - Fix repeated verb: "creating … and creating" → "creating … and building" - Fix inconsistent Apdex table description for universal.http.server.apdex Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

These files had unrelated or incomplete changes that should be handled separately. Restoring both to master state. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…cols/ The deleted additional_protocols.md page had no alias, causing a 404. Redirecting to setup.md which covers the equivalent configuration content. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

brett0000FF

Wow, great job! Looks really good. Note: You'll have to address the merge conflicts from the tracing library -> Datadog SDK rename. Sorry 😅

brett0000FF · 2026-04-24T20:38:29Z

+## How APM Basic works (eBPF)
+
+The Datadog Agent uses eBPF to observe network traffic at the kernel level, so APM Basic works regardless of the programming language or framework your services use.
+
+**Note**: On Windows, APM Basic uses Event Tracing for Windows (ETW) instead of eBPF. ETW is only available for IIS-based services. Non-IIS services on Windows support HTTP monitoring only, not HTTPS.


I don't think this is necessary to include. However, the part about "regardless of the programming or framework" is a good detail that could be added to the overview. Up to you though--just not sure we need to explain how this works.

Suggested change

## How APM Basic works (eBPF)

The Datadog Agent uses eBPF to observe network traffic at the kernel level, so APM Basic works regardless of the programming language or framework your services use.

**Note**: On Windows, APM Basic uses Event Tracing for Windows (ETW) instead of eBPF. ETW is only available for IIS-based services. Non-IIS services on Windows support HTTP monitoring only, not HTTPS.

Fair! I'll remove this section but incorporate that "regardless of programming language or framework" bit into the overview.

brett0000FF · 2026-04-24T20:44:19Z

-## How USM detects service names
+## How APM Basic detects service names

 <div class="alert alert-warning">


Preexisting, but this seems weird it's a red warning?

Suggested change

<div class="alert alert-warning">

<div class="alert alert-danger">

…-docs # Conflicts: # content/en/tracing/_index.md # content/en/tracing/apm_basic/metrics.md # content/en/tracing/apm_basic/setup.md # content/en/universal_service_monitoring/_index.md

jhgilbert · 2026-08-06T17:12:47Z

[Automated message] This PR has merge conflicts from a recent repo reorg that could not be resolved automatically.

If you feel comfortable resolving the conflicts yourself:

Resolve the conflicts. For a full list of repo files and folders and their updated location, see the configuration file for the reorg script.
When your PR is ready for merge, remove the WORK IN PROGRESS label.
Wait for the standard docs team approval before merging. Optionally, you can check the 'ready for merge' checkbox in the PR description if you would like the docs team to merge it for you.

If you need assistance resolving your conflicts, add the label astro-reorg-help-requested to your PR. This will add it to our support queue, and we will reach out to you as soon as possible.

This is an automated comment, but if you have a question, you can mention me in this PR (external contributors) or reach out in #docs-repo-reorg-support on Slack (internal contributors).

Resolve Hugo reorg conflicts by moving APM Basic docs to hugo/content/en/tracing/apm_basic/ and removing English USM pages. Co-authored-by: Cursor <cursoragent@cursor.com>

Co-authored-by: Cursor <cursoragent@cursor.com>

github-actions Bot added the Architecture Everything related to the Doc backend label Apr 6, 2026

domalessi and others added 4 commits April 8, 2026 11:16

Fix billing page table: move HTML comment above table

c9f27b3

The HTML comment inside the Markdown table was breaking rendering. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

github-actions Bot added the Guide Content impacting a guide label Apr 8, 2026

domalessi changed the title ~~[APM Basic] Template docs restructure (USM -> APM Basic)~~ [APM Basic] Integrate APM Basic docs into existing APM sections Apr 8, 2026

domalessi and others added 14 commits April 8, 2026 16:00

Update APM landing page Getting started section

1f323ff

Add APM Basic as the first option (requires the least setup), followed by SSI, then custom instrumentation. Also removes "seamless" per style guidelines. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Fix APM landing page: remove inaccurate 'automatically active' claim …

d1d7f19

…for APM Basic Setup requires explicit enablement via Agent config; reframe as capability-first. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Improve APM landing page Getting Started section

5fe2e16

Reframe APM Basic as entry-level tier, add when-to-use context, and frame SSI as the upgrade path to full distributed tracing. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

domalessi commented Apr 16, 2026

View reviewed changes

Comment thread content/en/tracing/apm_basic/_index.md Outdated

domalessi commented Apr 16, 2026

View reviewed changes

Comment thread content/en/tracing/apm_basic/metrics.md Outdated

domalessi commented Apr 16, 2026

View reviewed changes

Comment thread content/en/tracing/apm_basic/setup.md Outdated

domalessi commented Apr 16, 2026

View reviewed changes

Comment thread content/en/tracing/_index.md Outdated

Apply suggestions from code review

c3d898e

Co-authored-by: domalessi <111786334+domalessi@users.noreply.github.com>

domalessi commented Apr 17, 2026

View reviewed changes

Comment thread content/en/tracing/glossary/_index.md Outdated

domalessi commented Apr 17, 2026

View reviewed changes

Comment thread content/en/tracing/glossary/_index.md Outdated

domalessi commented Apr 17, 2026

View reviewed changes

Comment thread content/en/tracing/glossary/_index.md Outdated

domalessi and others added 4 commits April 17, 2026 14:50

Apply suggestions from code review

e88d5ad

Co-authored-by: domalessi <111786334+domalessi@users.noreply.github.com>

Remove glossary and injectors changes from APM Basic PR

6608a42

These files had unrelated or incomplete changes that should be handled separately. Restoring both to master state. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Add redirect alias for /universal_service_monitoring/additional_proto…

8c815f5

…cols/ The deleted additional_protocols.md page had no alias, causing a 404. Redirecting to setup.md which covers the equivalent configuration content. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

domalessi marked this pull request as ready for review April 17, 2026 19:16

domalessi requested a review from a team as a code owner April 17, 2026 19:16

domalessi added the editorial review Waiting on a more in-depth review label Apr 17, 2026

brett0000FF approved these changes Apr 24, 2026

View reviewed changes

Incorporate brett0000FF's feedback

c52a15f

ddOfir reviewed May 10, 2026

View reviewed changes

Comment thread hugo/content/en/tracing/apm_basic/_index.md

ddOfir reviewed May 10, 2026

View reviewed changes

Comment thread hugo/content/en/tracing/apm_basic/_index.md

ddOfir reviewed May 10, 2026

View reviewed changes

Comment thread hugo/content/en/account_management/billing/apm_tracing_profiler.md

domalessi added 2 commits May 11, 2026 14:54

Incorporate ddOfir's feedback

2cbe2bc

Combine alert callouts and adjust operation picker image size

9d07222

ddOfir approved these changes May 12, 2026

View reviewed changes

Comment thread hugo/content/en/tracing/metrics/_index.md

Merge remote-tracking branch 'origin/master' into domalessi/apm-basic…

a279825

…-docs # Conflicts: # content/en/tracing/_index.md # content/en/tracing/apm_basic/metrics.md # content/en/tracing/apm_basic/setup.md # content/en/universal_service_monitoring/_index.md

github-actions Bot added the Images Images are added/removed with this PR label Jul 31, 2026

jhgilbert added astro-reorg-manual-review Needs manual conflict resolution after replatforming reorg WORK IN PROGRESS No review needed, it's a wip ;) labels Aug 6, 2026

jhgilbert added the astro-reorg-processed Needs manual conflict resolution after replatforming reorg label Aug 6, 2026

domalessi and others added 3 commits August 7, 2026 15:36

Merge master into domalessi/apm-basic-docs

7fc9581

Resolve Hugo reorg conflicts by moving APM Basic docs to hugo/content/en/tracing/apm_basic/ and removing English USM pages. Co-authored-by: Cursor <cursoragent@cursor.com>

Merge branch 'master' into domalessi/apm-basic-docs

b3f227c

Merge branch 'master' into domalessi/apm-basic-docs

c200f2e

Co-authored-by: Cursor <cursoragent@cursor.com>

Navigation Menu

Uh oh!

[APM Basic] Integrate APM Basic docs into existing APM sections - #35777

[APM Basic] Integrate APM Basic docs into existing APM sections#35777
domalessi wants to merge 31 commits into
masterfrom
domalessi/apm-basic-docs

domalessi commented Apr 6, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Apr 6, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

brett0000FF left a comment

Uh oh!

Uh oh!

brett0000FF Apr 24, 2026

Uh oh!

domalessi Apr 27, 2026

Uh oh!

brett0000FF Apr 24, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jhgilbert commented Aug 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

	<div class="alert alert-warning">
	<div class="alert alert-danger">

Uh oh!

Conversation

domalessi commented Apr 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR do? What is the motivation?

Editorial review guidance

Context for reviewers

Merge instructions

Additional notes

Uh oh!

github-actions Bot commented Apr 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Preview links (active after the build_preview check completes)

New or renamed files

Removed or renamed files (these should redirect)

Renamed files

Modified Files

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

brett0000FF left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

brett0000FF Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

domalessi Apr 27, 2026

Choose a reason for hiding this comment

Uh oh!

brett0000FF Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jhgilbert commented Aug 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

domalessi commented Apr 6, 2026 •

edited

Loading

github-actions Bot commented Apr 6, 2026 •

edited

Loading

Preview links (active after the `build_preview` check completes)