> ## Documentation Index
> Fetch the complete documentation index at: https://stellar-relay.xdr.ooo/llms.txt
> Use this file to discover all available pages before exploring further.

# 문제 해결

> 스트림 설정, systemd 상태, TCP NDJSON 전달 문제를 확인합니다.

먼저 설정이 완전한지 확인하십시오. Alert와 Case 스트림은 서로 독립적으로 설정되며, 일부 필수 항목만 설정된 스트림은 오류로 처리됩니다.

## 스트림이 시작되지 않음

문제가 발생한 스트림에 필요한 필수 설정이 모두 있는지 확인합니다.

### Alert 스트림

```text theme={null}
--alert-interval
--alert-syslog-ip
--alert-syslog-port
```

### Case 스트림

```text theme={null}
--case-interval
--case-syslog-ip
--case-syslog-port
```

특정 스트림의 모든 옵션을 생략하면 해당 스트림은 비활성화됩니다. 스트림 설정을 시작했지만 필수 옵션이 누락되면 해당 스트림은 오류로 처리됩니다.

## 서비스가 실행되지 않음

서비스 상태를 확인합니다.

```bash theme={null}
sudo systemctl status stellar-alert-case.service
```

최근 unit 파일을 수정했다면 다음을 실행합니다.

```bash theme={null}
sudo systemctl daemon-reload
sudo systemctl restart stellar-alert-case.service
```

문제를 재현하면서 로그를 확인합니다.

```bash theme={null}
journalctl -u stellar-alert-case.service -f
```

자동 복구를 위해 다음 설정을 유지합니다.

```ini theme={null}
Restart=on-failure
RestartSec=10
```

## 수신 시스템에 레코드가 도착하지 않음

Relay 호스트에서 대상 시스템까지의 경로를 확인합니다.

1. 문제가 있는 스트림의 대상 IP와 port가 올바른지 확인합니다.
2. 수신 시스템이 해당 TCP port에서 listening 중인지 확인합니다.
3. Firewall 및 network policy가 연결을 허용하는지 확인합니다.
4. 해당 Alert 또는 Case 스트림이 필수 설정을 모두 갖추고 활성화되어 있는지 확인합니다.
5. 수신 시스템이 TCP 기반 newline-delimited JSON을 처리하도록 설정되어 있는지 확인합니다.

## 수신 시스템이 레코드를 parsing하지 못함

예상되는 framing은 다음과 같습니다.

```text theme={null}
JSON object + newline
JSON object + newline
...
```

하나의 큰 JSON 문서 또는 전통적인 RFC syslog framing을 기대하는 parser로 설정하지 마십시오. 실제 배포된 Relay에서 생성된 대표 이벤트를 이용해 mapping을 검증하십시오.

## Case fetch 문제 확인

권장 Case 설정에는 다음 옵션이 포함됩니다.

```bash theme={null}
--case-fetch-timeout 90 \
--case-include-summary \
--no-case-format-summary
```

Case 전달이 지연되거나 일부 데이터가 누락되는 경우 이 설정과 Stellar Cyber API 접근 상태를 함께 확인하십시오.

## Debug 모드

`--debug`는 문제 해결 시에만 사용하십시오.

<Warning>
  운영 환경에서 추가 logging이 의도적으로 필요한 경우가 아니라면 문제 해결이 끝난 뒤 debug 모드를 비활성화하십시오.
</Warning>

## 빠른 확인 항목

<CardGroup cols={2}>
  <Card title="서비스 상태" icon="server">
    systemd unit이 active 상태인지 확인하고 journal에서 런타임 오류를 확인합니다.
  </Card>

  <Card title="스트림 설정 완전성" icon="list-check">
    활성화된 각 스트림에 interval, 대상 IP, 대상 port가 모두 설정되어 있는지 확인합니다.
  </Card>

  <Card title="TCP 연결" icon="network-wired">
    Relay 호스트에서 설정된 각 destination listener까지 연결 가능한지 확인합니다.
  </Card>

  <Card title="NDJSON parsing" icon="code">
    수신 시스템이 newline으로 구분된 각 JSON 객체를 하나의 이벤트로 처리하는지 확인합니다.
  </Card>
</CardGroup>