diff --git a/journey/README.md b/journey/README.md index a5c9f6e..c291445 100644 --- a/journey/README.md +++ b/journey/README.md @@ -86,6 +86,7 @@ - [24서버 robeing runtime workspace-config 단일화](./worklog/260310_24서버_robeing_runtime_workspace_config_단일화.md) - [260316 runtime env override audit 및 SSOT 원칙 승격](./worklog/260316_runtime_env_override_audit_및_ssot원칙승격.md) - [non-RDB 계층 PostgreSQL 통일 1차 실행 완료](./worklog/260317_nonrdb_계층_postgresql_통일_1차_실행완료.md) +- [260318 51123 OpenSearch 샤드한도 로그적재 복구](./worklog/260318_51123_opensearch_샤드한도_로그적재복구.md) - [23 gateway MONITOR_URL 24 monitor 교정 및 실도메인 전수검증](./worklog/260310_23gateway_monitor_url_24monitor_교정_및_실도메인_전수검증.md) - [24전환 배포대상과 ingress 24IP 교정 1차](./worklog/260309_24전환_배포대상과_ingress_24IP_교정_1차.md) - [24서버 NAS 마운트 복원 및 ONNX 백업 실행](./worklog/260309_24서버_nas마운트복원_onnx백업실행.md) diff --git a/journey/worklog/260318_51123_opensearch_샤드한도_로그적재복구.md b/journey/worklog/260318_51123_opensearch_샤드한도_로그적재복구.md new file mode 100644 index 0000000..819ce18 --- /dev/null +++ b/journey/worklog/260318_51123_opensearch_샤드한도_로그적재복구.md @@ -0,0 +1,32 @@ +--- +tags: [infra, 51123, opensearch, fluent-bit, logging, worklog] +--- + +# 260318 51123 OpenSearch 샤드한도 로그적재 복구 + +## 관련 문서 +- [51123 로그 적재 복구 워크플로우](../../workflow/51123_log_ingest_recovery_workflow.md) +- [51123 구IP active runtime 제거 1차](./260309_51123_구IP_active_runtime_제거_1차.md) + +## 작업 + +- OpenSearch 연결 경로를 현재 운영 주소 `192.168.0.100:9200` 기준으로 다시 확인했습니다. +- 실제 적재 실패 원인이 `dataprepper-static` 샤드 문서 수 한도(`2147483519`) 도달임을 Fluent Bit와 OpenSearch 응답으로 확인했습니다. +- `/home/admin/robeing/fluent-bit/fluent-bit.conf`에서 출력 인덱스를 `dataprepper-static` 대신 `dataprepper-2026.03.18`로 바꾸고, 부팅을 막던 multiline 필터를 제거했습니다. +- `docker compose up -d --build --force-recreate fluent-bit`로 새 설정을 런타임에 반영했습니다. + +## 확인된 사실 + +- Data Prepper 경유 `http -> 127.0.0.1:2021` 경로는 Fluent Bit 로그 기준 `HTTP 200` 응답은 있었지만, OpenSearch에 새 일자 인덱스가 생성되지 않았습니다. +- 직접 `es` 출력으로 전환한 뒤에는 새 인덱스가 실제로 생성됐고 문서 수가 증가했습니다. + +## 검증 + +- `docker logs fluent-bit` 기준 `output:es:es.0` worker 시작을 확인했습니다. +- `curl -s http://192.168.0.100:9200/_cat/indices/dataprepper-2026.03.18?v` 결과 새 인덱스가 생성됐습니다. +- `curl -s http://192.168.0.100:9200/dataprepper-2026.03.18/_count` 결과 `count=22`를 확인했습니다. +- 기존 `dataprepper-static`는 여전히 `docs.count=2147483519` 상태로 남아 있어, 원인 인덱스 해소가 아니라 새 인덱스로 적재를 복구한 상태임을 분리해서 기록합니다. + +## 한 줄 결론 + +- 51123 로그 적재 중단의 직접 원인은 `dataprepper-static` 샤드 포화였고, 현재는 새 일자 인덱스 `dataprepper-2026.03.18`로 적재가 다시 살아났습니다. diff --git a/workflow/51123_log_ingest_recovery_workflow.md b/workflow/51123_log_ingest_recovery_workflow.md new file mode 100644 index 0000000..a7bdafc --- /dev/null +++ b/workflow/51123_log_ingest_recovery_workflow.md @@ -0,0 +1,159 @@ +--- +tags: [infra, workflow, 51123, opensearch, fluent-bit, logging, recovery] +--- + +# 51123 로그 적재 복구 워크플로우 + +## 상위 원칙 +- [Infra Project Identity](../00_Philosophy/00_IDENTITY/Infra_Project_Identity.md) +- [Core Infrastructure Principles](../00_Philosophy/01_PRINCIPLES/Core_Infrastructure_Principles.md) +- [Operational Guardrails](../00_Philosophy/02_GUARDRAILS/Operational_Guardrails.md) +- 공통 작성 원칙: `/home/admin/0_VALUE/02_Governance/writing-principles.md` + +## 관련 문서 +- [workflow/README.md](./README.md) +- [260318 51123 OpenSearch 샤드한도 로그적재 복구](../journey/worklog/260318_51123_opensearch_샤드한도_로그적재복구.md) +- [250930 OpenSearch HDD 마이그레이션](../journey/troubleshooting/250930_opensearch_hdd_migration.md) + +## 목적 + +- 51123에서 Fluent Bit 로그가 OpenSearch에 적재되지 않을 때, 원인 확인부터 적재 복구까지 같은 절차로 반복 수행합니다. +- 이 문서는 사건 기록이 아니라 재실행 가능한 운영 절차 SSOT입니다. + +## 적용 범위 + +- 서버: 51123 (`192.168.0.100`) +- OpenSearch: `192.168.0.100:9200` +- Fluent Bit 작업 경로: `/home/admin/robeing/fluent-bit` +- 주요 설정 파일: `/home/admin/robeing/fluent-bit/fluent-bit.conf` + +## 대표 장애 징후 + +- Fluent Bit 로그에 `Number of documents in shard exceeds the limit`가 반복됩니다. +- OpenSearch 연결은 되지만 신규 문서가 적재되지 않습니다. +- `_cat/indices`에서 기존 적재 인덱스 문서 수가 비정상적으로 크거나 한도 도달 상태입니다. + +## SSOT 기준값 + +- OpenSearch 호스트 기준: `192.168.0.100:9200` +- Fluent Bit 작업 디렉터리: `/home/admin/robeing/fluent-bit` +- 복구 검증 기준: + - Fluent Bit 컨테이너가 재기동 후 `running` + - 새 적재 인덱스가 생성됨 + - `_count`가 1 이상 증가함 + +## 표준 흐름 + +### 1. 현재 장애 징후 확인 + +```bash +docker logs --tail 100 fluent-bit +curl -s http://192.168.0.100:9200/_cat/indices?v | grep dataprepper +``` + +확인 기준: +- Fluent Bit 로그에 `Number of documents in shard exceeds the limit`가 보이면 샤드 포화로 판단합니다. +- `_cat/indices`에서 기존 적재 인덱스 문서 수가 한도 근처이거나 한도 도달이면 같은 원인으로 봅니다. + +### 2. 현재 설정과 런타임 확인 + +```bash +sed -n '1,200p' /home/admin/robeing/fluent-bit/fluent-bit.conf +docker inspect fluent-bit --format '{{.Image}} {{.Created}} {{.State.Status}}' +``` + +확인 기준: +- 실제 출력 인덱스를 파일 기준으로 먼저 확인합니다. +- 컨테이너가 `running`이어도 오래된 이미지일 수 있으므로 이미지 생성 시각도 같이 봅니다. + +### 3. 새 일자 인덱스로 전환 + +원칙: +- 포화된 인덱스에 계속 쓰지 않습니다. +- 새 인덱스명은 작업 날짜 기준 `dataprepper-YYYY.MM.DD` 형식으로 잡습니다. + +수정 대상: +- `/home/admin/robeing/fluent-bit/fluent-bit.conf` + +수정 예시: + +```ini +[OUTPUT] + Name es + Match * + Host ${OPENSEARCH_HOST} + Port 9200 + Index dataprepper-2026.03.18 + Suppress_Type_Name On + Trace_Error On + Retry_Limit False +``` + +주의: +- 날짜는 작업일 기준으로 바꿉니다. +- 이전 포화 인덱스명을 그대로 두지 않습니다. +- 설정만 바꾸고 재빌드하지 않으면 런타임에 반영되지 않을 수 있습니다. + +### 4. 컨테이너 완전 재빌드 및 재생성 + +```bash +cd /home/admin/robeing/fluent-bit +docker compose up -d --build --force-recreate fluent-bit +``` + +확인 기준: +- `Built`, `Recreated`, `Started`가 순서대로 보여야 합니다. + +### 5. 복구 검증 + +```bash +docker logs --since 1m fluent-bit +curl -s http://192.168.0.100:9200/_cat/indices/dataprepper-2026.03.18?v +curl -s http://192.168.0.100:9200/dataprepper-2026.03.18/_count +``` + +확인 기준: +- Fluent Bit 로그에 `output:es:es.0` worker 시작이 보여야 합니다. +- 새 인덱스가 `_cat/indices`에 나타나야 합니다. +- `_count`가 `1` 이상이면 실제 적재가 살아난 것입니다. + +### 6. 실패 시 재분기 + +#### A. OpenSearch 연결 실패 + +```bash +curl -s -o /dev/null -w '%{http_code}\n' http://192.168.0.100:9200 +``` + +판단: +- `200`이 아니면 네트워크 또는 OpenSearch 자체 문제로 분리합니다. + +#### B. 설정 변경 후에도 예전 인덱스로 계속 적재 + +판단: +- 컨테이너가 오래된 이미지로 떠 있는 것입니다. +- 반드시 `--build --force-recreate`로 다시 올립니다. + +#### C. Data Prepper 경유 경로를 재검토해야 할 때 + +판단: +- Fluent Bit 로그에 `127.0.0.1:2021 HTTP status=200`만 있고 OpenSearch에 새 인덱스가 생기지 않으면, 수신 성공과 적재 성공을 분리해서 봅니다. +- 이 경우 Data Prepper는 별도 원인 분석 대상으로 분리하고, 로그 적재 복구 자체는 직접 `es` 경로로 먼저 닫습니다. + +## 성공 판정 규칙 + +- OpenSearch 연결 응답이 `200` +- Fluent Bit 컨테이너가 새 이미지로 재생성됨 +- 새 일자 인덱스가 생성됨 +- `_count >= 1` +- 기존 포화 인덱스와 새 적재 인덱스를 혼동하지 않음 + +## 기록 원칙 + +- 실제 날짜별 조치와 결과는 `journey/worklog/`에 남깁니다. +- 장애 원인 분석이나 구조 문제는 `journey/troubleshooting/`으로 분리합니다. +- 반복 복구 절차 자체는 이 워크플로우를 SSOT로 유지합니다. + +## 한 줄 결론 + +- 이 워크플로우는 `51123 Fluent Bit -> OpenSearch 적재 중단`을 샤드 포화 기준으로 판별하고, 새 일자 인덱스로 복구하는 표준 절차입니다. diff --git a/workflow/README.md b/workflow/README.md index 3d61638..a23a42a 100644 --- a/workflow/README.md +++ b/workflow/README.md @@ -26,6 +26,7 @@ tags: [infra, workflow, docs, operations] | [51123_nas_remote_operations_workflow.md](./51123_nas_remote_operations_workflow.md) | NAS 원격 작업 전체 흐름 (점검·cron·동기화) | | [51123_nas_sync_verification_workflow.md](./51123_nas_sync_verification_workflow.md) | 51123 → 내부 NAS 동기화 점검 상세 절차 | | [51123_github_org_repo_bootstrap_workflow.md](./51123_github_org_repo_bootstrap_workflow.md) | GitHub org 기준 새 프로젝트·다중 레포 생성 | +| [51123_log_ingest_recovery_workflow.md](./51123_log_ingest_recovery_workflow.md) | 51123 Fluent Bit -> OpenSearch 로그 적재 복구 절차 | | [51124_remote_workspace_config_operations_workflow.md](./51124_remote_workspace_config_operations_workflow.md) | 24 서버 SSH 접속과 workspace-config 원격 수정·검증 | | [local_developer_workflow.md](./local_developer_workflow.md) | 로컬 PC 워크스페이스 레포 동기화·푸시 |