Skip to content

docs(tutorial): treat App Insights as already-connected by default#191

Merged
placerda merged 1 commit into
developfrom
feature/tutorial-appinsights-default-exists
May 29, 2026
Merged

docs(tutorial): treat App Insights as already-connected by default#191
placerda merged 1 commit into
developfrom
feature/tutorial-appinsights-default-exists

Conversation

@placerda
Copy link
Copy Markdown
Contributor

Why

PO doing the prompt-agent quickstart pointed out that section 8's optional App Insights subsection reads as if the resource might not exist, when in fact step 3 (both Path A and Path B) already instructs the reader to attach App Insights to the dev project:

  • Path A (manual portal) — lists 'Attach or create an Application Insights resource for telemetry, starting with the dev project' among the project-creation steps.
  • Path B (microsoft-foundry skill) — the prompt explicitly tells the skill to 'Attach or create an Application Insights resource for telemetry, starting with the dev project.'

So the default expectation should be 'it already exists', with a quick verification, and only fall back to manual creation/override if the verification fails.

What changed

Only docs/tutorial-prompt-agent-quickstart.md. Net: +51 / -26 lines.

  1. Section 7 callout rewritten to lead with 'should already be wired from step 3' and give a 10-second portal check.
  2. Section 8 optional subsection restructured:
    • Opens with 'you can skip this subsection' and a 2-row decision table for the verification outcome.
    • Adds a 'just click Connect Application Insights in the Foundry portal' fallback for the rare case the resource was not created in step 3.
    • Demotes the manual APPLICATIONINSIGHTS_CONNECTION_STRING paste to an 'override which resource telemetry goes to' advanced case at the end.
  3. Path A → C portal/CLI instructions remain available for anyone who actually needs the override.

Out of scope

The hosted-agent and end-to-end tutorials have different App Insights flows (wizard-driven, local FastAPI sample needing the env variable to enable OpenTelemetry export) — those are intentionally untouched here. Only the prompt-agent quickstart had the 'might not exist' framing.

Validation

Documentation-only change, no tests required.

PO running through the tutorial pointed out that section 8's optional
App Insights subsection reads as if the resource might not exist,
when in fact step 3 (both Path A and Path B) already instructs the
reader to attach App Insights to the dev project. Reframe accordingly:

- Section 7 callout now leads with 'should already be wired from
  step 3' and gives a 10-second portal check to confirm.
- Section 8 optional subsection now starts with 'you can skip this
  subsection', shows a 2-row decision table for the verification
  outcome, and only walks through the override case (a dedicated
  observability resource) at the end. Adds a 'just click Connect
  Application Insights in the Foundry portal' fallback for the rare
  case the resource was not created in step 3.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@placerda placerda merged commit d544388 into develop May 29, 2026
8 checks passed
@placerda placerda deleted the feature/tutorial-appinsights-default-exists branch May 29, 2026 02:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant