본문으로 건너뛰기

Alert Silence API

개요​

Alert Silence API는 특정 조건에 맞는 Alert를 일시적으로 음소거(Silence)하는 기능을 제공합니다. 유지보수 작업 중이나 예상된 경보를 억제할 때 사용합니다.

기본 정보​

항목값
기본 경로/api/v1.0/alert-silence
인증불필요
버전v1.0

엔드포인트 요약​

메서드경로설명
GET/api/v1.0/alert-silence모든 Silence 목록 조회
GET/api/v1.0/alert-silence/active활성 Silence 목록 조회
POST/api/v1.0/alert-silenceSilence 추가
DELETE/api/v1.0/alert-silence/{id}Silence 제거

상세 엔드포인트​

GET /api/v1.0/alert-silence​

모든 Silence 목록을 조회합니다 (활성/비활성 포함).

요청

파라미터 없음

응답

[
  {
    "silenceId": "550e8400-e29b-41d4-a716-446655440000",
    "sourceType": "Equipment",
    "sourceIdPattern": "Equipment-01",
    "reason": "Scheduled maintenance",
    "createdBy": "Admin",
    "createdAt": "2026-02-09T08:00:00Z",
    "startsAt": "2026-02-09T10:00:00Z",
    "endsAt": "2026-02-09T14:00:00Z"
  }
]

응답 코드

코드설명
200성공 (빈 배열도 200 반환)
500서버 내부 오류

GET /api/v1.0/alert-silence/active​

현재 활성화된 Silence 목록만 조회합니다 (현재 시각이 startsAt와 endsAt 사이).

요청

파라미터 없음

응답

[
  {
    "silenceId": "550e8400-e29b-41d4-a716-446655440000",
    "sourceType": "Equipment",
    "sourceIdPattern": "Equipment-01",
    "reason": "Scheduled maintenance",
    "createdBy": "Admin",
    "createdAt": "2026-02-09T08:00:00Z",
    "startsAt": "2026-02-09T10:00:00Z",
    "endsAt": "2026-02-09T14:00:00Z"
  }
]

응답 코드

코드설명
200성공
500서버 내부 오류

POST /api/v1.0/alert-silence​

새로운 Silence를 추가합니다.

요청 본문

{
  "sourceType": "Equipment",
  "sourceIdPattern": "Equipment-*",
  "reason": "Scheduled maintenance",
  "createdBy": "John Doe",
  "startsAt": "2026-02-09T10:00:00Z",
  "endsAt": "2026-02-09T14:00:00Z"
}

요청 필드

필드타입필수설명
sourceTypestringYAlert 소스 타입 (Equipment, Sensor 등)
sourceIdPatternstringY소스 ID 패턴 (와일드카드 * 지원)
reasonstringYSilence 사유
createdBystringN생성자 이름 (기본값: "Admin")
startsAtDateTimeYSilence 시작 시간 (UTC)
endsAtDateTimeYSilence 종료 시간 (UTC)

응답

{
  "silenceId": "550e8400-e29b-41d4-a716-446655440000",
  "sourceType": "Equipment",
  "sourceIdPattern": "Equipment-*",
  "reason": "Scheduled maintenance",
  "createdBy": "John Doe",
  "createdAt": "2026-02-09T08:00:00Z",
  "startsAt": "2026-02-09T10:00:00Z",
  "endsAt": "2026-02-09T14:00:00Z"
}

응답 코드

코드설명
201Silence 생성 성공
400잘못된 요청 (필수 필드 누락, 날짜 오류)
500서버 내부 오류

DELETE /api/v1.0/alert-silence/{id}​

Silence를 제거합니다.

요청

파라미터타입필수설명
idstringYSilence ID (GUID, 경로 파라미터)

응답

응답 본문 없음

응답 코드

코드설명
204Silence 제거 성공
404Silence를 찾을 수 없음 (이미 제거됨)
500서버 내부 오류

DTO 정의​

CreateSilenceRequest​

속성타입설명
sourceTypestringAlert 소스 타입
sourceIdPatternstring소스 ID 패턴 (와일드카드 * 지원)
reasonstringSilence 사유
createdBystring?생성자 이름 (선택, 기본값: "Admin")
startsAtDateTimeSilence 시작 시간 (UTC)
endsAtDateTimeSilence 종료 시간 (UTC)

AlertSilence​

속성타입설명
silenceIdstringSilence 고유 식별자 (GUID)
sourceTypestringAlert 소스 타입
sourceIdPatternstring소스 ID 패턴
reasonstringSilence 사유
createdBystring생성자 이름
createdAtDateTime생성 시간 (UTC)
startsAtDateTimeSilence 시작 시간 (UTC)
endsAtDateTimeSilence 종료 시간 (UTC)

사용 예제​

C# (HttpClient)​

using System.Net.Http.Json;

var client = new HttpClient { BaseAddress = new Uri("https://localhost:5001") };

// Silence 추가
var request = new CreateSilenceRequest
{
    SourceType = "Equipment",
    SourceIdPattern = "Equipment-01",
    Reason = "Scheduled maintenance",
    CreatedBy = "John Doe",
    StartsAt = DateTime.UtcNow.AddHours(1),
    EndsAt = DateTime.UtcNow.AddHours(5)
};

var response = await client.PostAsJsonAsync("/api/v1.0/alert-silence", request);
if (response.IsSuccessStatusCode)
{
    var silence = await response.Content.ReadFromJsonAsync<AlertSilence>();
    Console.WriteLine($"Silence 생성됨: {silence.SilenceId}");
}

// 활성 Silence 조회
var activeSilences = await client.GetFromJsonAsync<List<AlertSilence>>(
    "/api/v1.0/alert-silence/active");

foreach (var silence in activeSilences)
{
    Console.WriteLine($"{silence.SourceIdPattern}: {silence.Reason}");
}

// Silence 제거
await client.DeleteAsync($"/api/v1.0/alert-silence/{silence.SilenceId}");

curl​

# Silence 추가
curl -X POST "https://localhost:5001/api/v1.0/alert-silence" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceType": "Equipment",
    "sourceIdPattern": "Equipment-01",
    "reason": "Scheduled maintenance",
    "createdBy": "John Doe",
    "startsAt": "2026-02-09T10:00:00Z",
    "endsAt": "2026-02-09T14:00:00Z"
  }'

# 활성 Silence 조회
curl -X GET "https://localhost:5001/api/v1.0/alert-silence/active"

# Silence 제거
curl -X DELETE "https://localhost:5001/api/v1.0/alert-silence/550e8400-e29b-41d4-a716-446655440000"

JavaScript (Fetch)​

// Silence 추가
const silence = await fetch('https://localhost:5001/api/v1.0/alert-silence', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    sourceType: 'Equipment',
    sourceIdPattern: 'Equipment-*',
    reason: 'Scheduled maintenance',
    createdBy: 'John Doe',
    startsAt: new Date(Date.now() + 3600000).toISOString(), // +1 hour
    endsAt: new Date(Date.now() + 18000000).toISOString()   // +5 hours
  })
}).then(res => res.json());

console.log('Silence 생성됨:', silence.silenceId);

// 활성 Silence 조회
const activeSilences = await fetch('https://localhost:5001/api/v1.0/alert-silence/active')
  .then(res => res.json());

// Silence 제거
await fetch(`https://localhost:5001/api/v1.0/alert-silence/${silence.silenceId}`, {
  method: 'DELETE'
});

패턴 매칭​

sourceIdPattern은 와일드카드 *를 지원합니다:

  • Equipment-01: 정확히 일치
  • Equipment-*: Equipment- 접두사로 시작하는 모든 소스
  • *-Sensor: -Sensor 접미사로 끝나는 모든 소스
  • *: 모든 소스 (주의 필요)

주의사항​

  • startsAt는 endsAt보다 이전이어야 합니다.
  • Silence가 만료된 후에도 자동으로 제거되지 않으며, 목록 조회에는 계속 나타납니다 (활성 조회 제외).
  • 와일드카드 *는 과도하게 사용하면 의도하지 않은 Alert까지 음소거할 수 있으므로 주의하세요.
  • Silence 생성 시각(createdAt)은 서버에서 자동으로 설정됩니다.

유스케이스​

유지보수 작업 중 Alert 음소거​

// 특정 장비의 모든 Alert를 4시간 동안 음소거
var maintenanceSilence = new CreateSilenceRequest
{
    SourceType = "Equipment",
    SourceIdPattern = "Equipment-01",
    Reason = "Motor replacement maintenance",
    CreatedBy = "Maintenance Team",
    StartsAt = DateTime.UtcNow,
    EndsAt = DateTime.UtcNow.AddHours(4)
};

await client.PostAsJsonAsync("/api/v1.0/alert-silence", maintenanceSilence);

특정 센서 그룹 음소거​

// Temp-로 시작하는 모든 온도 센서 Alert 음소거
var sensorSilence = new CreateSilenceRequest
{
    SourceType = "Sensor",
    SourceIdPattern = "Temp-*",
    Reason = "Sensor calibration in progress",
    CreatedBy = "Engineering Team",
    StartsAt = DateTime.UtcNow,
    EndsAt = DateTime.UtcNow.AddHours(2)
};

await client.PostAsJsonAsync("/api/v1.0/alert-silence", sensorSilence);

관련 API​