Dokumentacja API: Monitorowanie i AI

Ta strona dokumentuje usługę Monitorowania (openapi-monitor.yaml, port 8085) oraz proxowane usługi AI Copilot, Silnika Migracji i konektorów CDC. Usługa Monitorowania udostępniana jest pod ścieżką /api/v1 i wymaga tokenu JWT bearerAuth na każdym endpoincie.

Panel

Endpointy panelu agregują metryki platformy, stan konektorów oraz stan systemu.

DashboardMetrics zawiera totalPipelinesRun, successRate, avgDurationMs, rowsProcessed, activeAlerts, pipelinesByStatus, recentRuns[], topErrors[], connectorHealth[], timeSeriesData[]. PipelineMetricsDetail dodaje czasy trwania p50/p95/p99 oraz slaComplianceRate.

// GET /api/v1/monitor/dashboard  →  200 OK  (DashboardResponse)
{
  "totalPipelinesRun": 1284,
  "successRate": 0.973,
  "avgDurationMs": 184200,
  "rowsProcessed": 9821044,
  "activeAlerts": 3,
  "pipelinesByStatus": { "SUCCESS": 1249, "FAILED": 28, "RUNNING": 7 },
  "recentRuns": [],
  "topErrors": []
}

// GET /api/v1/monitor/pipelines/{id}/metrics  →  200 OK  (PipelineMetricsDetail)
{
  "pipelineId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "p50DurationMs": 162000,
  "p95DurationMs": 240000,
  "p99DurationMs": 318000,
  "slaComplianceRate": 0.991
}

Alerty

Endpointy alertów zarządzają poszczególnymi rekordami alertów, w tym operacjami zbiorczymi, historią i czyszczeniem.

getAlerts przyjmuje status, severity, category oraz limit (domyślnie 100). getAlertHistory przyjmuje category oraz sinceSeconds (domyślnie 86400). purgeResolved przyjmuje olderThanSeconds (domyślnie 604800). Alert.severity: CRITICAL | WARNING | INFO; status: ACTIVE | ACKNOWLEDGED | RESOLVED; category: PIPELINE_FAILURE | PERFORMANCE_DEGRADATION | SECURITY_VIOLATION | DATA_QUALITY | SYSTEM_HEALTH | SLA_BREACH.

// POST /api/v1/monitor/alerts  →  201 Created
// Request: CreateAlertRequest
{
  "title": "Pipeline billing-daily-load failed",
  "severity": "CRITICAL",
  "category": "PIPELINE_FAILURE",
  "message": "Task 'load' failed after 3 retries"
}

// POST /api/v1/monitor/alerts/bulk/ack  →  200 OK
// Request: BulkAlertRequest
{ "alertIds": ["al-0001", "al-0002", "al-0003"] }

// GET /api/v1/monitor/alerts/summary  →  200 OK  (AlertSummaryResponse)
{
  "active": 3,
  "acknowledged": 5,
  "resolved": 142,
  "bySeverity": { "CRITICAL": 1, "WARNING": 2, "INFO": 0 }
}

Definicje alertów

Definicje alertów to reusowalne reguły, które silnik ocenia w celu generowania zdarzeń alertów.

getDefinitions przyjmuje type oraz enabled (bool). AlertDefinition.type: PIPELINE_FAILURE | SLA_BREACH | DATA_QUALITY | ROW_COUNT_ANOMALY | CONNECTION_DOWN | RESOURCE_THRESHOLD. Każda definicja zawiera AlertCondition (metric, operator ∈ GREATER_THAN | LESS_THAN | EQUAL | …, threshold, windowMinutes, consecutiveFailures) oraz recipients[] (NotificationRecipient z channel ∈ EMAIL | SLACK | PAGERDUTY | WEBHOOK).

// POST /api/v1/monitor/alerts/definitions  →  201 Created
// Request: AlertDefinition
{
  "name": "Billing SLA breach",
  "type": "SLA_BREACH",
  "enabled": true,
  "condition": {
    "metric": "duration_ms",
    "operator": "GREATER_THAN",
    "threshold": 300000,
    "windowMinutes": 60,
    "consecutiveFailures": 1
  },
  "recipients": [
    { "channel": "PAGERDUTY", "target": "routing-key-billing" }
  ]
}

// POST /api/v1/monitor/alerts/definitions/{id}/silence  →  200 OK
// Request: { "durationMinutes": 120 }
{
  "id": "def-0001",
  "name": "Billing SLA breach",
  "enabled": true,
  "silencedUntil": "2025-12-15T16:30:00Z"
}

Zdarzenia alertów

Zdarzenia alertów to poszczególne wyzwolenia generowane przez silnik, gdy warunek definicji zostanie spełniony.

getEvents przyjmuje status, severity, type. getEventHistory przyjmuje definitionId (uuid), from/to (date-time), limit (domyślnie 100). acknowledgeEvent i resolveEvent przyjmują treść {user}; silenceEvent przyjmuje treść {durationMinutes}. AlertEvent.status: FIRING | ACKNOWLEDGED | RESOLVED; zawiera metricValue, threshold, firedAt, metadane potwierdzenia/rozwiązania oraz silencedUntil.

// GET /api/v1/monitor/alerts/events/{id}  →  200 OK  (AlertEvent)
{
  "id": "ev-0042",
  "definitionId": "def-0001",
  "status": "FIRING",
  "metricValue": 342000,
  "threshold": 300000,
  "firedAt": "2025-12-15T14:30:00Z",
  "silencedUntil": null
}

// POST /api/v1/monitor/alerts/events/{id}/ack  →  200 OK
// Request: { "user": "u-1001" }
{
  "id": "ev-0042",
  "status": "ACKNOWLEDGED",
  "acknowledgedBy": "u-1001"
}

Strumienie SSE (czas rzeczywisty)

Usługa Monitorowania udostępnia strumienie Server-Sent Events dla alertów i metryk w czasie rzeczywistym. Są one routowane przez bramę za pośrednictwem prefiksu przejścia SSE /api/v1/monitor/sse/**.

streamAlerts przyjmuje parametr zapytania severity (filtr rozdzielony przecinkami) i zwraca text/event-stream. Jego typy zdarzeń to connected (początkowe potwierdzenie zawierające subscriberId), alert (ładunek JSON alertu) oraz heartbeat (utrzymanie połączenia). Połączenie wygasa po 30 minutach.

// GET /api/v1/monitor/sse/alerts?severity=CRITICAL,WARNING
event: connected
data: {"subscriberId":"sub-7c2e","at":"2025-12-15T14:30:00Z"}

event: alert
data: {"id":"al-0099","severity":"CRITICAL","title":"Connector teradata-prod down"}

event: heartbeat
data: {}

Kanały powiadomień

Kanały powiadomień dostarczają alerty do zewnętrznych miejsc docelowych.

listNotificationChannels przyjmuje workspaceId (uuid), channelType oraz enabled (bool). NotificationChannelDto.channelType: EMAIL | SLACK | PAGERDUTY | WEBHOOK | TEAMS. Obiekt config jest specyficzny dla kanału — EMAIL → recipients, SLACK/TEAMS → webhookUrl, PAGERDUTY → routingKey, WEBHOOK → url.

// POST /api/v1/monitor/channels  →  201 Created
// Request: NotificationChannelDto
{
  "name": "Billing team Slack",
  "channelType": "SLACK",
  "enabled": true,
  "config": { "webhookUrl": "https://hooks.slack.com/services/T000/B000/XXXX" }
}

// POST /api/v1/monitor/channels/{id}/test  →  200 OK  (ChannelTestResult)
{
  "success": true,
  "message": "Test notification delivered",
  "testedAt": "2025-12-15T14:30:00Z"
}

AI Copilot

Usługa Copilot (port 8086) jest proxowana przez bramę. Jest udostępniana przez pojedynczą operację-zaślepkę bramy, a nie poprzez formalną specyfikację OpenAPI.

// GET /api/v1/ai/copilot  →  200 OK
{
  "service": "copilot",
  "status": "available"
}

Silnik Migracji

Usługa Migracji (port 8087) jest proxowana przez bramę i udostępnia plany migracji.

// GET /api/v1/migration/plans  →  200 OK
{
  "plans": [
    { "id": "mig-0001", "name": "Teradata → Snowflake DWH migration", "status": "IN_PROGRESS" }
  ]
}

Konektory CDC

Operacje konektorów CDC są proxowane do Connector SDK (port 8088).

deployCdcConnector przyjmuje ogólny obiekt jako treść i zwraca 201 Created.

// POST /api/v1/cdc/connectors  →  201 Created
// Request: generic connector configuration object
{
  "name": "oracle-orders-cdc",
  "sourceType": "ORACLE",
  "tables": ["SALES.ORDERS", "SALES.ORDER_ITEMS"]
}

// GET /api/v1/cdc/health  →  200 OK
{
  "status": "UP",
  "connectors": 6,
  "running": 6,
  "failed": 0
}