How grafana/synthetic-monitoring-app works
Purpose and host integration
This repository is the Grafana Synthetic Monitoring application: a TypeScript/React Grafana app plugin for configuring blackbox checks, probe locations, alerting, and viewing synthetic-monitoring results. It runs inside Grafana rather than as a standalone web application.
• src/module.tsx
• src/plugin.json
• src/datasource/module.ts
Entrypoints, initialization, and routing
The app plugin entry registers pages/components with Grafana. Initialization establishes tenant/setup, datasource, metadata, permissions, feature flags, and access contexts before routing users through initialized or uninitialized flows. Routing separates provisioning/setup states from normal check, probe, configuration, and dashboard navigation.
• src/components/AppInitializer.tsx
• src/routing/InitialisedRouter.tsx
• src/routing/UninitialisedRouter.tsx
Control plane: checks, probes, and configuration
The primary control-plane UI manages synthetic checks and probe agents. Check lists support filtering, folders, permissions, and bulk actions; dedicated pages create/edit checks and probes. The app targets public Grafana-managed probes and private probes, with API-server mapping data bundled for BYOC/development variants.
• src/page/CheckList/CheckList.tsx
• src/page/NewCheck/NewCheckV2.tsx
• src/page/EditProbe/EditProbe.tsx
• src/data/probeAPIServerMappings.json
Checkster form engine and API boundary
Checkster is the central check-editor system. It renders protocol-specific layouts (HTTP, DNS, gRPC, TCP, ping, traceroute, browser, scripted, multi-HTTP), maintains form state/sections, validates configurations, and converts between backend check objects and UI form values. The transformation layer is the key compatibility boundary: toFormValues ingests existing/API check data, while toPayload emits service-ready configuration.
• src/components/Checkster/Checkster.tsx
• src/components/Checkster/transformations/toFormValues.http.ts
• src/components/Checkster/transformations/toPayload.http.ts
• src/schemas/forms/utils/createCheckSchema.ts
Data access, authorization, and service dependencies
React data hooks centralize reads and mutations for checks, probes, folders, tenant limits, alerts, logs, secrets, and setup. Grafana permissions and folder access gate UI/actions. The plugin relies on Grafana-hosted Synthetic Monitoring APIs for configuration/execution, Prometheus/Mimir-compatible metrics datasources for measurements, Loki for logs, and a Secrets Manager API for protected values.
• src/data/useChecks.ts
• src/data/useProbes.ts
• src/data/clients/SecretsManagerClient/SecretsManagerClient.ts
• src/features/queryDatasources/queryMimir.ts
Observability results and dashboards
Protocol-specific Grafana Scenes dashboards compose metric queries and visualizations for availability, latency, traffic, DNS/browser results, and traceroute paths. Logs are fetched/parsing-normalized separately, then rendered with HTTP timings, screenshots, and trace links. Timepoint Explorer provides detailed per-execution/probe investigation.
• src/scenes/HTTP/HttpDashboard.tsx
• src/scenes/Common/DashboardContainer.tsx
• src/features/parseLokiLogs/parseLokiLogs.ts
• src/scenes/components/TimepointExplorer/TimepointExplorer.tsx
Alerts, export, and operational runtime
Check-level alert configuration supports routing previews and Grafana/legacy alert displays. Terraform generation converts check configuration into HCL for infrastructure-as-code workflows. The frontend is bundled with Webpack and developed against a Docker Compose Grafana environment; browser telemetry is integrated through Faro.
• src/components/CheckForm/AlertsPerCheck/AlertsPerCheck.tsx
• src/components/TerraformConfig/hcl/terraformRenderer.ts
• .config/webpack/webpack.config.ts
• docker-compose.yaml
• src/faro.ts
Main entry points: InitialisedRouter.tsx Initialized router · HttpDashboard.tsx Scenes dashboards · module.tsx Plugin entry · Checkster.tsx Checkster
Components 26
Grafana host
- Grafana runtime · Hosts the app plugin and supplies permissions, routing, and datasource access.
- Synthetic Monitoring APIs · Stores configuration and executes synthetic checks.
Plugin application
- Plugin entry
src/module.tsx - Plugin manifest
src/plugin.json - Datasource module
src/datasource/module.ts - App initializer · Loads tenant, setup, metadata, access, permissions, and feature state.
src/components/AppInitializer.tsx - Initialized router
src/routing/InitialisedRouter.tsx - Setup router
src/routing/UninitialisedRouter.tsx
Control plane
- Check list · Filters, folders, permissions, and bulk check actions.
src/page/CheckList/CheckList.tsx - Checkster · Protocol-specific form layouts, state, and validation.
src/components/Checkster/Checkster.tsx - Check schema
src/schemas/forms/utils/createCheckSchema.ts - API-to-form transform
src/components/Checkster/transformations/toFormValues.http.ts - Form-to-payload transform
src/components/Checkster/transformations/toPayload.http.ts - New check
src/page/NewCheck/NewCheckV2.tsx - Probe editor
src/page/EditProbe/EditProbe.tsx - Probe API mappings
src/data/probeAPIServerMappings.json - Data hooks · Centralizes check, probe, folder, setup, alert, log, secret, and limit operations.
src/data/useChecks.ts - Secrets Manager client
src/data/clients/SecretsManagerClient/SecretsManagerClient.ts
Results and operations
- Scenes dashboards · Composes protocol-specific availability, latency, traffic, and path views.
src/scenes/HTTP/HttpDashboard.tsx - Dashboard container
src/scenes/Common/DashboardContainer.tsx - Mimir metrics queries
src/features/queryDatasources/queryMimir.ts - Loki log parser
src/features/parseLokiLogs/parseLokiLogs.ts - Timepoint Explorer
src/scenes/components/TimepointExplorer/TimepointExplorer.tsx - Check alerts
src/components/CheckForm/AlertsPerCheck/AlertsPerCheck.tsx - Terraform renderer
src/components/TerraformConfig/hcl/terraformRenderer.ts - Faro telemetry
src/faro.ts
Connections 27
- Grafana runtime → Plugin entry: loads
- Plugin manifest → Plugin entry: declares
- Plugin entry → Datasource module: integrates
- Plugin entry → App initializer: starts
- App initializer → Initialized router: when initialized
- App initializer → Setup router: when setup required
- Initialized router → Check list: routes to
- Initialized router → New check: routes to
- Initialized router → Probe editor: routes to
- Initialized router → Scenes dashboards: routes to
- New check → Checkster: uses
- Checkster → Check schema: validates with
- API-to-form transform → Checkster: hydrates form
- Checkster → Form-to-payload transform: produces values
- Check list → Data hooks: reads and mutates through
- Probe editor → Data hooks: manages through
- Data hooks → Synthetic Monitoring APIs: calls
- Form-to-payload transform → Synthetic Monitoring APIs: submits configuration
- Probe editor → Probe API mappings: uses
- Secrets Manager client → Synthetic Monitoring APIs: protects values via
- Scenes dashboards → Dashboard container: renders in
- Scenes dashboards → Mimir metrics queries: queries measurements
- Scenes dashboards → Loki log parser: loads normalized logs
- Scenes dashboards → Timepoint Explorer: drills into
- Check alerts → Synthetic Monitoring APIs: configures
- Terraform renderer → Form-to-payload transform: exports check configuration
- Plugin entry → Faro telemetry: reports telemetry