Table of Contents

Control plane

The diagnostics control plane is part of the Reignite API. The diagnostic bot treats it as a read-only source of status and metrics, plus one write — starting a diagnosis — that is asynchronous.

Endpoints

The bot calls the API under /api/diagnostics/control-plane/:

Endpoint Purpose
Status Current control-plane agent status for the account.
Metrics Current metrics snapshot.
Start trace Starts a trace; the portal's dashboard uses a fixed 30-second CPU/ThreadPool trace.
Trace status Polls an operation by operationId.
Diagnose Starts an asynchronous diagnosis and returns a correlation id.

The exact controller is DiagnosticsControlPlaneController in the api repository; the API surface page lists the controller families.

Authentication

  • Inbound Teams → bot: a Bot Framework JWT, validated against the OpenID metadata, with issuer and audience checks.
  • Bot → API: an Authorization: Bearer <token> header. The token in the bot's DiagnosticsControlPlane:ApiToken must match the API deployment's expected token.
  • Portal → API: the website's authenticated user token.

Do not reuse the bot token for a user-facing client. Rotate it like any other service credential.

Diagnose lifecycle

sequenceDiagram
  autonumber
  participant User as Teams user
  participant Bot as Diagnostic Bot
  participant API as Reignite API
  participant Worker as Diagnosis worker
  User->>Bot: "Diagnose app X"
  Bot->>API: POST /api/diagnostics/control-plane/diagnose
  API->>Worker: Start asynchronous diagnosis
  API-->>Bot: 202 + correlation id
  Bot-->>User: "Diagnosis started" card
  User->>Bot: "Status?"
  Bot->>API: GET status by correlation id
  API-->>Bot: Running / complete
  Bot-->>User: Adaptive card

The diagnose endpoint returns quickly; the work happens out of band. The correlation id is the handle the bot uses to poll.

Failure handling

  • A control-plane failure is rendered as an unavailable card with the underlying message, never as a 500 back to Teams.
  • A connector failure is logged and not rethrown, so Bot Framework does not replay the activity and start a duplicate diagnosis.
  • A disabled diagnose action (TeamsBot:DiagnoseEnabled=false) returns a disabled notice rather than an error.

Read-only boundary

The bot may read status and metrics and may ask the control plane to start a diagnosis. It must not issue destructive commands. If a new action is added, decide explicitly whether it is a read, an asynchronous request, or a destructive operation; only the first two belong in this bot.