Operations and observability
This page describes the current operational signals for SCL and its backend dependencies. It is intended for support and engineering teams; it does not contain credentials or secret-management procedures.
Deployment model
The SCL frontend is built as a static Next.js export and deployed to Azure Static Web Apps through Azure DevOps. The backend is deployed separately as an App Service with Azure Storage, API Management, and the configured integration services.
The current backend deployment also runs an initial seed process. That process creates the standard blob containers and inserts sample data only when the catalog tables are empty. It is not the normal mechanism for adding a later Role Play; use Create and provision a role-play for that workflow.
Health and version checks
After a deployment, verify these signals in the target environment:
- The backend health endpoint responds successfully.
- The version endpoint returns the expected build version, commit, and environment.
- The catalog endpoint returns active Role Plays for an authorized request.
- A staging launch reaches the briefing page.
- A controlled voice session reaches feedback.
- Completion and analytics are checked separately because both are non-blocking and asynchronous where configured.
The catalog endpoint returning a Role Play proves only that the catalog and active relationship are readable. It does not prove that SCAI voice, AI Factory evaluation, completion, or analytics are available.
Correlation and safe diagnostics
The backend accepts x-correlation-id. When one is not supplied, it generates a correlation ID and returns it in the response. Include this value in an incident record together with:
- Environment and approximate UTC timestamp.
- Role Play ID and, when authorized, analytics session ID.
- Browser/version, operating system, and network context.
- Learner-visible error category.
- HTTP status and dependency status.
Request logging records method, path, status, and latency without request bodies. Dependency logs include external status/latency, queue processing, retry, and poison-queue events. Do not add tokens, full transcripts, raw audio, or unsanitized payloads to support tickets or logs.
Queues and downstream delivery
The backend separates learner response time from downstream delivery:
| Queue | Purpose | Failure behaviour |
|---|---|---|
completion-requests | Deliver configured learning completion to Learning Platform Integration | Retries transient failures; isolates messages that exceed the retry limit in the poison queue |
analytics-events | Deliver backend analytics events and unload events to SCL Analytics | Retries delivery; isolates messages that exceed the retry limit in the poison queue |
Feedback can be returned successfully even when a downstream completion or analytics delivery later fails. Investigate the corresponding queue and poison queue before asking the learner to repeat a successful evaluation.
Dependency triage
| Symptom | First boundary to inspect | Next evidence |
|---|---|---|
| Portal cannot be opened | Static Web App authentication and deployment | Authentication response, route configuration, deployment result |
| Role Play is unavailable | RolePlays, ScaiAgents, active flags, and authorization | Catalog response and entity relationship |
| Briefing is empty or loading | roleplayinfo blob name, JSON, locale, and read access | Catalog payload and blob existence |
| Voice does not activate | SCAI agent, DNIS, environment credentials, WebSocket/WebRTC path | Credential exchange, SCAI signalling, browser network state |
| Feedback fails | Transcript, locale, criteria blob, AI Factory and technical token | Evaluation status, correlation ID, dependency logs |
| Completion is missing | Target platform, learner claims, completion queue, LPI | upn, cmid, queue state, LPI response |
| Analytics is missing | Analytics tenant, proxy session creation, backend token, analytics queue | Session response, proxy status, queue/poison-queue state |
Incident boundaries
Use the owning team shown in the Configuration map when escalating. Keep the learner journey and downstream delivery separate in incident reports:
- Feedback shown means the evaluation completed.
- It does not prove that completion reached the learning platform.
- Missing analytics does not prove that the learner abandoned or failed.
- A catalog failure is different from a voice, evaluation, completion, or analytics failure.
The planned Catalog API and Sessions API are not current operational dependencies. They remain future service boundaries until implemented.