feat: add multi-location uptime monitoring via Globalping

## Changes

### Server
- Add `locations` field to Monitor model and types (up to 5 locations per monitor)
- Add `location` field to Check metadata for per-location tracking
- Add `globalpingApiKey` to AppSettings for API key management
- Create GlobalpingService that wraps the Globalping SDK to run distributed
  HTTP/ping checks from multiple global locations (NA, EU, AS, SA, OC, AF)
- Extend SuperSimpleQueueHelper with fire-and-forget Globalping checks that
  run alongside the existing local check without affecting the main pipeline
- Add location-aware check queries with aggregation pipeline grouping by
  location in MongoChecksRepository
- Filter location checks from main uptime aggregation to preserve local check
  as source of truth for status/incidents
- Extend monitor details endpoint to return per-location check data
- Add GET /globalping/locations endpoint for available location options
- Add globalpingKeySet to settings response
- Add Joi validation for locations and globalpingApiKey fields

### Client
- Add locations multi-select (Autocomplete with chips) to monitor creation
  form, shown only for HTTP and ping monitor types
- Add SettingsGlobalping component for API key management (matching existing
  PageSpeed pattern with set/reset flow)
- Add per-location breakdown section to uptime details page with tabs,
  avg response time, uptime percentage, and response time charts
- Add globe icon with tooltip to monitor table for monitors with locations
- Add Zod validation for locations field in HTTP and ping schemas
- Add all translation keys for globalping settings, locations form, and
  location details sections

## Benefits
- Users gain visibility into geographic availability and latency data
- Local check remains the source of truth, Globalping runs alongside
- Supports up to 5 locations per monitor with 6 continent-level options
- Graceful degradation when API key is not configured or rate limited
This commit is contained in:
gorkem-bwl committed 2026-02-19 00:45:14 -05:00
1 parent 1c1474cd6f
commit e39b44db6c
33 files changed
+1258 -24

No files matched your search

+4
View File
@@ -14,6 +14,7 @@ import {
INotificationsService,
} from "@/service/index.js";
import SuperSimpleQueueHelper from "../service/infrastructure/SuperSimpleQueue/SuperSimpleQueueHelper.js";
import GlobalpingService from "../service/infrastructure/globalpingService.js";
import SuperSimpleQueue from "../service/infrastructure/SuperSimpleQueue/SuperSimpleQueue.js";
import UserService from "../service/business/userService.js";
import CheckService from "../service/business/checkService.js";
@@ -192,6 +193,8 @@ export const initializeServices = async ({
notificationMessageBuilder
);
const globalpingService = new GlobalpingService({ settingsService, logger });
const superSimpleQueueHelper = new SuperSimpleQueueHelper({
logger,
networkService,
@@ -200,6 +203,7 @@ export const initializeServices = async ({
checkService,
buffer: bufferService,
incidentService,
globalpingService,
maintenanceWindowsRepository,
monitorsRepository,
teamsRepository,
@@ -26,6 +26,7 @@ import {
} from "./controllerUtils.js";
import { AppError } from "@/utils/AppError.js";
import { IMonitorService } from "@/service/index.js";
import { GLOBALPING_LOCATIONS } from "@/service/infrastructure/globalpingService.js";
const SERVICE_NAME = "monitorController";
class MonitorController {
@@ -387,6 +388,18 @@ class MonitorController {
}
};
getGlobalpingLocations = async (_req: Request, res: Response, next: NextFunction) => {
try {
return res.status(200).json({
success: true,
msg: "Globalping locations retrieved successfully",
data: GLOBALPING_LOCATIONS,
});
} catch (error) {
next(error);
}
};
getGroupsByTeamId = async (req: Request, res: Response, next: NextFunction) => {
try {
const teamId = req?.user?.teamId;
+6 -1
View File
@@ -21,8 +21,9 @@ class SettingsController {
const sanitizedSettings = { ...dbSettings };
delete sanitizedSettings.version;
delete sanitizedSettings.jwtSecret;
const returnSettings = {
const returnSettings: any = {
pagespeedKeySet: false,
globalpingKeySet: false,
emailPasswordSet: false,
settings: null,
};
@@ -31,6 +32,10 @@ class SettingsController {
returnSettings.pagespeedKeySet = true;
delete sanitizedSettings.pagespeedApiKey;
}
if (typeof sanitizedSettings.globalpingApiKey !== "undefined") {
returnSettings.globalpingKeySet = true;
delete sanitizedSettings.globalpingApiKey;
}
if (typeof sanitizedSettings.systemEmailPassword !== "undefined") {
returnSettings.emailPasswordSet = true;
delete sanitizedSettings.systemEmailPassword;
+1
View File
@@ -23,6 +23,7 @@ const AppSettingsSchema = new Schema<AppSettingsDocument>(
language: { type: String, default: "gb" },
jwtSecret: { type: String },
pagespeedApiKey: { type: String },
globalpingApiKey: { type: String },
systemEmailHost: { type: String },
systemEmailPort: { type: Number },
systemEmailAddress: { type: String },
+5
View File
@@ -19,6 +19,7 @@ type CheckMetadataDocument = Omit<CheckMetadata, "monitorId" | "teamId"> & {
monitorId: Types.ObjectId;
teamId: Types.ObjectId;
type: MonitorType;
location?: string;
};
type CheckDocumentBase = Omit<Check, "id" | "metadata" | "expiry" | "ackAt" | "createdAt" | "updatedAt"> & {
@@ -197,6 +198,9 @@ const metadataSchema = new Schema<CheckMetadataDocument>(
required: true,
index: true,
},
location: {
type: String,
},
},
{ _id: false }
);
@@ -299,6 +303,7 @@ CheckSchema.index({ createdAt: 1 });
CheckSchema.index({ "metadata.teamId": 1, createdAt: -1 });
CheckSchema.index({ "metadata.monitorId": 1, "metadata.type": 1, createdAt: -1 });
CheckSchema.index({ "metadata.teamId": 1, status: 1, createdAt: -1 });
CheckSchema.index({ "metadata.monitorId": 1, "metadata.location": 1, createdAt: -1 });
const CheckModel = model<CheckDocument>("Check", CheckSchema);
+4
View File
@@ -160,6 +160,10 @@ const MonitorSchema = new Schema<MonitorDocument>(
gameId: {
type: String,
},
locations: {
type: [String],
default: [],
},
group: {
type: String,
trim: true,
@@ -35,6 +35,12 @@ export interface IChecksRepository {
options?: { type?: MonitorType }
): Promise<UptimeChecksResult | HardwareChecksResult | PageSpeedChecksResult>;
findSummaryByTeamId(teamId: string, dateRange: string): Promise<ChecksSummary>;
findLocationChecksByMonitorId(
monitorId: string,
startDate: Date,
endDate: Date,
dateString: string
): Promise<Record<string, UptimeChecksResult>>;
// update
//delete
deleteByMonitorId(monitorId: string): Promise<number>;
@@ -169,6 +169,7 @@ class MongoChecksRepository implements IChecksRepository {
monitorId: toStringId(metadata.monitorId),
teamId: toStringId(metadata.teamId),
type: metadata.type,
...(metadata.location ? { location: metadata.location } : {}),
});
return {
@@ -219,6 +220,7 @@ class MongoChecksRepository implements IChecksRepository {
monitorId: new mongoose.Types.ObjectId(metadata.monitorId),
teamId: new mongoose.Types.ObjectId(metadata.teamId),
type: metadata.type,
...(metadata.location ? { location: metadata.location } : {}),
},
...rest,
} as unknown as CheckDocument;
@@ -420,6 +422,68 @@ class MongoChecksRepository implements IChecksRepository {
return result.deletedCount ?? 0;
};
findLocationChecksByMonitorId = async (
monitorId: string,
startDate: Date,
endDate: Date,
dateString: string
): Promise<Record<string, any>> => {
const monitorObjectId = new mongoose.Types.ObjectId(monitorId);
const matchStage = {
"metadata.monitorId": monitorObjectId,
"metadata.location": { $exists: true, $ne: null },
createdAt: { $gte: startDate, $lte: endDate },
};
const results = await CheckModel.aggregate([
{ $match: matchStage },
{ $sort: { createdAt: 1 } },
{
$group: {
_id: {
location: "$metadata.location",
bucket: { $dateToString: { format: dateString, date: "$createdAt" } },
},
avgResponseTime: { $avg: "$responseTime" },
totalChecks: { $sum: 1 },
upChecks: { $sum: { $cond: [{ $eq: ["$status", true] }, 1, 0] } },
},
},
{ $sort: { "_id.bucket": 1 } },
{
$group: {
_id: "$_id.location",
groupedChecks: {
$push: {
bucketDate: "$_id.bucket",
avgResponseTime: "$avgResponseTime",
totalChecks: "$totalChecks",
},
},
totalUpChecks: { $sum: "$upChecks" },
totalAllChecks: { $sum: "$totalChecks" },
overallAvgResponseTime: { $avg: "$avgResponseTime" },
},
},
]);
const locationChecks: Record<string, any> = {};
for (const loc of results) {
const uptimePercentage =
loc.totalAllChecks > 0 ? loc.totalUpChecks / loc.totalAllChecks : 0;
locationChecks[loc._id] = {
monitorType: "http" as const,
groupedChecks: loc.groupedChecks,
groupedUpChecks: [],
groupedDownChecks: [],
uptimePercentage,
avgResponseTime: loc.overallAvgResponseTime ?? 0,
};
}
return locationChecks;
};
private findUptimeDateRangeChecks = async (
monitorType: Exclude<MonitorType, "hardware" | "pagespeed">,
monitorObjectId: mongoose.Types.ObjectId,
@@ -427,9 +491,10 @@ class MongoChecksRepository implements IChecksRepository {
endDate: Date,
dateString: string
) => {
const matchStage = {
const matchStage: Record<string, any> = {
"metadata.monitorId": monitorObjectId,
createdAt: { $gte: startDate, $lte: endDate },
"metadata.location": { $exists: false },
};
const [result] = await CheckModel.aggregate([
{ $match: matchStage },
@@ -343,6 +343,7 @@ class MongoMonitorsRepository implements IMonitorsRepository {
selectedDisks: doc.selectedDisks ?? [],
gameId: doc.gameId ?? undefined,
group: doc.group ?? null,
locations: doc.locations ?? [],
recentChecks: (doc.recentChecks ?? []).map((check: any) => this.toCheckSnapshot(check)),
createdAt: toDateString(doc.createdAt),
updatedAt: toDateString(doc.updatedAt),
@@ -398,6 +399,7 @@ class MongoMonitorsRepository implements IMonitorsRepository {
selectedDisks: doc.selectedDisks ?? [],
gameId: doc.gameId ?? undefined,
group: doc.group ?? null,
locations: doc.locations ?? [],
recentChecks: (doc.recentChecks ?? []).map((check: any) => this.toCheckSnapshot(check)),
createdAt: toDateString(doc.createdAt),
updatedAt: toDateString(doc.updatedAt),
+3
View File
@@ -21,6 +21,9 @@ class MonitorRoutes {
this.router.get("/team/with-checks", this.monitorController.getMonitorsWithChecksByTeamId);
this.router.get("/team/groups", this.monitorController.getGroupsByTeamId);
// Globalping locations
this.router.get("/globalping/locations", this.monitorController.getGlobalpingLocations);
// Uptime routes
this.router.get("/uptime/details/:monitorId", this.monitorController.getUptimeDetailsById);
+2 -1
View File
@@ -37,7 +37,7 @@ class CheckService {
};
buildCheck = (statusResponse: MonitorStatusResponse<PageSpeedStatusPayload | HardwareStatusPayload | undefined>) => {
const { monitorId, teamId, type, status, responseTime, code, message, payload, timings } = statusResponse;
const { monitorId, teamId, type, status, responseTime, code, message, payload, timings, location } = statusResponse;
const check: Partial<Check> = {
id: new Types.ObjectId().toString(),
@@ -46,6 +46,7 @@ class CheckService {
monitorId,
teamId,
type,
...(location ? { location } : {}),
},
status,
statusCode: code,
@@ -222,6 +222,20 @@ export class MonitorService implements IMonitorService {
throw new AppError({ message: `${monitor.type} monitors are not supported for uptime details`, status: 400 });
}
// Fetch location checks if monitor has locations configured
let locationChecks: Record<string, any> | undefined;
if (monitor.locations && monitor.locations.length > 0) {
const locData = await this.checksRepository.findLocationChecksByMonitorId(
monitor.id,
start,
end,
this.getDateFormat(rangeKey)
);
if (Object.keys(locData).length > 0) {
locationChecks = locData;
}
}
return {
monitorData: {
monitor,
@@ -230,6 +244,7 @@ export class MonitorService implements IMonitorService {
groupedDownChecks: NormalizeDataUptimeDetails(checksData.groupedDownChecks, 10, 100),
groupedAvgResponseTime: checksData.avgResponseTime,
groupedUptimePercentage: checksData.uptimePercentage,
...(locationChecks ? { locationChecks } : {}),
},
monitorStats,
};
@@ -4,6 +4,7 @@ import { AppError } from "@/utils/AppError.js";
import { INetworkService, INotificationsService, IStatusService } from "@/service/index.js";
import type { StatusChangeResult, MonitorStatusResponse, HardwareStatusPayload, MonitorStatus } from "@/types/index.js";
import IncidentService from "@/service/business/incidentService.js";
import type GlobalpingService from "@/service/infrastructure/globalpingService.js";
import {
IMaintenanceWindowsRepository,
IMonitorsRepository,
@@ -37,6 +38,7 @@ class SuperSimpleQueueHelper {
private checkService: any;
private buffer: any;
private incidentService: IncidentService;
private globalpingService: GlobalpingService;
private maintenanceWindowsRepository: IMaintenanceWindowsRepository;
private monitorsRepository: IMonitorsRepository;
private teamsRepository: ITeamsRepository;
@@ -52,6 +54,7 @@ class SuperSimpleQueueHelper {
checkService,
buffer,
incidentService,
globalpingService,
maintenanceWindowsRepository,
monitorsRepository,
teamsRepository,
@@ -66,6 +69,7 @@ class SuperSimpleQueueHelper {
checkService: any;
buffer: any;
incidentService: IncidentService;
globalpingService: GlobalpingService;
maintenanceWindowsRepository: IMaintenanceWindowsRepository;
monitorsRepository: IMonitorsRepository;
teamsRepository: ITeamsRepository;
@@ -80,6 +84,7 @@ class SuperSimpleQueueHelper {
this.buffer = buffer;
this.notificationsService = notificationsService;
this.incidentService = incidentService;
this.globalpingService = globalpingService;
this.maintenanceWindowsRepository = maintenanceWindowsRepository;
this.monitorsRepository = monitorsRepository;
this.teamsRepository = teamsRepository;
@@ -122,6 +127,27 @@ class SuperSimpleQueueHelper {
throw new Error("No network response");
}
// Step 2b. Run Globalping checks (fire-and-forget, doesn't affect local check pipeline)
if (monitor.locations && monitor.locations.length > 0 && (monitor.type === "http" || monitor.type === "ping")) {
this.globalpingService
.runChecks(monitor)
.then((locationStatuses) => {
for (const locStatus of locationStatuses) {
const locCheck = this.checkService.buildCheck(locStatus);
if (locCheck) {
this.buffer.addToBuffer(locCheck);
}
}
})
.catch((err: any) => {
this.logger.warn({
message: `Globalping checks failed for monitor ${monitorId}: ${err.message}`,
service: SERVICE_NAME,
method: "getMonitorJob",
});
});
}
// Step 3. Build check
const check = await this.checkService.buildCheck(status);
if (!check) {
@@ -0,0 +1,208 @@
import { Globalping } from "globalping";
import type { ISettingsService } from "@/service/system/settingsService.js";
import type { Monitor } from "@/types/monitor.js";
import type { MonitorStatusResponse } from "@/types/network.js";
const SERVICE_NAME = "GlobalpingService";
const LOCATION_MAP: Record<string, { continent: string }> = {
"north-america": { continent: "NA" },
europe: { continent: "EU" },
asia: { continent: "AS" },
"south-america": { continent: "SA" },
oceania: { continent: "OC" },
africa: { continent: "AF" },
};
export const GLOBALPING_LOCATIONS = [
{ id: "north-america", label: "North America" },
{ id: "europe", label: "Europe" },
{ id: "asia", label: "Asia" },
{ id: "south-america", label: "South America" },
{ id: "oceania", label: "Oceania" },
{ id: "africa", label: "Africa" },
];
class GlobalpingService {
static SERVICE_NAME = SERVICE_NAME;
private logger: any;
private settingsService: ISettingsService;
private client: Globalping<false> | null = null;
private lastApiKey: string | undefined;
constructor({ settingsService, logger }: { settingsService: ISettingsService; logger: any }) {
this.settingsService = settingsService;
this.logger = logger;
}
get serviceName() {
return GlobalpingService.SERVICE_NAME;
}
private async getClient(): Promise<Globalping<false> | null> {
const dbSettings = await this.settingsService.getDBSettings();
const apiKey = dbSettings.globalpingApiKey;
if (!apiKey) {
return null;
}
if (this.client && this.lastApiKey === apiKey) {
return this.client;
}
this.client = new Globalping({ auth: apiKey, throwApiErrors: false, timeout: 30000 });
this.lastApiKey = apiKey;
return this.client;
}
async runChecks(monitor: Monitor): Promise<MonitorStatusResponse[]> {
if (!monitor.locations || monitor.locations.length === 0) {
return [];
}
const client = await this.getClient();
if (!client) {
this.logger.warn({
message: "Globalping API key not configured, skipping location checks",
service: SERVICE_NAME,
method: "runChecks",
});
return [];
}
const measurementType = monitor.type === "ping" ? "ping" : "http";
const monitorUrl = monitor.url ?? "";
// Parse target from monitor URL
let target: string;
try {
if (measurementType === "http") {
const url = new URL(monitorUrl);
target = url.hostname;
} else {
target = monitorUrl.replace(/^https?:\/\//, "").split("/")[0] ?? monitorUrl;
}
} catch {
target = monitorUrl;
}
const locations = monitor.locations
.map((loc) => LOCATION_MAP[loc])
.filter(Boolean);
if (locations.length === 0) {
return [];
}
try {
const createResult = measurementType === "http"
? await client.createMeasurement({
type: "http" as const,
target,
locations: locations as any,
measurementOptions: { request: { method: "HEAD" }, protocol: "HTTPS" },
})
: await client.createMeasurement({
type: "ping" as const,
target,
locations: locations as any,
});
if (!createResult.ok) {
this.logger.warn({
message: "Failed to create Globalping measurement",
service: SERVICE_NAME,
method: "runChecks",
details: JSON.stringify(createResult.data),
});
return [];
}
const measurementId = (createResult.data as any).id;
const awaitResult = await client.awaitMeasurement(measurementId);
if (!awaitResult.ok) {
this.logger.warn({
message: "Failed to await Globalping measurement",
service: SERVICE_NAME,
method: "runChecks",
details: JSON.stringify(awaitResult.data),
});
return [];
}
const measurement = awaitResult.data as any;
const results: MonitorStatusResponse[] = [];
for (const item of measurement.results || []) {
const probe = item.probe;
const result = item.result;
const locationLabel = this.getLocationLabel(probe?.continent, probe?.country);
if (measurementType === "http") {
results.push({
monitorId: monitor.id,
teamId: monitor.teamId,
type: monitor.type,
status: result.statusCode >= 200 && result.statusCode < 400,
code: result.statusCode || 0,
message: result.statusCodeName || result.rawOutput || "",
responseTime: result.timings?.total ?? 0,
location: locationLabel,
});
} else {
// Ping
const stats = result.stats;
results.push({
monitorId: monitor.id,
teamId: monitor.teamId,
type: monitor.type,
status: stats?.loss !== undefined ? stats.loss < 100 : false,
code: stats?.loss === 0 ? 200 : 5000,
message: stats?.loss === 0 ? "Ping successful" : `Packet loss: ${stats?.loss}%`,
responseTime: stats?.avg ?? 0,
location: locationLabel,
});
}
}
return results;
} catch (error: any) {
this.logger.warn({
message: `Globalping check failed: ${error.message}`,
service: SERVICE_NAME,
method: "runChecks",
stack: error.stack,
});
return [];
}
}
private getLocationLabel(continent?: string, country?: string): string {
if (continent && country) {
return `${continent}-${country}`;
}
return continent || country || "unknown";
}
async getLimits(): Promise<any | null> {
const client = await this.getClient();
if (!client) {
return null;
}
try {
const result = await client.getLimits();
if (result.ok) {
return result.data;
}
return null;
} catch {
return null;
}
}
}
export default GlobalpingService;
+1
View File
@@ -6,6 +6,7 @@ export interface CheckMetadata {
monitorId: string;
teamId: string;
type: MonitorType;
location?: string;
}
export interface CheckCpuInfo {
+8
View File
@@ -43,6 +43,7 @@ export interface Monitor {
selectedDisks: string[];
gameId?: string;
group: string | null;
locations: string[];
recentChecks: CheckSnapshot[];
createdAt: string;
updatedAt: string;
@@ -64,6 +65,12 @@ export interface MonitorsWithChecksByTeamIdResult {
monitors: Monitor[];
}
export interface LocationCheckData {
groupedChecks: import("./check.js").GroupedCheck[];
uptimePercentage: number;
avgResponseTime: number;
}
export interface UptimeDetailsResult {
monitorData: {
monitor: Monitor;
@@ -72,6 +79,7 @@ export interface UptimeDetailsResult {
groupedDownChecks: import("./check.js").GroupedCheck[];
groupedAvgResponseTime: number;
groupedUptimePercentage: number;
locationChecks?: Record<string, LocationCheckData>;
};
monitorStats: import("./monitorStats.js").MonitorStats | null;
}
+1
View File
@@ -34,6 +34,7 @@ export interface MonitorStatusResponse<T = any> {
matchMethod?: MonitorMatchMethod;
expectedValue?: string;
extracted?: unknown;
location?: string;
}
export interface PingStatusPayload {
+1
View File
@@ -24,6 +24,7 @@ export interface Settings {
systemEmailRequireTLS: boolean;
systemEmailRejectUnauthorized: boolean;
showURL: boolean;
globalpingApiKey?: string;
singleton: boolean;
version: number;
globalThresholds?: SettingsThresholds;
+3
View File
@@ -172,6 +172,7 @@ const createMonitorBodyValidation = joi.object({
gameId: joi.string().allow(""),
selectedDisks: joi.array().items(joi.string()).optional(),
group: joi.string().max(50).trim().allow(null, "").optional(),
locations: joi.array().items(joi.string()).max(5).optional(),
});
const createMonitorsBodyValidation = joi.array().items(
@@ -203,6 +204,7 @@ const editMonitorBodyValidation = joi
gameId: joi.string().allow(""),
selectedDisks: joi.array().items(joi.string()).optional(),
group: joi.string().max(50).trim().allow(null, "").optional(),
locations: joi.array().items(joi.string()).max(5).optional(),
})
.options({ stripUnknown: true });
@@ -428,6 +430,7 @@ const updateAppSettingsBodyValidation = joi.object({
systemEmailRequireTLS: joi.boolean(),
systemEmailRejectUnauthorized: joi.boolean(),
globalpingApiKey: joi.string().allow(""),
globalThresholds: joi
.object({
cpu: joi.number().min(1).max(100).allow(""),