quinzee.cloud

Development edition · 16 November 2026. Commands using repository paths, Make targets or sample projects require access to the Quinzee source checkout. No public installer is available. Examples use disposable local environments.

Administrator’s guide

12. Observe the platform and the application separately

Quinzee's platform diagnostics describe the emulator, workers and helpers. Application Insights and Log Analytics store application telemetry through Azure-compatible APIs. An optional external Grafana/OTLP stack observes the platform. These are related but separate pipelines: enabling one does not silently configure the others.

Step 1: check basic health

GET /health is public liveness. GET /ready says Identity and Resource Manager are loaded; it does not certify that every optional module or external database is available. In QHQ → Monitoring → Observability → Health, inspect workers, module state, engine status and heartbeat freshness. An old runtime status can remain visible after its helper stops; use the heartbeat as well as the last reconciliation result.

Platform health

An engine heartbeat older than ten seconds is unavailable. Request handler metrics exclude socket transfer and executor wait, while transport metrics span the parsed HTTP exchange. Queue depth samples cover at most 32 queues with a bounded sampling budget and ten-second cache; a truncated sample is not a complete count of pending work. Use service inventory for exact operational investigation.

Step 2: correlate one request

Open Requests, reproduce one action, and filter by its trace ID. A trace ID links request/operation records; it is not an authentication token. Logs omit headers, queries, bodies and private credential material. Application log messages and custom properties remain application-controlled data, so producers must avoid secrets and personal data themselves. Redaction of known names is not a general sensitive-data detector.

Administrator APIs include /quinzee/v1/observability and /quinzee/v1/observability/metrics. The latter returns Prometheus text. Both require an administrator bearer token; do not publish them anonymously to make scraping convenient.

Step 3: provision and query application monitoring

Compile examples/book-iac/monitoring.bicep into .local/admin-training/monitoring.json with python3 scripts/deps/bicep.py build and --outfile, then submit it through QHQ Deployments in your training group. The default parameters create a Log Analytics workspace and a workspace-backed Application Insights component. The component needs the workspace capability, so unload the component module before the workspace module. Configure the application's official exporter with its returned connection string and supported token credential when local authentication is disabled. Use 100% sampling for this subset.

Open Workspace logs, enter the customer/workspace ID and a query:

AppTraces | order by TimeGenerated desc | take 20

Use AppRequests, AppDependencies, AppTraces, AppExceptions, AppEvents or AppMetrics. Supported stages are simple where comparisons, project, one-column order by, take/limit, count and summarize count(). Unsupported operators return errors; there is no full KQL engine behind the textbox.

Resource / API Configurable values and bounds
Workspace Name/location/tags, PerGB2018 SKU, retentionInDays 30–730
Component Name/location/tags, web/other application type, immutable workspace binding, DisableLocalAuth
Ingestion Uncompressed JSON object/array/NDJSON, supported envelope types, 1 MiB/256 envelopes, 8 KiB rows
Stored data At most 64 workspaces/components; latest 4,096 rows/workspace in addition to time retention
Query Query and optional timespan; 4,096 characters, 16 stages, at most 1,000 result rows; QHQ displays up to 100
ARM metrics Supported request/dependency count/failed/duration; Count/Total/Average/Minimum/Maximum; PT1M/PT5M/PT1H/FULL; at most ten names, 30 days and 1,440 buckets

The 4,096-row cap can evict data much sooner than the configured days. Do not promise a month of audit history based only on retentionInDays. Live metrics, profiling, alerts, diagnostic settings, gzip/sample ingestion and arbitrary cross-workspace queries are unsupported.

Step 4: enable external platform telemetry

The simplest complete local stack is make application-observability-up. It prepares a separate application environment, certificates, private telemetry credentials and the Grafana/Collector/Prometheus/Loki/Tempo services. Record the URLs and paths it reports. For a separately managed cloud, use the normal TLS arguments plus --otlp-endpoint https://<collector-origin> and --otlp-ca <collector-ca-file>. The engine helper has matching QUINZEE_OTLP_ENDPOINT/QUINZEE_OTLP_CA environment values.

The stack Compose settings include QUINZEE_UID/GID, QUINZEE_OBSERVABILITY_DIR (private persisted data and TLS/auth files), QUINZEE_GRAFANA_PORT (default 13001) and QUINZEE_OTLP_PORT (14318). Its configuration files are mounted from infrastructure/observability: collector.yaml routes telemetry, prometheus.yaml sets collection, loki.yaml and tempo.yaml control stores, grafana.ini and the provisioning directory set dashboard/datasource behavior. Review those explicit files when operating the optional third-party stack; they are not quinzee.cloud JSON members. Keep the healthcheck and authentication/trust mounts intact.

Export is bounded and best effort. Collector failure increments export/drop counters instead of blocking application requests. Check those counters before assuming that an empty dashboard proves no requests occurred. Stop/backup this stack separately from the cloud's own monitoring resource files.