Improve user experience & AI readability of the Azure Container Apps Instrumentation page by migrating to Customizable Docs by rohanagarwaldd · Pull Request #38440 · DataDog/documentation

rohanagarwaldd · 2026-07-23T17:54:55Z

Summary

Migrates the Azure Container Apps instrumentation docs from ~16 separate pages (7 runtimes × 2 instrumentation methods, plus the In-Container/Sidecar index pages) into a single Customizable Docs (Cdocs) page driven by Runtime and Instrumentation method filters — then adds structure so the consolidated page stays friendly to AI agents and answer engines.

Now ready to Merge

Why

User experience: one page with filters instead of navigating between ~16 near-duplicate pages. Readers pick their runtime + method and see only what's relevant.
AI readability: Cdocs packs every variant onto one page. A human only sees the selected variant, but an AI agent (and the auto-generated serverless llms.txt) receives the entire page "flat." Without added structure, an agent has to self-select the right variant out of one large page.

What changed

Migration (a29c7a64be, 90aad733c4)

Consolidate the per-runtime/per-method pages into _index.mdoc.md with content_filters for instrumentation_method and prog_lang; the former per-variant URLs are preserved as aliases.
Remove the In-Container / Sidecar child entries from the side nav (now one page).

AI-readability additions (985b05799e)

Per-variant headings — each of the 14 filter blocks now starts with a heading (e.g. ### In-Container: Ruby), giving the consolidated page stable anchors (#in-container-ruby, mirroring the old per-variant URLs) and clear section delimiters in the flat plaintext/.md that agents consume. Headings live inside the filter blocks, so the table of contents stays trait-aware for human readers.
description frontmatter — improves the serverless llms.txt entry and answer-engine optimization (the page previously had none).
Section title — renamed the comparison callout to "In-Container vs. Sidecar".

Validation

make build-cdocs compiles cleanly (108 Markdoc files).
Headings render as anchored <h3> inside each cdoc__toggleable block; the TOC updates per active filter (consistent with the cdocs headings/TOC behavior).

Not addressed here (for discussion)

Whether consolidating ~16 pages into one 14-variant page crosses the Cdocs "overuse" / long-page threshold (page weight, "Copy page" token cost) is a separate question for the Cdocs / AI-readability team — this PR does not split the page. (Done, docs team concluded that the page length does not exceed the expected limit)

🤖 Generated with Claude Code

…page Replace the separate in-container and sidecar per-language pages with one filterable Cdocs page driven by instrumentation_method and prog_lang content filters. Extract shared serverless-init content into Markdoc partials, add the instrumentation_method trait and serverless option groups, and remove the now orphaned _index translations. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…e nav The per-method pages are consolidated into the single Azure Container Apps Cdocs page, so the child nav items are no longer needed. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

The ACA instrumentation docs were consolidated from ~16 separate pages (7 runtimes x 2 methods, plus method indexes) into a single Cdocs page driven by runtime + instrumentation-method filters. On one page, all variants "lie flat" in the plaintext/.md version that AI agents (and the serverless llms.txt) consume, so this adds structure back: - Add a heading to each of the 14 content-filter variants (for example "### In-Container: Ruby") so the page exposes stable per-variant anchors (#in-container-ruby, mirroring the former per-variant URLs) and clear section delimiters in the flat plaintext. Headings live inside the filter blocks, so the table of contents stays trait-aware for human readers (verified against the cdocs headings/TOC behavior). - Add `description` frontmatter to improve the serverless llms.txt entry and answer-engine optimization. - Rename the comparison section title to "In-Container vs. Sidecar". Verified with `make build-cdocs` (compiles cleanly; headings render as anchored <h3> inside the filter blocks). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Bring the ACA Cdocs migration up to date with master (was 728 commits behind). Conflict resolutions: - content/en/serverless/azure_container_apps/sidecar/nodejs.md: kept deleted. The migration consolidates all sidecar/runtime pages into the single Cdocs page; master's only change to it (#38081, GCP->Azure reference fixes) is already reflected in the consolidated page's partials. - content/.gitignore: union of both sides (kept the ACA _index.md ignore plus master's new cpp / observability_pipelines / session_replay entries). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

github-actions · 2026-07-23T18:29:00Z

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

New or renamed files

https://docs-staging.datadoghq.com/rohanagarwal/aca-cdocs-migration/serverless/azure_container_apps/

Removed or renamed files (these should redirect)

rohanagarwaldd · 2026-07-27T17:49:59Z

removing this file, and all succeeding language-specific files and adding the information to _index.mdoc.md to be accessed using cdocs filtering.

rohanagarwaldd · 2026-07-27T18:52:08Z

deleting old language specific guides as we got instruction that new cdocs implementation will be translated to target languages via phase.

ava-silver

One question about the consolidated ACA content.

ava-silver · 2026-07-28T19:26:42Z

+
+| Variable                 | Description | Container |
+| ------------------------ | ----------- | --------- |
+| `DD_API_KEY`             | [Datadog API key](https://app.datadoghq.com/organization-settings/api-keys) - **Required** | Sidecar container |


The ACA sidecar table no longer lists DD_AZURE_SUBSCRIPTION_ID and DD_AZURE_RESOURCE_GROUP, although the legacy partial required both for containerapp, can we fix that?

ava-silver · 2026-07-28T19:30:17Z

+
+{% /collapse-content %}
+
+## Setup


Should this page still state the Azure Integration prerequisite before setup? The further-reading card may be sufficient, but the previous in-container and sidecar landing pages explicitly made it the first step.

Ah you are right. At least for this PR, I think it would be best to preserve that. I will make the change

Add DD_AZURE_SUBSCRIPTION_ID and DD_AZURE_RESOURCE_GROUP to the sidecar serverless-init env vars table to match the in-container table and the current published documentation. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Add a prerequisite note to set up the Azure Integration before instrumentation, matching the current published documentation. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

ava-silver

overall lgtm, nothing looks like a regression here -- I think there are some things we could do to improve but that's out of scope for this PR

ava-silver · 2026-07-29T21:51:42Z

nit: if theres a way, itd be great to only have a $ appear on the first line, or remove the \ and see if we can have line wrapping for these commands:

Add a sentence after the prerequisite explaining that the setup instruments the application with serverless-init to enable tracing, enhanced metrics, custom metrics, and direct log collection. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

ava-silver · 2026-07-29T23:41:06Z

+
+{% /collapse-content %}
+
+## Setup


One other thing an agent found:

The previous page documented that Serverless Agent instrumentation provides enhanced metrics, linked to the metrics reference, and identified the azure.app_containerapps.enhanced.* namespace. Could we restore that guidance here? Without it, users can no longer discover the enhanced metrics capability or know which namespace to query.

Note that enhanced metrics use the azure.app_containerapps.enhanced.* namespace, linking to the Azure Container Apps integration metrics section, matching the current published documentation. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

janine-c · 2026-07-30T00:46:23Z

Nice! Created DOCS-15245 for docs team review 🙂

brett0000FF

Looks great! Nice job on this conversion. I left a few comments and suggestions for you to consider.

As we discussed, the main loss for agent-friendliness will be the generated .md page size, but I think the tradeoff is worth it given the content improvements for both humans and agents. And this will inherently resolve after we migrate off of Hugo.

brett0000FF · 2026-07-31T22:29:02Z

Can you please revert the deletion of non-english pages? It's better for these to exist until the non-English cdocs pages are translated. Otherwise, we temporarily only have English content.

brett0000FF · 2026-08-04T20:50:59Z

+{% step title="Set up logs" %}
+To enable logging, set the environment variable `DD_LOGS_ENABLED=true`. This allows `serverless-init` to read logs from stdout and stderr.
+
+Datadog also recommends setting the environment variables `DD_LOGS_INJECTION=true` and `DD_SOURCE=nodejs` to enable advanced Datadog log parsing.


I believe DD_LOGS_INJECTION is for trace/log correlation whereas DD_SOURCE is for parsing? This is repeated a few times on the page. I think it would be more precise to say:

Set DD_LOGS_INJECTION=true to correlate logs and traces, and DD_SOURCE=node.js to enable language-specific parsing.

brett0000FF · 2026-08-04T20:56:56Z

+
+| Aspect | In-Container | Sidecar |
+|--------|--------------|---------|
+| Deployment | One container (your app, wrapped with the Datadog Agent) | Two containers (your app, Datadog Agent) |


brett0000FF · 2026-08-04T21:04:06Z

+    text: "Azure Integration"
+---
+
+{% collapse-content title="In-Container vs. Sidecar" level="h5" %}


Nothing wrong with the existing approach but it would be more typical to just have an overview section. I do think we are missing a brief overview telling users about this page. Switching from a collapsed section avoids starting the page with an h5 as well, which could hurt the page structure for agents.

## Overview Azure Container Apps is a fully managed serverless platform for deploying and scaling containerized applications. Datadog monitors Container Apps in two layers: - The Azure integration collects standard metrics and logs. - The Datadog `serverless-init` Agent adds distributed tracing, enhanced metrics, custom metrics, and direct log collection. Instrument your application with `serverless-init` in one of two ways: - **In-container**: Wraps your application container with the Datadog Agent. Choose this for a simpler setup, lower cost overhead, and direct log piping. - **Sidecar**: Runs the Datadog Agent in a separate container alongside your application container. Choose this if you have multiple containers in a single service, if you prefer strict isolation of the Datadog Agent, or if you have performance-sensitive workloads.

made changes to add a short overview and repositioned the collapsed section.

brett0000FF · 2026-08-04T21:04:43Z

+}
+```
+
+Finally, run `terraform apply`, and follow any prompts.


Seems out of order since we include that command after a bit of exposition.

Suggested change

Finally, run `terraform apply`, and follow any prompts.

completely agree, this is something we flagged already. we will make this change in a future PR

brett0000FF · 2026-08-04T21:05:44Z

+The [Datadog Container App module](https://registry.terraform.io/modules/DataDog/container-app-datadog/azurerm/latest) only deploys the Container App resource, so you need to build and push your container separately.
+
+See the [Environment variables](#environment-variables) section for more information on the configuration options available through the `env`.
+
+Make sure the container port for the main container matches the one exposed in your Dockerfile/service.


These are sorta floating notes you could bullet under a lead in like "Note the following before you deploy:"

…hooting.mdoc.md Co-authored-by: Brett Blue <84536271+brett0000FF@users.noreply.github.com>

…oc.md Co-authored-by: Brett Blue <84536271+brett0000FF@users.noreply.github.com>

Co-authored-by: Brett Blue <84536271+brett0000FF@users.noreply.github.com>

Narrow the generated-file gitignore from /*/ to /en/ so it only ignores the compiled English _index.md, and restore the Spanish, Japanese, and Korean _index.md pages that the broad pattern had swept into deletion. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

rohanagarwaldd and others added 3 commits July 20, 2026 11:12

Remove In-Container and Sidecar entries from Azure Container Apps sid…

90aad73

…e nav The per-method pages are consolidated into the single Azure Container Apps Cdocs page, so the child nav items are no longer needed. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

This comment has been minimized.

Sign in to view

github-actions Bot added Architecture Everything related to the Doc backend cdocs labels Jul 23, 2026

rohanagarwaldd assigned rohanagarwaldd, ava-silver and Chronobreak Jul 23, 2026

rohanagarwaldd commented Jul 27, 2026

View reviewed changes

ava-silver reviewed Jul 28, 2026

View reviewed changes

rohanagarwaldd and others added 2 commits July 29, 2026 16:12

Add Azure Integration prerequisite to setup section

eacd2e2

Add a prerequisite note to set up the Azure Integration before instrumentation, matching the current published documentation. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

rohanagarwaldd requested a review from ava-silver July 29, 2026 20:46

rohanagarwaldd added 2 commits July 29, 2026 17:07

Merge branch 'master' into rohanagarwal/aca-cdocs-migration

fcbd5e2

Merge branch 'master' into rohanagarwal/aca-cdocs-migration

fe7a255

rohanagarwaldd marked this pull request as ready for review July 29, 2026 21:49

rohanagarwaldd requested review from a team as code owners July 29, 2026 21:49

ava-silver approved these changes Jul 29, 2026

View reviewed changes

ava-silver reviewed Jul 29, 2026

View reviewed changes

janine-c added the editorial review Waiting on a more in-depth review label Jul 30, 2026

rohanagarwaldd mentioned this pull request Aug 4, 2026

Add agentic onboarding setup to the Azure Container Apps page [SVLS-9614] #38746

Merged

1 task

brett0000FF approved these changes Aug 4, 2026

View reviewed changes

rohanagarwaldd and others added 5 commits August 4, 2026 22:38

Update layouts/shortcodes/mdoc/en/serverless/serverless-init-troubles…

0f91565

…hooting.mdoc.md Co-authored-by: Brett Blue <84536271+brett0000FF@users.noreply.github.com>

Update layouts/shortcodes/mdoc/en/serverless/serverless-init-image.md…

e6f231b

…oc.md Co-authored-by: Brett Blue <84536271+brett0000FF@users.noreply.github.com>

Update content/en/serverless/azure_container_apps/_index.mdoc.md

44b6e05

Co-authored-by: Brett Blue <84536271+brett0000FF@users.noreply.github.com>

Update content/en/serverless/azure_container_apps/_index.mdoc.md

ddbb882

Co-authored-by: Brett Blue <84536271+brett0000FF@users.noreply.github.com>

rohanagarwaldd merged commit ef396d6 into master Aug 5, 2026
17 checks passed

rohanagarwaldd deleted the rohanagarwal/aca-cdocs-migration branch August 5, 2026 15:13

	\| Deployment \| One container (your app, wrapped with the Datadog Agent) \| Two containers (your app, Datadog Agent) \|
	\| Deployment \| One container (your app, wrapped with the Datadog Agent). \| Two containers (your app, Datadog Agent). \|

Uh oh!

Conversation

rohanagarwaldd commented Jul 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Why

What changed

Validation

Not addressed here (for discussion)

Uh oh!

This comment has been minimized.

github-actions Bot commented Jul 23, 2026

Preview links (active after the build_preview check completes)

New or renamed files

Removed or renamed files (these should redirect)

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ava-silver left a comment

Choose a reason for hiding this comment

Uh oh!

ava-silver Jul 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ava-silver left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

janine-c commented Jul 30, 2026

Uh oh!

brett0000FF left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

brett0000FF Aug 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

brett0000FF Aug 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

brett0000FF Aug 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

rohanagarwaldd commented Jul 23, 2026 •

edited

Loading

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

ava-silver Jul 28, 2026 •

edited

Loading

brett0000FF Aug 4, 2026 •

edited

Loading

brett0000FF Aug 4, 2026 •

edited

Loading

brett0000FF Aug 4, 2026 •

edited

Loading