# Event Specification

## Event Log 파일

Event Monitoring을 활성화 하면 [Event Configuration](event-configuration)에서 지정한 디렉로리에 `events.log`로 Event Log 파일이 생성되며 `events.log.YYYYMMDD` 형식으로 Daily rolling이 됩니다.

### Event Log 파일 예제

```json
{"time":"2025-03-26T05:21:46.315+00:00","level":"Info","category":"StreamEvent","type":"StreamCreated","sourceId":"#default#app/push_rtmp","summary":"Stream created. Id: 103, StreamType: Rtmp, SourceUrl: TCP://172.17.0.1:44004"}
{"time":"2025-03-26T05:21:46.316+00:00","level":"Info","category":"StreamEvent","type":"StreamPrepared","sourceId":"#default#app/push_rtmp","summary":"Stream prepared. Id: 103, StreamType: Rtmp, SourceUrl: TCP://172.17.0.1:44004","snapshot":{"createdTime":"2025-03-26T05:21:46.315+00:00","name":"push_rtmp","sourceType":"Rtmp","sourceUrl":"TCP://172.17.0.1:44004","tracks":[{"id":0,"name":"Video","type":"Video","video":{"bitrate":"2500000","bitrateAvg":"0","bitrateConf":"2500000","bitrateLatest":"128503","bypass":false,"codec":"H264","deltaFramesSinceLastKeyFrame":0,"framerate":30.0,"framerateAvg":0.0,"framerateConf":30.0,"framerateLatest":0.0,"hasBframes":false,"height":1080,"keyFrameInterval":1.0,"keyFrameIntervalAvg":1.0,"keyFrameIntervalConf":0.0,"keyFrameIntervalLatest":0.0,"width":1920}},{"audio":{"bitrate":"160000","bitrateAvg":"0","bitrateConf":"160000","bitrateLatest":"-795170153","bypass":false,"channel":2,"codec":"AAC","samplerate":48000},"id":1,"name":"Audio","type":"Audio"},{"id":2,"name":"Data","type":"Data"}]}}
{"time":"2025-03-26T05:21:46.319+00:00","level":"Info","category":"StreamEvent","type":"PushPublishingStarted","sourceId":"#default#app/push_rtmp","summary":"PushPublishing started. Id: JwW9AM, Protocol: rtmp, Url: rtmp://192.168.0.234:52935/app/pushedRtmp, StreamKey: ","snapshot":{"app":"app","createdTime":"2025-03-26T05:21:46.319+00:00","finishTime":"1970-01-01T00:00:00.000+00:00","id":"JwW9AM","isConfig":true,"protocol":"rtmp","sentBytes":0,"sentTime":0,"sequence":0,"startTime":"1970-01-01T00:00:00.000+00:00","state":"ready","stream":{"name":"push_rtmp","trackIds":[],"variantNames":["video_h264_1080p","aac_audio"]},"totalsentBytes":0,"totalsentTime":0,"url":"rtmp://192.168.0.234:52935/app/pushedRtmp","vhost":"default"}}
{"time":"2025-03-26T05:21:47.114+00:00","level":"Info","category":"StreamEvent","type":"StreamCreated","sourceId":"#default#app/pushedRtmp","summary":"Stream created. Id: 104, StreamType: Rtmp, SourceUrl: TCP://172.17.0.1:48218"}
{"time":"2025-03-26T05:21:47.129+00:00","level":"Info","category":"StreamEvent","type":"StreamPrepared","sourceId":"#default#app/pushedRtmp","summary":"Stream prepared. Id: 104, StreamType: Rtmp, SourceUrl: TCP://172.17.0.1:48218","snapshot":{"createdTime":"2025-03-26T05:21:47.114+00:00","name":"pushedRtmp","sourceType":"Rtmp","sourceUrl":"TCP://172.17.0.1:48218","tracks":[{"id":0,"name":"Video","type":"Video","video":{"bitrate":"4906000","bitrateAvg":"0","bitrateConf":"4906000","bitrateLatest":"1059802151","bypass":false,"codec":"H264","deltaFramesSinceLastKeyFrame":0,"framerate":30.0,"framerateAvg":0.0,"framerateConf":30.0,"framerateLatest":0.0,"hasBframes":false,"height":1080,"keyFrameInterval":0.0,"keyFrameIntervalAvg":0.0,"keyFrameIntervalConf":0.0,"keyFrameIntervalLatest":0.0,"width":1920}},{"audio":{"bitrate":"125000","bitrateAvg":"0","bitrateConf":"125000","bitrateLatest":"1059802151","bypass":false,"channel":2,"codec":"AAC","samplerate":48000},"id":1,"name":"Audio","type":"Audio"},{"id":2,"name":"Data","type":"Data"}]}}
```

### Event Log JSON

Event Log는 Event의 정보를 `JSON`형태로 기록하며, 각 필드의 의미는 다음과 같습니다:

<table><thead><tr><th width="119">Field</th><th width="90">Optional</th><th>Description</th></tr></thead><tbody><tr><td><code>time</code></td><td>N</td><td>Event 가 발생한 시간을 ISO 8601 포맷으로 기록합니다.</td></tr><tr><td><code>level</code></td><td>N</td><td>Event의 레벨을 기록합니다.</td></tr><tr><td><code>category</code></td><td>N</td><td>Event의 대분류를 기록합니다. 대분류로는 <code>Server Events</code>, <code>Virtual Host Events</code>, <code>Application Events</code>, <code>Stream Events</code>, <code>Rest API Call Events</code>, <code>Access Control Events</code>가 있습니다.</td></tr><tr><td><code>type</code></td><td>N</td><td>Event의 종류를 기록합니다. Event 카테고리에 따른 Event 타입들은 아래 <a href="#undefined-4">Event Category 및 Type </a>섹션에서 확인할 수 있습니다.</td></tr><tr><td><code>sourceId</code></td><td>N</td><td>Event를 발생시킨 소스의 ID를 기록합니다. 소스의 타입은 <code>Server</code>, <code>Virtual Host</code>, <code>Application</code>, <code>Stream</code>이 있습니다.</td></tr><tr><td><code>summary</code></td><td>N</td><td>Event의 내용을 한 줄로 요약해 기록합니다.</td></tr><tr><td><code>cause</code></td><td>Y</td><td>특정 Event의 Event 발생 원인을 기록합니다.</td></tr><tr><td><code>snapshot</code></td><td>Y</td><td>특정 Event 발생 시점의 상세한 정보를 <code>JSON</code>형식으로 기록합니다.</td></tr></tbody></table>

## Event Level

Event는 심각도에 따라 다음과 같은 레벨로 분류됩니다.

<table><thead><tr><th width="119">Level</th><th>Description</th></tr></thead><tbody><tr><td><code>Trace</code></td><td>기능 동작의 상세한 흐름을 확인하기 위한 Event입니다.</td></tr><tr><td><code>Debug</code></td><td>기능 동작 및 상태 변경에 대한 상세 정보를 확인하기 위한 Event입니다.</td></tr><tr><td><code>Info</code></td><td>일반적인 기능 동작 및 상태 변경시 발생하는 Event (대부분의 Event)입니다.</td></tr><tr><td><code>Warning</code></td><td>오류 상황이기는 하지만, 기능 동작에 영향을 미치지는 않은 Event입니다.</td></tr><tr><td><code>Error</code></td><td>심각한 문제나 기능 오작동 시 발생하는 Event입니다.</td></tr></tbody></table>

## Event Source ID

Event를 발생시킨 소스의 출처를 확인 할 수 있는 `URI` 형식의 ID입니다. 소스의 타입별로 다음과 같이 ID의 형태가 달라 질 수 있습니다:

<table><thead><tr><th width="119">Source ID</th><th>Description</th></tr></thead><tbody><tr><td>Server</td><td><p>OvenMediaEngine의  Server ID가 기록됩니다.</p><ul><li>예: <code>6add8be3-181f-4c4b-bc4e-xxxxxxxxxxxx</code></li></ul></td></tr><tr><td>Virtual Host</td><td><p>Virtual Host의 이름이 기록됩니다.</p><ul><li>예: <code>default</code></li></ul></td></tr><tr><td>Application</td><td><p><code>#{virtual_host_name}#{app_name}</code> 형식으로 기록됩니다.</p><ul><li>예: <code>#default#app</code></li></ul></td></tr><tr><td>Stream</td><td><p><code>#{virtual_host_name}#{app_name}/{stream_name}</code> 형식으로 기록됩니다. </p><ul><li>예: <code>#default#app/stream</code></li></ul></td></tr></tbody></table>

## Event Category 및 Type

Event Log는 카테고리와 타입으로 분류됩니다.

{% hint style="info" %}
Monitoring을 위한 Event 카테고리와 타입은 지속적으로 추가될 예정입니다.
{% endhint %}

### 서버 이벤트 (`ServerEvent`)

<table><thead><tr><th width="140">Event Type</th><th width="335">Description</th><th width="136">Event Level</th><th width="137">Snapshot</th></tr></thead><tbody><tr><td><code>ServerStarted</code></td><td>Server 시작 (Server 이름, Server 버전)</td><td>Info</td><td>가상호스트 세부 정보</td></tr><tr><td><code>InternalQueueCongestion</code></td><td><p>내부 큐 혼잡 (발생한 큐 정보)</p><ul><li>지원 버전: 0.18.1.2+</li></ul></td><td>Info</td><td>N/A</td></tr></tbody></table>

### 가상호스트 이벤트 (`HostEvent`)

<table><thead><tr><th width="140">Event Type</th><th width="335">Description</th><th width="135">Event Level</th><th width="138">Snapshot</th></tr></thead><tbody><tr><td><code>HostCreated</code></td><td>새 Virtual Hsot 생성 (Virtual Host 이름, distribution 이름)</td><td>Info</td><td>Virtual Host 세부 정보</td></tr><tr><td><code>HostDeleted</code></td><td>Virtual Hsot 삭제 (삭제된 Virtual Host 이름, distribution 이름)</td><td>Info</td><td>N/A</td></tr></tbody></table>

### 애플리케이션 이벤트 (`AppEvent`)

<table><thead><tr><th>Event Tpe</th><th width="344">Description</th><th>Event Level</th><th>Snapshot</th></tr></thead><tbody><tr><td><code>AppCreated</code></td><td>새 Application 생성 (Application 이름)</td><td>Info</td><td>Application 세부 정보</td></tr><tr><td><code>AppDeleted</code></td><td>Application 삭제 (삭제된 Applicaiton 이름)</td><td>Info</td><td>N/A</td></tr></tbody></table>

### 스트림 이벤트 (`StreamEvent`)

<table><thead><tr><th width="266">Event Type (Cause)</th><th width="240">Description</th><th width="113">Event Level</th><th>Snapshot</th></tr></thead><tbody><tr><td><code>StreamCreated</code></td><td>새 Stream 생성 (Stream ID, 타입, 미디어 소스)</td><td>Info</td><td>N/A</td></tr><tr><td><code>StreamPrepared</code></td><td>Stream 준비 완료 (Stream ID, 타입, 미디어 소스)</td><td>Info</td><td>Stream 세부정보</td></tr><tr><td><code>StreamDeleted</code></td><td>Stream 삭제 (Stream ID, 타입, 미디어 소스)</td><td>Info</td><td>N/A</td></tr><tr><td><p><code>StreamCreationFailed</code> </p><p>(<code>DuplicatedStreamName</code>)</p></td><td>중복된 Stream 이름으로 인한 Stream 생성 실패 (중복된 Stream 이름)</td><td>Error</td><td>N/A</td></tr><tr><td><p><code>AbnormalStreamDetected</code> </p><p>(<code>BFrameDetected</code>) </p></td><td>B-Frame 감지 (Track 정보)</td><td>Warning</td><td>Track 정보</td></tr><tr><td><p><code>AbnormalStreamDetected</code> </p><p>(<code>AbnormalIncreasedTimestamp</code>)</p></td><td>Input Stream의 Timestamp 이상 (Track 정보)</td><td>Warning</td><td>Track 정보</td></tr><tr><td><p><code>AbnormalStreamDetected</code> </p><p>(<code>AbnormalFpsDetected</code>)</p></td><td><p>Input Stream의 Framerate 이상 (Input Stream Framerate, Track 정보)</p><ul><li>지원 버전: 0.18.1.2+</li></ul></td><td>Warning</td><td>Track 정보</td></tr><tr><td><p><code>AbnormalStreamDetected</code> </p><p>(<code>LongKeyFrameIntervalDetected</code>)</p></td><td><p>Input Stream에서 4초 이상의 Keyframe Interval 탐지 (Track 정보)</p><ul><li>지원 버전: 0.18.1.2+</li></ul></td><td>Warning</td><td>Track 정보</td></tr><tr><td><code>ScheduledChannelCreated</code></td><td>Scheduled Channel 생성 (<code>sch</code> 파일 경로)</td><td>Info</td><td>Scheduled Channel 정보</td></tr><tr><td><code>ScheduledChannelUpdated</code></td><td>Scheduled Channel 업데이트 (<code>sch</code> 파일 경로)</td><td>Info</td><td>Scheduled Channel 정보</td></tr><tr><td><code>ScheduledChannelDeleted</code></td><td>Scheduled Channel 삭제 (<code>sch</code> 파일 경로)</td><td>Info</td><td>N/A</td></tr><tr><td><code>ScheduledChannelItemChanged</code></td><td>Scheduled Channel 아이템 변경 (프로그램, 일정, 아이템 정보, Fallback 여부)</td><td>Info</td><td>N/A</td></tr><tr><td><p><code>ScheduledChannelPlaybackError</code></p><p>(<code>FailedToPopPacket</code>)</p></td><td><p>Scheduled Channel 라이브 아이템 재생 시, Packet 수신 실패 (프로그램, 일정, 아이템 정보, Fallback 여부)</p><ul><li>지원 버전: 0.18.1.2+</li></ul></td><td>Warning</td><td>N/A</td></tr><tr><td><code>MultiplexChannelCreated</code></td><td>Multiplex Channel 생성 (<code>mux</code> 파일 경로)</td><td>Info</td><td>Multiplex Channel 정보</td></tr><tr><td><code>MultiplexChannelUpdated</code></td><td>Multiplex Channel 업데이트 (<code>mux</code> 파일 경로)</td><td>Info</td><td>Multiplex Channel 정보</td></tr><tr><td><code>MultiplexChannelDeleted</code></td><td>Multiplex Channel 삭제 (<code>mux</code> 파일 경로)</td><td>Info</td><td>N/A</td></tr><tr><td><code>RecordingStarted</code></td><td>Recording 시작 (Recording ID, Recording 파일 경로)</td><td>Info</td><td>Recording 정보</td></tr><tr><td><code>RecordingStopped</code></td><td>Recording 중지 (Recording ID, Recording 파일 경로)</td><td>Info</td><td>Recording 정보</td></tr><tr><td><code>PushPublishingStarted</code></td><td>Push Publishing 시작 (Pus ID, 프로토콜, 재송출 URL)</td><td>Info</td><td>Push 정보</td></tr><tr><td><code>PushPublishingStopped</code></td><td>Push Publishing 중지 (Push ID, 프로토콜, 재송출 URL)</td><td>Info</td><td>Push 정보</td></tr><tr><td><code>HLSDumpStarted</code></td><td>HLS Dump 시작 (Dump ID, Dump 저장 경로)</td><td>Info</td><td>Dump 정보</td></tr><tr><td><code>HLSDumpStopped</code></td><td>HLS Dump 중지 (Dump ID, Dump 저장 경로)</td><td>Info</td><td>Dump 정보</td></tr></tbody></table>

### REST API 이벤트 (`RestApiEvent`)

<table><thead><tr><th width="176">Event Type</th><th width="313">Description</th><th>Event Level</th><th>Snapshot</th></tr></thead><tbody><tr><td><code>RestApiRequested</code></td><td>REST API 요청 (HTTP 버전, 메서드, 경로, 원격 주소, <code>RequestID</code>)</td><td>Info</td><td>요청 본문</td></tr><tr><td><code>RestApiResponded</code></td><td>REST API 응답 (응답 상태 코드, <code>RequestID</code>)</td><td>Info (오류 시 Error)</td><td>응답 본문</td></tr></tbody></table>

### 접근 제어 이벤트 (`AccessControlEvent`)

<table><thead><tr><th width="171">Event Type</th><th width="313">Description</th><th>Event Level</th><th>Snapshot</th></tr></thead><tbody><tr><td><code>VerifyingSignedPolicyFailed</code></td><td>Signed Policy 검증 실패 (요청 URL, 원격 주소, 오류 메시지)</td><td>Error</td><td>N/A</td></tr><tr><td><code>VerifyingAdmissionWebhooksFailed</code></td><td>Admission Webhooks 검증 실패 (요청 URL, 원격 주소, 오류 메시지)</td><td>Error</td><td>응답 본문, N/A</td></tr></tbody></table>

