Enhanced Alert

OvenMediaEngine Enterprise 0.18.3.2-1 버전부터 Enhanced Alert 기능을 지원합니다.

Enhanced Alert는 Stream 또는 System에서 이상 징후와 관심 패턴을 탐지하고 사용자에게 Notification을 전송하는 Module입니다. 사전 정의된 규칙으로 이상 징후와 관심 패턴을 설정할 수 있으며, 조건이 충족되면 Module이 사용자의 Notification Server로 HTTP(S) Request를 전송합니다.

Enhanced Alert 설정하기

Enhanced Alert는 아래와 같이 <Server>에서 설정할 수 있습니다:

<Server version="8">
	<Alert>
		<Url>http://192.168.0.161:9595/alert/notification</Url>
		<SecretKey>1234</SecretKey>
		<Timeout>3000</Timeout>
		<RulesFile>AlertRules.xml</RulesFile>
		<Rules>
			<Ingress>
				<StreamStatus />
				<MinBitrate>2000000</MinBitrate>
				<MaxBitrate>4000000</MaxBitrate>
				<MinFramerate>15</MinFramerate>
				<MaxFramerate>60</MaxFramerate>
				<MinWidth>1280</MinWidth>
				<MinHeight>720</MinHeight>
				<MaxWidth>1920</MaxWidth>
				<MaxHeight>1080</MaxHeight>
				<MinSamplerate>16000</MinSamplerate>
				<MaxSamplerate>50400</MaxSamplerate>
				<LongKeyFrameInterval />
				<HasBFrames />
			</Ingress>
			<Egress>
				<StreamStatus />
				<LLHLSReady />
				<HLSReady />
			</Egress>
			<InternalQueueCongestion />
		</Rules>
	</Alert>
</Server>

Key	Description
Url	Notification을 수신할 HTTP Server 주소입니다. HTTP와 HTTPS를 모두 지원합니다.
SecretKey	HMAC-SHA1 암호화에 사용되는 Secret Key입니다. 자세한 내용은 아래 Security를 참고하십시오.
Timeout	요청 전송 후 응답을 대기하는 시간입니다. 단위는 밀리초입니다.
RulesFile	(Optional) Alert 탐지 규칙이 정의된 별도의 외부 파일을 참조합니다.
Rules	(Optional) 탐지할 이상 징후 및 관심 패턴을 정의합니다. < RulesFile>이 지정된 경우, <RulesFile>을우선합니다.

Rules File 설정하기

탐지할 이상 징후와 관심 패턴을 별도의 파일로 정의할 수 있습니다. OvenMediaEngine Enterprise는 Rules File의 변경 사항을 모니터링하고, 서비스 재시작 없이 즉시 적용합니다. 운영 중에 규칙을 자주 수정해야 한다면 <RulesFile> 사용을 권장합니다.

<?xml version="1.0" encoding="UTF-8"?>
<Rules>
	<Ingress>
		<StreamStatus />
		<MinBitrate>2000000</MinBitrate>
		<MaxBitrate>4000000</MaxBitrate>
		<MinFramerate>15</MinFramerate>
		<MaxFramerate>60</MaxFramerate>
		<MinWidth>1280</MinWidth>
		<MinHeight>720</MinHeight>
		<MaxWidth>1920</MaxWidth>
		<MaxHeight>1080</MaxHeight>
		<MinSamplerate>16000</MinSamplerate>
		<MaxSamplerate>50400</MaxSamplerate>
		<LongKeyFrameInterval />
		<HasBFrames />
	</Ingress>
	<Egress>
		<StreamStatus />
		<LLHLSReady />
		<HLSReady />
	</Egress>
	<InternalQueueCongestion />
</Rules>

Rules

Key		Description
Ingress	StreamStatus	Ingress Stream의 생성, 준비 완료, 실패, 삭제 상태를 감지합니다.
	MinBitrate	Ingress Stream의 Video Bitrate가 설정값보다 낮을 때 감지합니다.
	MaxBitrate	Ingress Stream의 Video Bitrate가 설정값보다 높을 때 감지합니다.
	MinFramerate	Ingress Stream의 Framerate가 설정값보다 낮을 때 감지합니다.
	MaxFramerate	Ingress Stream의 Framerate가 설정값보다 높을 때 감지합니다.
	MinWidth	Ingress Stream의 가로 해상도 (Width)가 설정값보다 작을 때 감지합니다.
	MaxWidth	Ingress Stream의 가로 해상도 (Width)가 설정값보다 클 때 감지합니다.
	MinHeight	Ingress Stream의 세로 해상도 (Height)가 설정값보다 작을 때 감지합니다.
	MaxHeight	Ingress Stream의 세로 해상도 (Height)가 설정값보다 클 때 감지합니다.
	MinSamplerate	Ingress Stream의 Audio Samplerate가 설정값보다 낮을 때 감지합니다.
	MaxSamplerate	Ingress Stream의 Audio Samplerate가 설정값보다 높을 때 감지합니다.
	LongKeyFrameInterval	Ingress Stream의 Keyframe Interval이 너무 길 때 감지합니다. 기준은 4초 초과입니다.
	HasBFrames	Ingress Stream에 B-frame이 포함되어 있을 때 감지합니다.
Egress	StreamStatus	Egress Stream의 생성, 준비 완료, 실패, 삭제 상태를 감지합니다.
	LLHLSReady	Low-Latency HLS 재생이 가능해지는 시점을 감지합니다.
	HLSReady	HLS 재생이 가능해지는 시점을 감지합니다.
InternalQueueCongestion		내부 큐가 혼잡한 상황을 감지합니다.

Notification 구성 알아보기

Request

POST /configured/target/url HTTP/1.1
Content-Length: 1037
Content-Type: application/json
Accept: application/json
X-OME-Signature: f871jd991jj1929jsjd91pqa0amm1
{
  "sourceUri": "#default#app/stream",
  "messages": [
    {
      "code": "INGRESS_HAS_BFRAME",
      "description": "There are B-Frames in the ingress stream."
    },
    {
      "code": "INGRESS_BITRATE_LOW",
      "description": "The ingress stream's current bitrate (316228 bps) is lower than the configured bitrate (2000000 bps)"
    }
  ],
  "sourceInfo": {
    "createdTime": "2023-04-07T21:15:24.487+09:00",
    "sourceType": "Rtmp",
    "sourceUrl": "TCP://192.168.0.220:10639",
    "tracks": [
      {
        "id": 0,
        "name": "Video",
        "type": "Video",
        "video": {
          "bitrate": 300000,
          "bypass": false,
          "codec": "H264",
          "framerate": 30.0,
          "hasBframes": true,
          "height": 1080,
          "keyFrameInterval": 0,
          "width": 1920
        }
      },
      {
        "audio": {
          "bitrate": 160000,
          "bypass": false,
          "channel": 1,
          "codec": "AAC",
          "samplerate": 48000
        },
        "id": 1,
        "name": "Audio",
        "type": "Audio"
      },
      {
        "id": 2,
        "name": "Data",
        "type": "Data"
      }
    ]
  },
  "type": "INGRESS"
}

Element

다음은 JSON Payload의 각 Element에 대한 상세 설명입니다:

Element	Description
messages	Rules에 의해 감지된 Messages 목록입니다.
type	JSON Payload의 형식을 나타냅니다. 값에 따라 포함되는 Element의 정보가 달라질 수 있습니다.
sourceUri	감지된 Source의 URI 정보입니다. INGRESS: #<vhost>#<application>/<input_stream> EGRESS: #<vhost>#<application>/<output_stream>
sourceInfo	감지 시점의 Source 상세 정보입니다. 형식은 해당 Source를 REST API로 정보 조회한 응답과 동일합니다.
parentSourceUri	감지된 Source의 상위 레벨의 Source URI 정보입니다.
parentSourceInfo	감지 된 Source의 상황에 따라 상세 정보가 없을 수 있습니다. 이럴 때 Source를 추적 할 수 있도록 Source와 연결 된 상위 레벨의 Source에 대한 상세 정보입니다.

Additional Element (EGRESS_STREAM_CREATION_FAILED)

다음은 Egress Stream 생성 실패 시 제공되는 추가 정보입니다.

Element	Description
outputProfile	Egress Stream 생성이 실패하게 된 설정정보입니다.
codecModules	Decoder, Encoder, Filter에 문제가 있는 경우의 해당 모듈 정보입니다.

{
  "messages": [
    {
      "code": "EGRESS_STREAM_CREATION_FAILED_FILTER",
      "description": "Failed to create egress stream because the filter could not be created"
    }
  ],  
  "codecModules": [
    {
      "busId": "18:01.0",
      "displayName": "Xilinx Corporation Device 513d",
      "id": 0,
      "isDecoder": true,
      "isDefault": false,
      "isEncoder": true,
      "isHwAccel": true,
      "mediaType": "Video",
      "metrics": {
        "active": {
          "decoder": 1,
          "encoder": 1
        }
      },
      "module": "xma",
      "name": "xma:0",
      "supportedCodecs": [
        "H264",
        "H265"
      ]
    }
  ],
  "outputProfile": {
    "encodes": {
      "videos": [
        {
          "bFrames": "0",
          "bitrate": "1000000",
          "codec": "h264",
          "framerate": "30",
          "height": "1080",
          "keyFrameInterval": "120",
          "name": "video_1080",
          "preset": "fast",
          "width": "1920"
        }
      ]
    },
    "name": "high",
    "outputStreamName": "${OriginStreamName}_out"
  },
  "parentSourceInfo": {
    "createdTime": "2025-10-28T00:07:11.863+09:00",
    "name": "stream1",
    "sourceType": "Rtmp",
    "sourceUrl": "TCP://192.168.0.160:60470",
    "tracks": [
      {
        "id": 0,
        "name": "Video",
        "type": "Video",
        "video": {
          "bitrate": 677000,
          "bitrateAvg": 0,
          "bitrateConf": 677000,
          "bitrateLatest": 32767,
          "bypass": false,
          "codec": "H264",
          "deltaFramesSinceLastKeyFrame": 6,
          "framerate": 25.0,
          "framerateAvg": 0.0,
          "framerateConf": 25.0,
          "framerateLatest": 0.0,
          "hasBframes": true,
          "height": 720,
          "keyFrameInterval": 1.0,
          "keyFrameIntervalAvg": 1.0,
          "keyFrameIntervalConf": 0.0,
          "keyFrameIntervalLatest": 0.0,
          "width": 1280
        }
      },
      {
        "audio": {
          "bitrate": 18000,
          "bitrateAvg": 0,
          "bitrateConf": 18000,
          "bitrateLatest": 0,
          "bypass": false,
          "channel": 2,
          "codec": "AAC",
          "samplerate": 44100
        },
        "id": 1,
        "name": "Audio",
        "type": "Audio"
      },
      {
        "id": 2,
        "name": "Data",
        "type": "Data"
      }
    ]
  },
  "parentSourceUri": "#default#app/stream1",
  "sourceInfo": {
    "createdTime": "2025-10-28T00:07:11.876+09:00",
    "name": "stream1_out",
    "sourceType": "Transcoder",
    "sourceUrl": "da4da9dc-4e0f-41de-b623-4a8f3ed8a4c5/#default#app/stream1/i",
    "tracks": [
      {
        "id": 0,
        "name": "video_1080",
        "type": "Video",
        "video": {
          "bitrate": 1000000,
          "bitrateAvg": 0,
          "bitrateConf": 1000000,
          "bitrateLatest": 0,
          "bypass": false,
          "codec": "H264",
          "deltaFramesSinceLastKeyFrame": 0,
          "framerate": 30.0,
          "framerateAvg": 0.0,
          "framerateConf": 30.0,
          "framerateLatest": 0.0,
          "hasBframes": false,
          "height": 1080,
          "keyFrameInterval": 120.0,
          "keyFrameIntervalAvg": 0.0,
          "keyFrameIntervalConf": 120.0,
          "keyFrameIntervalLatest": 0.0,
          "width": 1920
        }
      },
      {
        "id": 1,
        "name": "Data",
        "type": "Data"
      }
    ]
  },
  "sourceUri": "#default#app/stream1_out",
  "type": "EGRESS"
}

Messages

Type	Code	Description
INGRESS	INGRESS_STREAM_CREATED	새 ingress stream이 생성되었습니다.
	INGRESS_STREAM_PREPARED	ingress stream이 준비되었습니다.
	INGRESS_STREAM_DELETED	ingress stream이 삭제되었습니다.
	INGRESS_STREAM_CREATION_FAILED_DUPLICATE_NAME	지정한 stream name이 이미 사용 중이므로 stream을 생성하지 못했습니다.
	INGRESS_BITRATE_LOW	ingress stream의 현재 bitrate (%d bps)가 설정된 bitrate (%d bps)보다 낮습니다.
	INGRESS_BITRATE_HIGH	ingress stream의 현재 bitrate (%d bps)가 설정된 bitrate (%d bps)보다 높습니다.
	INGRESS_FRAMERATE_LOW	ingress stream의 현재 frame rate (%.2f fps)가 설정된 frame rate (%.2f fps)보다 낮습니다.
	INGRESS_FRAMERATE_HIGH	ingress stream의 현재 frame rate (%f fps)가 설정된 frame rate (%f fps)보다 높습니다.
	INGRESS_WIDTH_SMALL	ingress stream의 width (%d)가 설정된 width (%d)보다 작습니다.
	INGRESS_WIDTH_LARGE	ingress stream의 width (%d)가 설정된 width (%d)보다 큽니다.
	INGRESS_HEIGHT_SMALL	ingress stream의 height (%d)가 설정된 height (%d)보다 작습니다.
	INGRESS_HEIGHT_LARGE	ingress stream의 height (%d)가 설정된 height (%d)보다 큽니다.
	INGRESS_SAMPLERATE_LOW	ingress stream의 현재 sample rate (%d)가 설정된 sample rate (%d)보다 낮습니다.
	INGRESS_SAMPLERATE_HIGH	ingress stream의 현재 sample rate (%d)가 설정된 sample rate (%d)보다 높습니다.
	INGRESS_LONG_KEY_FRAME_INTERVAL	ingress stream의 현재 keyframe interval (%.1f seconds)이 너무 깁니다. keyframe interval을 4초 이하로 설정해 주십시오.
	INGRESS_HAS_BFRAME	ingress stream에서 B-Frames가 감지되었습니다.
EGRESS	EGRESS_STREAM_CREATED	새 egress stream이 생성되었습니다.
	EGRESS_STREAM_PREPARED	egress stream이 준비되었습니다.
	EGRESS_STREAM_DELETED	egress stream이 삭제되었습니다.
	EGRESS_STREAM_CREATION_FAILED_OUTPUT_PROFILE	output profile 설정이 올바르지 않아 egress stream을 생성하지 못했습니다.
	EGRESS_STREAM_CREATION_FAILED_DECODER	decoder를 생성할 수 없어 egress stream을 생성하지 못했습니다.
	EGRESS_STREAM_CREATION_FAILED_ENCODER	encoder를 생성할 수 없어 egress stream을 생성하지 못했습니다.
	EGRESS_STREAM_CREATION_FAILED_FILTER	filter를 생성할 수 없어 egress stream을 생성하지 못했습니다.
	EGRESS_LLHLS_READY	LL-HLS stream이 playback 가능한 상태입니다 (initial segment(s)가 생성되었습니다).
	EGRESS_HLS_READY	HLS stream이 playback 가능한 상태입니다 (initial segment(s)가 생성되었습니다).
INTERNAL_QUEUE	INTERNAL_QUEUE	internal queue(s)가 현재 congested 상태입니다.

Security

보안상의 이유로 Control Server는 수신된 HTTP 요청의 유효성을 검사해야 할 수 있습니다. 이를 위해 Enhanced Alert Module은 X-OME-Signature 값을 HTTP Request Header에 추가합니다.

이때, X-OME-Signature는 Server.xml 내 <Alert><SecretKey>에 설정된 Secret Key를 사용하여 HMAC-SHA1 Algorithm으로 HTTP Request의 Payload를 암호화한 뒤, URL-safe (base64)로 인코딩한 값입니다.

Response

Engine이 Closing 상태일 때, Response에 별도의 Parameter가 필요하지 않으므로 Response Payload는 무시됩니다.

HTTP/1.1 200 OK
Content-Length: 0
Connection: Closed

Anomaly Detection | 0.20.1.0+

Anomaly Detection는 Streaming 과정에서 발생하는 Input Stream 오류를 탐지하고, Alert Callback 또는 Stream 종료 등 후속 조치를 취할 수 있는 모듈입니다.

Anomaly Detection는 아래와 같이 <Server><Alert><Rules>에서 설정할 수 있습니다:

<Server>
	<Alert>
		<Rules>
			...
			<Anomaly>
				<DTSReversal>
					<CheckDuration>5</CheckDuration>
					<Count>1</Count>
					<Threshold>5</Threshold>
					<Action>TerminateStream,Alert</Action>
				</DTSReversal>
				<DTSJump>
					<Action>TerminateStream,Alert</Action>
				</DTSJump>
				<DTSDuplication>
					<Count>1</Count>
					<Action>TerminateStream,Alert</Action>
				</DTSDuplication>
				<PacketTimeout>
					<Action>TerminateStream,Alert</Action>
				</PacketTimeout>
			</Anomaly>
		</Rules>
	</Alert>
...

Key	Default (Allowed)	Description
CheckDuration	10 (0-3600)	Action 실행 조건을 판단하기 위해, Anomaly 발생 횟수를 누적 집계하는 기준 시간입니다. 단위는 초 (s)입니다. CheckDuration으로 설정된 시간 내에 Threshold (아래 각 옵션마다 설명)를 초과하는 상황이 Count 횟수만큼 발생할 경우 Action이 발동됩니다. ex) CheckDuration이 0으로 설정된 경우, Count가 1이면 대기 시간 없이 즉시 탐지하지만, Count가 2이상이면 시간 구간이 없으므로 탐지가 불가능합니다.
Count	1 (1-65535)	CheckDuration으로 설정된 시간 내에 Anomaly 횟수가 Count에 설정된 값보다 많이 발생하면 Anomaly로 판단합니다. 단위는 회 입니다.
Action	N/A	Anomaly가 탐지된 이후에 어떤 후속 조치를 할지 지정합니다. 설정 가능한 후속 조치는 아래와 같으며, 복수로 지정할 수 있습니다. TerminateStream: Anomaly가 감지된 WebRTC, Ovt, RTMP, RtmpPull, Rtsp, RtspPull, Mpegts, Srt 와같은 Source Type일 때, Stream을 중단합니다. Alert: Anomaly 감지 여부를 Alert으로 전송합니다.

DTSReversal 설정하기

DTSReversal은 Decoding Time Stamp (DTS)가 이전 값 (ms)보다 작아지거나, 증가하지 않아 재생 문제가 생길 수 있는 경우를 탐지합니다.

DTSReversal은 <Server><Alert><Rules><Anomaly>에 설정할 수 있으며, 아래는 예제입니다:

<Server>
	<Alert>
		<Rules>
		...
			<Anomaly>
				<DTSReversal>
					<CheckDuration>5</CheckDuration>	<!-- 최근 5초 동안 -->
					<Count>2</Count>	<!-- 두 번 이상 -->
					<Threshold>5</Threshold>	<!-- DTS가 5ms 이상 역전하였다면 -->
					<Action>TerminateStream,Alert</Action>	<!-- 해당 스트림을 종료하고 alert -->
				</DTSReversal>
				...

= 최근 5초 동안 (CheckDuration) DTS가 5밀리초 이상 역전 (Threshold)된 횟수가 2회 이상 (Count)이라면 해당 Stream을 종료하고 Alert을 전송 (Action)합니다.

Key	Default (Allowed)	Description
Threshold	1 (1-2147483647)	"DTS가 몇 밀리초 이상 역전해야 Anomaly로 판단하는가?"에 대한 기준입니다. 단위는 밀리초 (ms)입니다.

DTSJump 설정하기

DTSJump는 연속된 Frame 사이에 DTS가 급격히 증가하여, 재생 문제를 일으킬 수 있는 경우를 탐지합니다.

DTSJump는 <Server><Alert><Rules><Anomaly>에 설정할 수 있으며, 아래는 예제입니다:

<Server>
	<Alert>
		<Rules>
			<Anomaly>
				<DTSJump>
					<CheckDuration>5</CheckDuration>	<!-- 최근 5초 동안 -->
					<Count>2</Count>	<!-- 두 번 이상 -->
					<Threshold>1000</Threshold>	<!-- DTS가 1000ms 이상 급증하였다면 -->
					<Action>TerminateStream,Alert</Action>	<!-- 해당 스트림을 종료하고 alert -->
				</DTSJump>
				...

= 최근 5초 동안 (CheckDuration) DTS가 1,000밀리초 이상 급증 (Threshold)한 횟수가 2회 이상 (Count)이라면 해당 Stream을 종료하고 Alert을 전송 (Action)합니다.

Key	Default (Allowed)	Description
Threshold	1000 (1-2147483647)	"DTS가 몇 밀리초 이상 급증해야 Anomaly로 판단하는가?"에 대한기준입니다. 단위는 밀리초 (ms)입니다.

DTSDuplication 설정하기

DTSDuplication는 연속된 Frame의 DTS가 동일하여, 재생 문제를 일으킬 수 있는 경우를 탐지합니다.

DTSDuplication은 <Server><Alert><Rules><Anomaly>에 설정할 수 있으며, 아래는 예제입니다:

<Server>
	<Alert>
		<Rules>
			<Anomaly>
				<DTSJump>
					<CheckDuration>5</CheckDuration>	<!-- 최근 5초 동안 -->
					<Count>2</Count>	<!-- 두 번 이상 -->
					<Action>TerminateStream,Alert</Action>	<!-- 해당 스트림을 종료하고 alert -->
				</DTSJump>
				...

= 최근 5초 동안 (CheckDuration) DTS가 동일한 횟수가 2회 이상 (Count)이라면 해당 Stream을 종료하고 Alert을 전송 (Action)합니다.

PacketTimeout 설정하기

PacketTimeout은 지정한 시간 동안 Packet이 수신되지 않아, 재생 문제를 일으킬 수 있는 경우를 탐지합니다.

PacketTimeout은 <Server><Alert><Rules><Anomaly>에 설정할 수 있으며, 아래는 예제입니다:

<Server>
	<Alert>
		<Rules>
			<Anomaly>
				<DTSJump>
					<CheckDuration>5</CheckDuration>	<!-- 최근 5초 동안 -->
					<Count>2</Count>	<!-- 두 번 이상 -->
					<Threshold>1000</Threshold>	<!-- 패킷이 1000ms 이상 수신되지 않았다면 -->
					<Action>TerminateStream,Alert</Action>	<!-- 해당 스트림을 종료하고 alert -->
				</DTSJump>
				...

= 최근 5초 동안 (CheckDuration) Packet이 1,000밀리초 이상 수신 (Threshold)되지 않은 횟수가 2회 이상 (Count)이라면 해당 Stream을 종료하고 Alert을 전송 (Action)합니다.

Key	Default (Allowed)	Description
Threshold	1500 (1-2147483647)	"Packet이 몇 밀리초 만큼 수신되지 않을 경우 Anomaly로 판단하는가?"에 대한 기준입니다. 단위는 밀리초 (ms)입니다.

PacketTimeout 기능이 Origin Redudnacy의 PacketSilenceTimeoutMs와 중복되므로, Anomaly Dqetection 기능을 사용하는 것을 권장합니다.

• 두 설정 모두 켜져있는 경우, 조금 더 작은 값으로 설정된 모듈이 먼저 동작합니다.