Apache Fluss 플러그인
Apache Fluss 플러그인은 Fluss 클러스터를 Konduo 리소스로 등록하고 CoordinatorServer, TabletServer, 버킷, 복제, 요청 경로, 스토리지 및 JVM 상태를 모니터링합니다.
주요 기능
- 여러 bootstrap 주소를 통해 Fluss 프로토콜을 협상하고 Coordinator와 활성 TabletServer를 탐색합니다.
- Prometheus 매핑팩으로 27개 Fluss 논리 메트릭을 제공합니다.
핵심과상세화면의 27개 기본 패널에서 클러스터, 처리량, 복제 안정성, 요청 적체, 스토리지 및 JVM 자원을 모니터링합니다.- 진단 요약은 범주별 상태를 보여주고 상세 화면은 판단 근거와 권장 조치를 제공합니다.
- 직접 연결 근거와 연결된 Prometheus의 기간 메트릭 근거를 구분합니다.
- 카탈로그에서 데이터베이스와 테이블을 선택해 Log 및 Primary-key 데이터를 제한적으로 조회·변경하고, 구성·ACL·서버 태그·리밸런스를 권한과 안전 점검에 따라 운영합니다.
등록 전 준비
- Konduo 백엔드에서 접근 가능한 Fluss CoordinatorServer 또는 TabletServer
host:port주소를 하나 이상 준비합니다. - 모든 CoordinatorServer와 TabletServer에서 Prometheus reporter를 활성화합니다.
- Prometheus가 각 서버의 메트릭 엔드포인트를 수집하는지 확인합니다.
- Fluss 리소스에 대상 Prometheus 리소스를 메트릭 소스로 연결합니다.
- Fluss 버전이나 reporter scope가 기본 매핑과 다르면 실제 메트릭 이름과 라벨을 확인하고 환경별 매핑 규칙을 준비합니다.
연결 설정
| 항목 | 필수 여부 | 기본값 | 설명 |
|---|---|---|---|
endpoint | 필수 | localhost:9123 | 쉼표로 구분한 CoordinatorServer 또는 TabletServer host:port bootstrap 주소 |
security_protocol | 필수 | PLAINTEXT | PLAINTEXT, TLS, SASL_PLAINTEXT, SASL_TLS 중 하나 |
sasl_mechanism | SASL 사용 시 | PLAIN | Fluss 0.9.1이 지원하는 PLAIN 방식 |
sasl_username, sasl_password | SASL 사용 시 | 없음 | PLAIN 인증 정보이며 비밀번호는 secret으로 저장 |
tls_ca_cert | TLS 선택 | 시스템 CA | PEM CA 인증서 |
tls_client_cert, tls_client_key | TLS 선택 | 없음 | PEM 클라이언트 인증서 쌍 |
tls_server_name | TLS 선택 | 자동 | 인증서 서버 이름 재정의 |
tls_skip_verify | TLS 선택 | false | 인증서 검증 비활성화. 격리된 시험 환경에서만 사용 |
dial_timeout_seconds | 선택 | 10 | 연결별 dial 제한, 1~300초 |
request_timeout_seconds | 선택 | 15 | 프로토콜 요청 제한, 1~300초 |
read_max_attempts | 선택 | 2 | 안전한 조회의 시도 횟수, 1~3. 변경 요청은 자동 재시도하지 않음 |
| 메트릭 소스 연결 | 메트릭 사용 시 필수 | 없음 | 모든 Fluss 서버를 수집하는 prometheus-plugin 리소스 |
연결 테스트는 fluss-go v0.1.0-beta.10으로 Apache Fluss 0.9.1-incubating 프로토콜을 협상하고 CoordinatorServer와 활성 TabletServer 메타데이터를 조회합니다. TCP 연결만 성공한 경우는 정상으로 판정하지 않습니다.
여러 bootstrap 주소를 설정하면 일부 서버만 실패해도 남은 경로로 클러스터 탐색을 계속할 수 있습니다. 쉼표로 구분하되 스킴이나 경로가 아닌 실제 서버의 host:port를 사용합니다.
등록 및 검증 절차
- 서로 다른 장애 영역에 있는 CoordinatorServer 또는 TabletServer 주소를 가능하면 둘 이상
endpoint에 입력합니다. - 연결 테스트에서 프로토콜 협상 성공, Coordinator 1개와 예상한 활성 TabletServer 수를 확인합니다.
- 모든 CoordinatorServer와 TabletServer의 Prometheus reporter endpoint를 Prometheus가 수집하는지 확인합니다.
- 해당 Prometheus 리소스를 Fluss의 메트릭 소스로 연결합니다.
- 클러스터 개요에서 활성 CoordinatorServer·TabletServer와 오프라인 버킷 수가 실제 배포와 일치하는지 확인합니다.
- CoordinatorServer와 TabletServer의 CPU·힙 패널에 서버별 라벨이 구분되어 표시되는지 확인합니다.
- 복제와 요청 진단에서
사용 불가가 표시되면 정상으로 간주하지 말고 논리 메트릭의 조회 경로와 실제 reporter scope를 확인합니다. - CE에는 관리 경보 규칙팩이 없으므로 필요한 논리 메트릭을 일반 경보 구성에 명시적으로 추가합니다.
프로토콜 상태, 서버별 Prometheus 수집과 논리 메트릭 매핑은 서로 다른 검증입니다. 프로토콜 탐색 성공만으로 버킷, 메트릭 또는 애플리케이션 데이터가 정상이라고 판정하지 않습니다.
처음 사용하는 운영자 빠른 경로
- 리소스를 등록하고
연결 테스트에서 프로토콜 협상, Coordinator 및 활성 TabletServer 탐색 결과를 확인합니다. - 모든 Fluss 서버를 수집하는 Prometheus 리소스를 연결한 뒤
대시보드 > 핵심에서 클러스터와 복제 상태를 확인합니다. 이상이 있으면상세에서 요청 적체와 스토리지 근거를 함께 봅니다. 진단 > 요약에서정상,부분 근거,사용 불가를 구분합니다. 원인을 좁힐 때는 범주별 상세 화면과이력의 기간 근거를 확인합니다.운영 > 카탈로그에서 데이터베이스 행의 테이블 작업을 선택하고, 테이블 유형에 맞는Log 데이터또는Primary-key 데이터화면으로 이동합니다. 데이터베이스와 테이블 이름은 선택한 행에서 이어집니다.- 변경 작업은 먼저 사전 점검 결과를 검토합니다. 웹 UI는 대상에서 계산한 확인값을 읽기 전용으로 제공하며, 위험 작업은 별도의 최종 확인을 한 번 더 요구합니다.
- 요청 결과를 알 수 없거나
조정 대기로 끝난 작업은 바로 반복하지 말고 카탈로그, 제한 조회 또는 작업 상세에서 권위 있는 현재 상태를 먼저 확인합니다.
운영 화면은 Fluss 명령 콘솔을 대체하는 범용 SQL 도구가 아닙니다. 목록, 조회와 변경은 모두 화면에 표시된 대상과 제한 범위 안에서 실행됩니다.
읽기 전용 운영 기능
해당 fluss-plugin.operations.*.read 권한이 있는 운영자는 Coordinator를 기준으로 다음 클러스터·카탈로그 정보를 조회할 수 있습니다.
| 영역 | 경로 | 내용 |
|---|---|---|
| 클러스터 | operations/cluster, operations/servers | Coordinator와 활성 TabletServer의 ID, 역할, 주소, rack |
| 데이터베이스 | operations/databases, operations/databases/detail | 설명, 속성, 생성·수정 시각과 테이블 수 |
| 테이블 | operations/tables, operations/tables/detail | 종류, 버킷, 행 수, 버킷별 오프셋 범위 요약, 전체 논리 스키마와 속성 |
| 파티션 | operations/partitions | 선택적인 부분 partition_spec JSON 필터 |
| 오프셋·통계 | operations/tables/offsets, operations/tables/stats | 버킷별 오프셋 범위, 선택적 시각 기준 오프셋과 행 수 |
| 구성 | operations/cluster-config | 유효 설정값과 서버가 보고한 출처 |
| ACL | operations/acls | 필터와 일치하는 접근 제어 항목 및 사람이 읽을 수 있는 enum |
목록 경로는 search, offset, limit을 지원하며 최대 limit은 1,000입니다. 테이블 경로에는 database와 table이 필요합니다. 파티션 대상은 {"region":"kr"} 같은 JSON 문자열 맵으로 지정합니다. 일부 버킷 실패는 전체 결과를 성공 또는 실패로 축약하지 않고 partial 상태와 개별 오류로 반환합니다. 사용 불가, 권한 거부, 잘못된 입력과 빈 목록을 서로 구분합니다.
카탈로그 UI는 테이블 컴포넌트가 페이지네이션을 담당하므로 데이터베이스·테이블 목록 위에는 검색만 표시합니다. API 자동화에서는 계속 offset과 limit을 사용할 수 있습니다. 데이터베이스와 테이블 삭제는 각 행에서 실행하며, 선택 대상과 예상 테이블·스키마 ID 및 확인 문구는 행에서 자동으로 읽기 전용 설정됩니다. 운영자는 수기 재입력 대신 dry-run을 실행하고 마지막 위험 작업 확인을 승인합니다. 테이블 변경과 파티션 진입도 선택한 테이블 행에서 수행합니다. 파티션 화면은 선택한 데이터베이스·테이블·예상 ID를 이어받는 숨김 drill-down이며 파티션 삭제는 해당 파티션 행에서 실행합니다.
Log와 Primary-key 테이블의 행 수와 오프셋 범위는 테이블 목록에 바로 표시됩니다. 행 수는 버킷 통계를 합산하고, 최대 세 버킷의 최초·최신 오프셋을 한 셀에 요약하며, 모든 버킷의 숫자 간격 합계를 함께 표시합니다. 오프셋 간격 합계는 정확한 행 수가 아닙니다. 파티션 테이블은 테이블 전체에 단일 범위와 행 수가 없으므로 두 항목 모두 파티션별로 표시합니다. 시각 기준 오프셋이 필요한 자동화는 operations/tables/offsets API에 RFC3339 timestamp를 전달할 수 있습니다. 테이블 목록의 통계·오프셋 보강은 테이블마다 여러 Coordinator 요청이 필요하므로 30초 자동 polling을 하지 않고 진입 또는 수동 새로고침 때만 실행합니다. 각 행의 운영 데이터 상태는 정상, 부분, 사용 불가 또는 파티션별로 표시되어 불완전한 합계를 정상값으로 오인하지 않게 합니다.
클러스터 구성과 ACL 운영
operations/cluster-config는 서버의 유효 설정값과 출처를 함께 반환하며 자격 증명으로 보이는 키의 값은 항상 마스킹합니다. fluss-plugin.operations.config.write 권한과 admin 역할이 있는 운영자는 operations/cluster-config/apply에서 환경별 허용 목록에 포함된 설정을 한 번에 최대 20개 변경할 수 있습니다. SET, DELETE, APPEND, SUBTRACT를 지원합니다. dry-run은 선택적인 expected_value, expected_source로 stale 작업을 막고 실제 값 대신 전후 비교용 fingerprint를 남깁니다. 실제 적용 문구는 APPLY CLUSTER CONFIG <environment>이며, 한 번만 요청한 뒤 권위 있는 설정 조회로 결과를 확인합니다. 화면의 기본 편집 모드는 현재 설정 목록에서 키와 새 값을 선택하는 key/value 편집기이며 SET을 적용합니다. DELETE, APPEND, SUBTRACT 또는 예상값·출처 검증은 고급 JSON 모드를 사용합니다.
operations/acls는 resource, principal, host, operation, permission 필터를 지원합니다. operations/acls/create는 명시적인 ALLOW 항목만 허용하며 operations/acls/drop은 전체 wildcard 삭제를 거부합니다. 실제 변경에는 각각 CREATE ACLS <개수>, DROP ACLS <개수> 문구가 필요합니다. 항목별 성공·실패를 보존하고 변경 후 목록을 다시 읽어 확인합니다. User, Group, Role principal은 fluss-go가 제공하는 타입 안전한 정식 ACL 계약을 사용합니다. 화면에서는 단일 ACL을 구조화된 필드로 생성하고, 일괄 생성이 필요할 때만 고급 JSON을 사용합니다. 삭제 대상은 ACL 행에서 선택되며 정확한 필터와 확인 문구가 자동 설정됩니다. Fluss authorizer가 꺼진 상태는 권한 거부와 별도 오류로 표시됩니다. production, staging, development에는 리소스별 cooldown이 적용되고 test에는 적용되지 않습니다. 화면은 필터보다 먼저 ACL·보안 주체·대상 리소스·모든 작업 권한 수를 요약합니다. 리소스와 작업 유형은 서버 필터로 제공하고, 목록 통합 검색은 보안 주체·리소스·접속 호스트 등 표시된 텍스트를 찾습니다. 목록은 보안 주체, 리소스, 작업, 접속 호스트 순서로 구성합니다. 현재 Fluss 계약에서 생성하는 ACL은 ALLOW로 고정되므로 권한은 목록 열을 차지하지 않고 상세 시트에서 확인합니다.
서버 유지보수와 리밸런스
관리자 전용 유지보수 기능은 raw 정수 대신 Fluss 0.9의 공식 이름만 받습니다. 서버 태그는 PERMANENT_OFFLINE, TEMPORARY_OFFLINE이며 리밸런스 goal은 REPLICA_DISTRIBUTION, LEADER_DISTRIBUTION, RACK_AWARE입니다. 태그 변경 경로는 operations/servers/tags/add와 operations/servers/tags/remove입니다. Fluss에 서버측 preview가 없으므로 dry-run은 현재 TabletServer, rack, 대상 ID를 확인하는 local preflight라고 명확히 표시합니다.
운영 화면은 goal 이름을 직접 입력받지 않고 안전한 리밸런스 정책을 선택지로 제공합니다. 기본값은 복제본과 리더를 함께 균형화합니다. 다중 랙 클러스터에서는 랙 분산 후 복제본과 리더 균형 정책을 선택합니다. RACK_AWARE는 뒤의 goal이 랙 제약을 유지하도록 반드시 첫 번째여야 하며 API도 잘못된 순서를 거부합니다.
Fluss 0.9 프로토콜에는 현재 태그를 조회하는 API가 없습니다. 영구 오프라인 태그의 추가·제거는 Coordinator metadata 변화로 확인할 수 있지만, 임시 오프라인 태그처럼 확인할 수 없는 결과는 성공으로 단정하지 않고 reconciliation pending으로 남기며 자동 재시도하지 않습니다.
operations/rebalances/start는 활성 TabletServer가 3개 이상인지 확인하고 rack label과 전달된 offline/under-replicated bucket evidence를 점검합니다. 서버가 반환한 rebalance ID를 작업 참조로 사용하며 알려진 작업이 실행 중이면 중복 시작을 막습니다. operations/rebalances/detail에 ID를 전달해 table/bucket별 상태, 원래·새 leader와 replica를 polling합니다. 운영 화면은 해당 리소스 인스턴스에서 시작해 추적 중인 ID를 자동으로 사용하고 읽기 전용 진행 정보로 표시하므로 다시 입력할 필요가 없습니다. 운영자는 리밸런스 goal 우선순위만 선택하며 버킷 이동 계획은 Coordinator가 계산합니다. 화면은 반환된 계획을 버킷별 표로 표시합니다. 명시적인 ID는 API 호출이나 별도 작업 조회에 계속 사용할 수 있습니다. operations/rebalances/cancel은 실행 중과 이미 끝난 작업을 구분하며 이미 완료된 이동은 되돌리지 않는다는 경고를 반환합니다. 모든 실제 action은 정확한 확인 문구와 cooldown을 거치고 한 번만 요청한 뒤 Coordinator에서 다시 읽습니다.
운영 페이지, 접근 제어, 감사
리소스 대시보드는 /resources/{resourceInstanceId}/manage/operations에 읽기·쓰기 운영 작업 공간을 제공합니다. 화면은 선언형 operations/schema 계약을 읽어 클러스터, 카탈로그, 리밸런스, 보안의 4개 탭을 표시합니다. 클러스터 화면은 Coordinator와 TabletServer 수를 서버 목록과 함께 보여주며, 클러스터 설정은 이 화면에서 문맥형 하위 작업 공간으로 엽니다. 카탈로그의 데이터베이스 행을 선택하면 메타데이터와 속성을 간결한 상세 시트에서 확인하고, 테이블 목록 작업을 선택하면 해당 데이터베이스의 테이블로 이동합니다. 테이블 목록은 권위 있는 테이블 유형을 확인해 Log Data 또는 Primary-key Data 작업만 표시하고 행 수와 오프셋 범위를 함께 보여주며, 선택한 데이터베이스와 테이블을 다음 화면에 자동으로 전달합니다. 테이블 상세, 파티션, point/prefix 조회는 선택한 문맥과 상위 화면으로 돌아갈 경로를 유지하는 숨김 drill-down 탭입니다.
모든 탭과 action은 manifest의 접근 카탈로그를 참조합니다. viewer는 클러스터·카탈로그·설정과 제한형 데이터 결과를 조회할 수 있고, editor는 비파괴 카탈로그·데이터 쓰기를 수행할 수 있습니다. 유지보수, ACL·설정 변경, 카탈로그 삭제, 데이터 삭제에는 admin이 필요합니다. 화면을 거치지 않는 직접 API 호출도 core proxy가 같은 capability descriptor로 검사하므로, 버튼 숨김만으로 권한을 판단하지 않습니다.
운영 기능의 최소 역할과 권한은 다음과 같습니다. 역할을 부여해도 대응하는 권한 패턴이 없으면 실행할 수 없습니다.
| 작업 범위 | 최소 역할 | 대표 권한 패턴 |
|---|---|---|
| 클러스터·카탈로그·구성·제한 데이터 조회 | viewer | operations.cluster.read, operations.catalog.read, operations.config.read, operations.data.read |
| 데이터베이스·테이블·파티션 생성·변경, Log/KV 쓰기 | editor | operations.catalog.write, operations.data.write |
| ACL 및 리밸런스 조회 | admin | operations.security.read, operations.maintenance.read |
| 구성·ACL·서버 태그·리밸런스 변경 | admin | operations.config.write, operations.security.write, operations.maintenance.write |
| 카탈로그 및 Primary-key 데이터 삭제 | admin | operations.catalog.delete, operations.data.delete |
위 표의 권한에는 실제로 fluss-plugin. 접두사가 붙습니다. 예를 들어 제한 데이터 조회의 전체 권한은 fluss-plugin.operations.data.read입니다.
생성 폼의 새 객체 이름과 자유 입력 payload는 빈 값으로 시작합니다. 새 테이블의 현재 데이터베이스처럼 명시된 상위 문맥만 자동 설정하며, 목록의 첫 행이나 이전에 선택한 행 값을 생성 폼으로 복사하지 않습니다.
조회에는 제한된 페이지 크기·검색·갱신 주기가 적용됩니다. Log 및 Primary-key 데이터의 명시적 조회는 요청 처리 중에만 중복 실행을 막으며, 완료 후 별도의 UI cooldown을 두지 않습니다. 쓰기 폼은 dry-run으로 시작하고 실제 요청 전에 대상에서 파생한 정확한 확인 문구를 요구합니다. 성공 후에도 제한된 횟수의 재조회만 수행합니다. Dry-run 결과는 실행 전 검토를 위해 작업 모달 안에 표시합니다. 실제 변경 성공은 일시적인 성공 알림으로만 안내하며 결과 테이블 헤더에 같은 문구를 중복해서 남기지 않습니다. 검증·실행 오류는 작업 모달 안에 유지하고 오류 알림도 표시합니다. 모달을 닫은 뒤에는 블록 헤더, 행 작업 영역, 상세 시트의 실행 버튼 옆에 이전 피드백 문구를 남기지 않습니다. 호출자가 별도 request ID를 주지 않으면 core 감사 request ID를 실행 ID로 재사용합니다. 감사 증거에는 대상·경로·요청·결과·실행 참조만 남기고, 인증 정보, 행·키 payload, ACL 본문, 설정 변경값, Arrow batch, client key는 마스킹하며 작업 메시지에 원문을 포함하지 않습니다.
웹 UI는 현재 파라미터 또는 선택한 행으로 경로별 실행 확인값을 자동 생성해 읽기 전용으로 표시합니다. 운영자가 명령문 형태의 문구를 다시 입력할 필요는 없습니다. API를 직접 호출할 때는 정확한 값을 전달해야 하며, 삭제 같은 위험 작업은 별도의 최종 확인 단계를 유지합니다.
결과 표의 필터는 이미 반환된 현재 페이지를 브라우저에서 좁혀 보는 기능입니다. 서버에 조건식을 전달하는 검색창이 아니며, Fluss의 임의 WHERE 조건이나 전체 테이블 검색을 수행하지 않습니다. 긴 행 데이터는 표에서 줄임 표시하고 선택한 행의 상세 시트에서 전체 구조와 복사 기능을 제공합니다.
Log Table 데이터 운영
fluss-plugin.operations.data.read 권한으로 operations/tables/log/scan에서 Log Table을 제한적으로 조회합니다. 기본 100행, 최대 1,000행이며 최대 16 MiB·30초를 넘길 수 없습니다. start_kind는 latest_backward, latest_forward, earliest, timestamp, offset을 지원하며(latest는 API에서 latest_forward 별칭으로 유지), API의 timestamp는 RFC3339, offset은 0 이상의 정수입니다. 웹 UI에서는 애플리케이션 시간대로 시각을 입력합니다. Konduo는 요청 전에 UTC RFC3339로 변환하고, 반환된 기록 시각도 같은 애플리케이션 시간대로 표시합니다. projection, partition_spec_json, 버킷별 배타적 종료 offset을 담은 stopping_offsets_json을 선택적으로 지정합니다. projection 컬럼은 테이블 스키마로 검증한 뒤 제한된 row 및 Arrow 결과에 플러그인이 적용하고, 파티션과 종료 offset 옵션은 스캐너에 전달합니다. 스냅샷 방식은 조회 전에 버킷별 현재 끝 offset을 고정하므로, 최대 100행을 요청해도 현재 데이터가 그보다 적으면 확보된 행만 즉시 반환합니다. 결과에는 버킷, offset, high watermark, scan_mode, completion_reason이 포함되며 일부 버킷 실패는 partial과 개별 오류로 남습니다. 이 경로는 무제한 tail이나 서버 전체 검색이 아닙니다.
웹 UI의 조회 시작점은 다음처럼 사용합니다.
| 선택 | 동작 | 추가 입력 |
|---|---|---|
| 처음부터 | 선택한 버킷의 현재 최초 offset부터 요청 시점의 최신 offset까지만 조회 | 없음. 기본값 |
| 최근 데이터 | 선택 버킷에 최대 행 수를 배분하고 요청 시점의 최신 행부터 미래 데이터를 기다리지 않고 반환 | 없음 |
| 신규 데이터 대기 | 요청 시점의 최신 offset부터 앞으로 추가되는 행을 대기·조회 | 없음. 행·바이트·시간 제한에서 반환 |
| 오프셋 지정 | 선택한 각 버킷에 같은 0 이상 시작 오프셋을 적용 | 시작 오프셋 |
| 시각 지정 | 해당 시각 이후의 버킷별 오프셋을 찾아 조회 | 웹 UI는 로컬 날짜·시각, API는 시간대가 포함된 RFC3339 시각 |
조회할 열에는 clerk,customer_id처럼 반환할 컬럼 이름을 쉼표로 구분합니다. 이 값은 행을 찾는 조건이 아닙니다. clerk를 입력하면 모든 대상 행에서 clerk 컬럼만 반환하며, clerk 값으로 행을 검색하지 않습니다. 비워두면 모든 컬럼을 반환합니다.
operations/tables/log/append는 JSON 행을 권위 있는 테이블 스키마로 검증하거나, 스키마가 같은 Arrow IPC record batch 하나를 받습니다. JSON 행은 단일 객체가 아니라 [{"id":1,"payload":"value"}] 형태의 비어 있지 않은 객체 배열로 rows_json에 입력합니다. Arrow는 arrow_ipc_base64와 명시적 bucket을 사용합니다. auto(버킷 키가 있으면 hash), sticky, round-robin 배정과 auto/indexed/compacted 행 형식, Arrow NONE/LZ4/ZSTD 압축을 지원합니다.
예를 들어 선택한 테이블 스키마가 id, event_type, payload를 요구하면 다음처럼 배열로 입력합니다.
[
{"id": 1, "event_type": "CREATED", "payload": "value"}
]단일 객체 {...}는 허용하지 않습니다. 필드 이름, 필수 여부와 값 형식은 예제가 아니라 선택한 테이블의 권위 있는 스키마를 따릅니다. 파티션 테이블의 파티션 명세 JSON만 {"region":"kr"} 같은 객체 하나이며 행 배열에 포함하지 않습니다.
append는 fluss-plugin.operations.data.write와 editor 역할이 필요하며 항상 dry_run=true로 시작합니다. 실제 쓰기에는 APPEND LOG <database.table> 확인 문구가 필요합니다. Konduo는 쓰기를 기본 1회 시도합니다. 운영자가 write_max_attempts를 2~3회로 명시하면 writer ID, 버킷 sequence와 인코딩된 bytes를 보존하는 fluss-go 멱등 재시도를 사용하며 acks=-1이 필수입니다. 버킷이 여러 개여도 운영 결과와 부분 실패 증거의 순서를 보존하도록 직렬 처리합니다. 선택한 시도 횟수 이후의 결과 불명확은 offset 조회나 제한 scan으로 확인합니다.
Primary-key Table 데이터 운영
operations/tables/kv/lookup과 operations/tables/kv/prefix-lookup은 keys_json의 복합 키 입력 순서를 유지합니다. point lookup은 전체 PK, prefix lookup은 비어 있지 않은 leading PK 부분집합만 허용합니다. 각 결과에는 input_index, 키 또는 prefix, 버킷과 found, not_found, 개별 오류 상태가 있습니다. 제한형 scheduler는 최대 1,000키 queue, 고정 1ms batch 지연, 설정된 request timeout과 read_max_attempts를 적용합니다. 상태를 변경할 수 있는 insert-if-not-exists는 1회만 시도합니다.
웹 UI의 조회 방식은 다음과 같습니다.
| 조회 방식 | 입력 | 용도 |
|---|---|---|
| 목록 조회 | 선택적 조회 컬럼과 최대 행 수 | 버킷을 순회해 제한된 현재 행을 탐색 |
| 키 조회 | [{"customer_id":0}] 같은 전체 Primary Key 객체 배열 | 알고 있는 키의 현재 행을 정확히 조회 |
| 접두 키 조회 | [{"region":"kr"}] 같은 leading key 객체 배열 | 복합 Primary Key의 앞쪽 컬럼으로 제한 조회 |
키 입력은 객체 하나가 아니라 객체 배열입니다. 복합 Primary Key가 region, customer_id 순서라면 키 조회에는 두 컬럼이 모두 필요하고, 접두 키 조회에는 region만 사용할 수 있습니다. customer_id만 입력하는 것은 앞쪽 컬럼을 건너뛰므로 허용되지 않습니다.
operations/tables/kv/scan은 현재 bucket leader의 안정적인 목록을 얻어 각 버킷을 제한적으로 조회합니다. 기본 100행, 최대 1,000행·16 MiB·30초 예산과 projection을 적용하며 버킷 하나의 실패는 partial로 남깁니다. 파티션 테이블에는 정확한 partition_spec_json이 필수이므로 동적 파티션의 경계를 암묵적으로 넘지 않습니다.
전체 행은 operations/tables/kv/upsert, PK와 변경할 열만 있는 행은 operations/tables/kv/partial-upsert에 전달합니다. 기본 merge engine과 명시적 overwrite를 지원하되 overwrite에는 테이블 merge-engine 설정이 필요합니다. operations/tables/kv/insert-if-not-exists는 누락된 키를 원자적으로 생성할 수 있으므로 읽기 query가 아니라 write action입니다. Upsert와 insert는 전체 Primary Key와 모든 필수 컬럼을 가진 객체 배열, partial upsert는 전체 Primary Key와 변경할 컬럼을 가진 객체 배열을 입력합니다. 삭제도 [{"primary_key":1}] 형태의 전체 Primary Key 객체 배열을 사용합니다. 파티션 명세만 배열이 아닌 JSON 객체 하나입니다.
다음 예시는 Primary Key가 customer_id인 경우의 입력 모양입니다. 실제 컬럼과 값 형식은 선택한 테이블 스키마를 따릅니다.
| 작업 | 필요한 행 모양 | 예시 |
|---|---|---|
| Upsert | 전체 Primary Key와 모든 필수 컬럼 | [{"customer_id":0,"name":"Alice","balance":"146.30"}] |
| 부분 Upsert | 전체 Primary Key와 변경할 컬럼 하나 이상 | [{"customer_id":0,"balance":"200.00"}] |
| 없을 때 삽입 | Upsert와 같은 완전한 행 | [{"customer_id":1,"name":"Bob","balance":"0.00"}] |
| 삭제 | 전체 Primary Key만 | [{"customer_id":1}] |
웹 UI는 행 배열 JSON과 Primary Key 배열 JSON을 구분해 안내하고 단일 객체를 제출 전에 거부합니다. 쓰기 성공은 일시적인 알림으로 표시하고 목록을 다시 읽습니다. 오류는 작업 모달에서 입력과 함께 확인할 수 있으며, 긴 서버 오류 문구를 결과 표 헤더에 남기지 않습니다.
upsert·partial upsert·insert는 operations.data.write, 삭제는 별도의 operations.data.delete와 admin 역할이 필요합니다. 모든 action은 dry-run과 대상별 확인 문구를 거치며, 삭제 문구는 DELETE KV <database.table>입니다. KV writer action은 기본 1회이며, 운영자가 명시한 경우에만 acks=-1 조건에서 최대 3회의 멱등 재시도를 사용합니다. insert-if-not-exists는 재시도하지 않습니다. 적용 결과는 point lookup으로 다시 확인하고, 확인하지 못하면 성공으로 단정하거나 쓰기를 반복하지 않고 reconciliation pending으로 반환합니다.
카탈로그 수명주기
데이터베이스, 테이블, 파티션의 생성·변경·삭제 action은 기본적으로 dry_run=true입니다. 사전 점검 요약과 최신 상세 정보를 확인한 다음 실행합니다. 웹 UI는 대상에서 생성된 정확한 확인값을 읽기 전용으로 설정하므로 운영자가 다시 입력하지 않습니다. 아래 문구는 API 호출자가 confirmation_phrase에 전달하는 계약입니다.
CREATE DATABASE <database>또는DROP DATABASE <database>CREATE TABLE <database.table>,ALTER TABLE <database.table>,DROP TABLE <database.table>CREATE PARTITION <database.table>또는DROP PARTITION <database.table> <partition-name>
테이블 변경·삭제와 파티션 action에는 사전 점검에서 확인한 테이블 ID와 스키마 ID를 expected_table_id, expected_schema_id로 전달합니다. 값이 바뀌었으면 stale 작업으로 거부하고 변경 요청을 보내지 않습니다. schema_json은 Fluss 논리 스키마를 보존하며, 최상위 partition_key와 bucket_key 배열은 선언된 컬럼을 참조해야 합니다. alter_json은 설정의 set/delete/append/subtract, 컬럼 추가·삭제·이름 변경을 묶습니다. partition_spec은 테이블 파티션 키와 일치해야 합니다.
테이블 생성 모달은 다음과 같은 검증된 Primary-key Table 예시를 제공합니다. Log Table을 만들 때는 필요한 컬럼과 키를 유지하되 primary_key를 []로 지정합니다.
{
"version": 1,
"columns": [
{"name": "id", "data_type": {"type": "BIGINT", "nullable": false}, "id": 0},
{"name": "value", "data_type": {"type": "STRING", "nullable": true}, "id": 1}
],
"primary_key": ["id"],
"partition_key": [],
"bucket_key": ["id"],
"auto_increment": [],
"highest_field_id": 1
}Konduo는 이 변경 요청을 자동 재시도하지 않습니다. 한 번 요청한 뒤 권위 있는 조회로 다시 확인합니다. 응답이 유실되면 결과를 알 수 없음으로 표시하므로 해당 조회 경로에서 현재 상태를 확인한 뒤 재시도 여부를 판단해야 합니다. 데이터베이스 cascade 및 테이블·파티션 삭제는 관리자 권한이 필요한 위험 action입니다.
현재 릴리스의 통합 검증 기준은 다음과 같습니다.
| 항목 | 검증 기준 | 해석 |
|---|---|---|
| Apache Fluss | 0.9.1-incubating, CoordinatorServer 1개와 TabletServer 3개 | 이 버전을 현재 운영 기능 호환 기준으로 사용합니다. |
| Go 클라이언트 | github.com/pletorco/fluss-go v0.1.0-beta.10 | fgo 데이터 프로토콜과 fadm 관리 프로토콜을 함께 검증합니다. 선택형 저장소·관측 어댑터 모듈은 플러그인 의존성에 포함하지 않습니다. |
| 일반 연결과 인증 | PLAINTEXT, SASL/PLAIN | Fluss 0.9.1의 native listener를 사용합니다. |
| TLS | TLS termination을 거친 PLAINTEXT와 SASL/PLAIN | Fluss 0.9.1의 native TLS 지원으로 해석하면 안 됩니다. |
| 장애 시나리오 | TabletServer 중단·복구, CoordinatorServer 중단 | TabletServer 복구와 서비스 상태 갱신을 검증합니다. Fluss 0.9.1은 CoordinatorServer HA를 제공하지 않으므로 Coordinator 중단은 정상적인 failover가 아니라 unavailable로 판정합니다. |
통합 검증은 카탈로그 수명주기, Log·Primary-key 데이터 경로, 구성·ACL, 리밸런스, 취소와 정리 절차를 포함합니다. 지원 기준 밖 Fluss 또는 fluss-go 조합은 운영에 적용하기 전에 동일한 경로를 별도로 검증하십시오.
대시보드와 메트릭
기본 대시보드는 핵심과 상세 서브페이지에 27개 패널을 제공합니다.
핵심 서브페이지에는 다음 영역이 있습니다.
- 클러스터 개요: 활성 CoordinatorServer·TabletServer, 오프라인 버킷, 테이블 및 버킷 수
- 처리량: 초당 메시지, 입력 바이트 및 출력 바이트
- 복제 안정성: 최소 ISR 미달, ISR 축소, ISR 갱신 실패 및 요청 오류
- JVM 자원: CoordinatorServer와 TabletServer CPU 및 힙 사용률
상세 서브페이지에는 다음 영역이 있습니다.
- 복제 여유: 복제 부족 및 최소 ISR 경계 버킷
- 요청 처리: 요청 처리율·대기열, 지연 쓰기·fetch 및 만료 쓰기
- 스토리지: 논리 Log/KV와 물리 로컬/원격 로그 크기
따라서 기본 메트릭 카탈로그의 모든 논리 메트릭은 하나의 기본 대시보드 패널을 가집니다. 핵심 화면에서 이상을 발견한 뒤 상세 화면에서 복제 여유, 요청 적체와 용량 증가 추이를 함께 확인하십시오.
기본 매핑팩은 Apache Fluss 0.9 계열 Prometheus 메트릭 이름을 기준으로 합니다. 예를 들어 메시지 입력은 fluss_tabletserver_messagesInPerSecond, 최소 ISR 미달은 fluss_tabletserver_underMinIsr를 사용합니다.
요청 메트릭은 request_produceLog, request_putKv, request_fetchLogClient처럼 요청 유형별 scope로 노출됩니다. 따라서 플러그인은 존재하지 않는 단일 일반 요청 메트릭을 기대하지 않고 요청 유형별 이름을 묶어 집계합니다.
진단 화면
진단 요약은 다음 다섯 범주의 상태와 건수를 짧게 보여줍니다.
- 클러스터: bootstrap TCP 접근성, 실제 Fluss 프로토콜 협상, Coordinator 메타데이터, 활성 CoordinatorServer·TabletServer, 카탈로그 읽기 경로와 오프라인 버킷
- 복제: 최소 ISR 미달, 최소 ISR 경계, 복제 부족 및 ISR 갱신 실패
- 요청: 요청 오류·대기열, 지연 쓰기·fetch 및 만료 쓰기
- 스토리지: 논리·로컬·원격 스토리지와 쓰기 지연
- 런타임: 서버별 CPU와 JVM 힙 압박
화면은 요약, 클러스터, 복제, 요청, 스토리지, 런타임, 이력 순서로 구성됩니다. 요약은 현재 분류 상태를 빠르게 선별하는 화면이고, 범주별 화면은 관측값·판단 기준·영향·다음 조치를 보여줍니다. 이력은 연결된 메트릭 소스에서 1h, 6h, 24h, 7d, 14d, 30d 기간의 반복 위험과 추이를 확인합니다. 이력 데이터가 없다는 이유만으로 현재 Fluss 상태를 정상으로 판단하지 않습니다.
상세 화면에서 관측값, 판단 기준, 영향, 근거 신선도와 다음 조치를 확인할 수 있습니다. 요약 행은 상세 근거를 반복하지 않고 범주 상태만 표시합니다.
자동 라이브 점검은 전체 8초 제한 안에서 최대 3개 bootstrap 주소를 확인합니다. TCP 연결, 프로토콜 세션/TLS·SASL 협상, Coordinator 메타데이터, 카탈로그 읽기를 각각 별도 finding으로 표시합니다. Admin API의 TabletServer 수와 연결된 Prometheus의 활성 서버 수가 다르면 서버 손실과 수집 범위 누락을 구분해 표시합니다. Prometheus 수집 장애만으로 Fluss가 중단됐다고 판정하지 않습니다.
기간 기반 메트릭 진단은 선택 구간에서 최소 5개 샘플과 예상 샘플의 50% 이상을 요구합니다. 기준에 미달하면 정상이 아니라 부분 근거로 표시됩니다. 메트릭 소스 또는 매핑 문제는 사용 불가로 남습니다.
제한형 정밀 진단 실행은 자동 갱신과 분리된 수동 read-only 검사입니다. 전체 15초 안에서 데이터베이스 2개, 테이블 4개, 테이블별 파티션 2개, 물리 테이블별 버킷 8개까지만 표본으로 선택합니다. GetTableInfo와 GetTable의 schema/metadata, ResolveTableBuckets 라우팅, ListOffsets와 GetTableStats의 버킷별 성공·실패를 확인합니다. Primary-key Table은 최신 KV snapshot 존재 여부와 최신 offset 차이를 보조 근거로 표시하고, 플러그인이 추적 중인 rebalance ID가 있을 때만 진행 상태를 확인합니다. 실제 행 조회, log tail, lookup 및 모든 쓰기 작업은 수행하지 않습니다.
정밀 진단 보고서는 데이터베이스·테이블 이름, endpoint, 버킷 ID, credential, 행/key payload와 서버 오류 원문을 포함하지 않습니다. 대신 리소스 fingerprint와 제한된 성공·실패 집계만 메모리에 최대 30분, 리소스 32개까지 보관합니다. 플러그인 재시작 시 초기화되며 실행 이력을 제공하는 영구 저장소는 아닙니다.
요청 상세 진단의 Konduo Fluss 클라이언트 경로는 fluss-go observer가 수집한 15분 고정 구간의 RPC 시간, dial 실패, retry, timeout, throttle, queue, scanner lag와 decode 실패입니다. 고정 latency bucket과 리소스 fingerprint 최대 32개만 사용하며 주소·테이블 경로·버킷·payload를 저장하지 않습니다. RPC, dial, lookup, Log 쓰기, KV 쓰기, Log 조회와 remote read도 고정된 작업별 집계로 구분합니다. 이 값은 Konduo가 실행한 요청만 나타내며 Fluss 클러스터 전체 트래픽이 아닙니다.
진단 결과 해석
| 상태 또는 근거 | 의미 | 다음 확인 |
|---|---|---|
| Bootstrap 정상 | 하나 이상의 TCP 탐색 경로에 연결됨 | 활성 CoordinatorServer·TabletServer와 버킷 상태 |
| TCP 정상, 프로토콜 실패 | 포트는 열려 있지만 TLS/SASL 또는 Fluss 요청이 실패함 | 보안 모드, 인증 정보, 권한과 Coordinator 로그 |
| 제한형 읽기 경로 부분 실패 | 일부 버킷의 metadata/routing/offset/statistics만 실패함 | 실패 범주와 TabletServer 상태를 확인한 뒤 수동 재실행 |
| Bootstrap 일부 실패 | 남은 탐색 경로는 있지만 중복성이 줄어듦 | 실패한 주소의 서버, DNS, 방화벽과 장애 영역 |
| 메트릭 소스 사용 불가 | 기간 근거를 조회할 Prometheus 연결이 없음 | 모든 Fluss 서버를 수집하는 Prometheus 리소스 연결 |
| 부분 근거 | 최소 5개 또는 예상 샘플 50% 기준을 충족하지 못함 | 수집 주기, 선택 기간, target 중단과 누락 라벨 |
| 특정 역할만 데이터 없음 | 해당 역할의 reporter가 빠졌거나 scope·매핑이 일치하지 않음 | 역할별 target, 원본 메트릭 이름과 라벨 |
| 복제·요청 위험 | 단일 지표가 아니라 관련 근거를 함께 조사해야 함 | ISR, 서버 가용성, 요청 유형, 대기열과 스토리지 |
정상, 부분 근거, 사용 불가를 구분합니다. 근거가 부족한 상태를 정상으로 승격하지 않으며 Prometheus 수집 장애를 Fluss 장애로 변환하지 않습니다.
경보 지원
현재 CE Fluss 플러그인은 관리 경보 규칙팩을 제공하지 않습니다. 대시보드와 진단에서 위험 근거를 확인할 수 있지만, alerts/rules 기능이 있다고 가정해서는 안 됩니다. 경보 규칙이 추가되기 전에는 연결된 메트릭 소스의 정책과 Konduo의 일반 경보 구성에서 필요한 논리 메트릭을 명시적으로 선택하십시오.
대표 점검 절차
버킷 가용성이 저하될 때
- 활성 CoordinatorServer와 TabletServer 수를 확인합니다.
- 오프라인, 최소 ISR 미달 및 복제 부족 버킷 수를 함께 봅니다.
- ISR 축소와 ISR 갱신 실패가 같은 시각에 발생했는지 확인합니다.
- 영향받은 TabletServer의 CPU, 힙, 스토리지와 네트워크 상태를 비교한 뒤 복구 절차를 진행합니다.
요청 오류가 증가할 때
- 요청 오류율과 요청 대기열을 함께 확인합니다.
- 지연 쓰기·fetch와 만료 쓰기 여부를 확인합니다.
- 요청 유형별로 오류가 집중되는지 확인합니다.
- TabletServer 자원, 복제 상태와 스토리지 지연을 비교합니다.
스토리지가 증가할 때
- 논리 로그, KV, 로컬 및 원격 로그 크기를 구분해 확인합니다.
- TabletServer별 증가 편차와 쓰기 처리량을 비교합니다.
- 지연 쓰기나 복제 저하가 함께 발생하는지 확인합니다.
- Fluss 보존 정책과 원격 로그 이동 정책에 따라 운영 절차를 수행합니다.
관리 경계
- CE 플러그인은 운영자가 명시적으로 실행한 카탈로그·데이터·구성·ACL·서버 태그·리밸런스 작업을 안전 점검과 권한 검사 뒤 수행합니다. 메트릭이나 진단 결과만으로 테이블을 생성·삭제하거나 서버 태그와 리밸런스를 자율적으로 실행하지 않습니다.
- 지속적인 자동 복구, 정책 기반 자동 리밸런스와 임의 SQL 실행기는 제공하지 않습니다. 리밸런스의 실제 버킷 이동 계획은 Coordinator가 계산하며 플러그인은 반환된 계획과 상태를 표시합니다.
- 클러스터 공통 설정이나 공개 API에 없는 replica/ISR 배치를 서버별 메트릭에서 추정하지 않습니다. 제한형 Admin 진단은 실제 호출 결과만 근거로 사용합니다.
- Bootstrap TCP 연결 성공을 데이터 경로 정상으로 해석하지 않습니다.
- 메트릭 수집 실패와 Fluss 리소스 장애를 분리해 판단합니다.
문제 해결
| 증상 | 확인 순서 |
|---|---|
| Bootstrap 진단 전체 실패 | host:port 형식, CoordinatorServer·TabletServer 상태, 백엔드 DNS·네트워크 경로와 방화벽을 확인 |
| Bootstrap 일부만 실패 | 실패한 주소가 중복되거나 오래된 주소인지 확인하고 해당 서버와 장애 영역을 복구 |
| 연결은 정상인데 클러스터 진단이 사용 불가 | TCP만 성공했는지, protocol session·Coordinator metadata·catalog read 중 어느 단계가 실패했는지 확인 |
| 제한형 정밀 진단이 부분 근거 | 표본별 metadata/routing/offset/statistics 실패 범주와 TabletServer 상태를 확인하고 수동 재실행 |
| 모든 메트릭 패널이 비어 있음 | 모든 Fluss 서버의 reporter, Prometheus target, 메트릭 소스 연결과 Fluss 0.9 기본 매핑 적용을 확인 |
| 특정 역할만 비어 있음 | CoordinatorServer·TabletServer별 수집 대상과 실제 메트릭 scope·라벨을 확인 |
| 진단이 부분 근거 | 선택 기간의 샘플 수, 수집 간격과 target 중단 시간을 확인 |
| 요청 메트릭만 비어 있음 | request_produceLog, request_putKv, request_fetchLogClient 등 요청 유형별 scope와 매핑 정규식을 확인 |
| 사용자 정의 reporter scope 사용 후 비어 있음 | 원본 Prometheus 이름과 라벨을 확인하고 환경별 매핑 override를 적용 |
| 신규 데이터 대기가 0행 | 이 방식은 기존 행을 반환하지 않으므로 새 행을 추가하거나 처음부터·최근 데이터·오프셋·시각 기준으로 다시 조회 |
| 조회할 열을 입력했는데 원하는 값의 행이 안 나옴 | 조회할 열은 검색 조건이 아니라 반환 컬럼 선택임을 확인하고, 현재 결과의 텍스트 필터 또는 키 조회를 목적에 맞게 사용 |
rows_json must be a JSON array 검증 실패 | {...} 대신 [{...}]을 사용하고 행마다 선택한 테이블 스키마의 필수 컬럼과 전체 Primary Key를 포함 |
| 쓰기 결과가 알 수 없음 또는 조정 대기 | 같은 쓰기를 즉시 반복하지 말고 point lookup, 제한 scan 또는 카탈로그 상세로 현재 상태를 확인 |
| 리밸런스 ID가 비어 있음 | 이 리소스 화면에서 리밸런스를 시작해 반환된 ID를 자동 추적하거나 API 호출 시 명시적 ID를 전달 |
| ACL 목록이 사용 불가 | Fluss authorizer 활성화 여부, admin 역할, operations.security.read 권한과 연결 계정 권한을 확인 |
Apache Fluss Enterprise 확장
Apache Fluss Enterprise 확장은 Community Fluss 리소스 플러그인에 다중 신호 이상징후 규칙과 읽기 전용 MCP 설명자를 추가합니다. 연결, 상태 점검, 프로토콜 진단, 메트릭 카탈로그, 매핑 팩, 대시보드와 실제 운영 API는 Community 플러그인이 계속 소유합니다.
카탈로그와 데이터 조회·쓰기, 클러스터 구성, ACL, 서버 태그 및 리밸런스 사용법은 Community 매뉴얼의 Apache Fluss 플러그인 항목을 먼저 참조하십시오. 이 문서는 그 위에 추가되는 Enterprise 분석 및 MCP 표면만 설명합니다.
제공 범위
| 기능 | 소유 에디션 | 설명 |
|---|---|---|
| 연결과 프로토콜 상태 | Community | fluss-go를 통한 CoordinatorServer 협상, 서버 탐색과 상태 점검 |
| 모니터링과 진단 | Community | 대시보드, 논리 메트릭, 현재·이력 진단 및 제한형 read-path 근거 |
| 운영 워크스페이스 | Community | 카탈로그·데이터·구성·ACL·서버 태그·리밸런스 작업과 사전 점검·감사 |
| 이상징후 규칙 | Enterprise | 여러 논리 메트릭을 결합하는 fluss-anomaly-rules-v1 규칙 팩 |
| MCP 카탈로그 | Enterprise | Community 조회 경로와 Enterprise 이상징후 규칙을 노출하는 읽기 전용 descriptor |
Enterprise MCP는 Community 운영 API를 복제하거나 우회하지 않습니다. MCP 읽기 권한이 있어도 데이터 쓰기나 관리 작업 권한은 추가되지 않습니다.
사용 전 확인
- Community 매뉴얼에 따라 bootstrap 서버, TLS 또는 SASL을 구성하고 CoordinatorServer 프로토콜 상태 점검이 성공하는지 확인합니다.
- Fluss 매핑 팩을 통해 Prometheus 호환 메트릭 소스를 Fluss 리소스에 연결합니다. CoordinatorServer와 모든 TabletServer의 메트릭이 같은 리소스 범위에 포함되어야 합니다.
- Enterprise 라이선스에서
mcp.gateway와anomaly.engine기능이 활성화되어 있는지 확인합니다. - 이상징후 규칙 조회 사용자에게
viewer이상의 역할과fluss-plugin.anomaly.read권한을 부여합니다. - MCP 호출자에게 허용된 MCP 읽기 범위와 대상 Fluss 리소스 인스턴스 접근 권한을 함께 부여합니다.
- 현재 기준 조합인 Apache Fluss
0.9.1-incubating과 fluss-gov0.1.0-beta.10을 사용하고 있는지 확인합니다.
Enterprise 분석은 Fluss 프로토콜 연결이나 Prometheus 수집을 대신하지 않습니다. 프로토콜 진단은 실제 Coordinator·TabletServer read path를 확인하고, 이상징후 규칙은 연결된 메트릭 소스의 논리 시계열을 평가합니다. 두 근거가 다르면 한쪽을 정상으로 가정하지 말고 수집 범위와 시각을 먼저 비교합니다.
권한과 안전 경계
| 작업 | 필요한 접근 |
|---|---|
| Enterprise 이상징후 규칙 조회 | 대상 리소스 접근, viewer 이상, fluss-plugin.anomaly.read |
| MCP 리소스·도구 조회 | MCP 읽기 범위와 대상 리소스 인스턴스 접근 |
| 카탈로그·데이터 쓰기 | Community 운영 화면의 해당 editor 권한 |
| 구성·ACL·서버 태그·리밸런스·삭제 | Community 운영 화면의 해당 admin 권한과 확인 절차 |
MCP descriptor는 조회 경로만 제공합니다. 진단 새로 고침과 모든 mutation은 기존 Konduo API의 RBAC, 사전 점검, 확인 문구, 결과 재확인 및 감사 로그 경계를 그대로 따릅니다.
이상징후 평가 방식
fluss-anomaly-rules-v1은 다음 다섯 가지 규칙을 제공합니다. 하나 이상은 나열된 조건 중 하나만 충족해도 일치하고, 모두는 같은 평가 맥락에서 모든 조건이 충족되어야 일치합니다.
| 규칙 키 | 결합 | 심각도·점수 | 논리 메트릭과 조건 | 우선 확인 |
|---|---|---|---|---|
fluss.cluster_availability_risk | 하나 이상 | 심각·0.98 | fluss.cluster.coordinators.active < 1, fluss.cluster.tablet_servers.active < 1, fluss.cluster.buckets.offline > 0 | Coordinator 리더십, TabletServer 등록, 오프라인 버킷과 스토리지 근거 |
fluss.replication_degradation | 하나 이상 | 심각·0.95 | fluss.replication.buckets_under_min_isr > 0, fluss.replication.buckets_under_replicated > 0, fluss.replication.failed_isr_updates_per_second > 0 | 영향 버킷, 복제 배치, TabletServer 상태와 스토리지 지연 |
fluss.request_path_pressure | 모두 | 경고·0.84 | fluss.requests.queue_size >= 100, fluss.requests.errors_per_second > 0 | TabletServer·요청 유형별 대기열과 오류, 네트워크·디스크 압박 |
fluss.write_expiration_cascade | 모두 | 심각·0.91 | fluss.requests.delayed_writes > 0, fluss.requests.expired_writes_per_second > 0 | 영향 테이블, 복제본 응답, 스토리지와 producer 재시도 상태 |
fluss.tabletserver_resource_pressure | 모두 | 경고·0.82 | fluss.tablet_server.jvm.cpu.percent >= 90, fluss.tablet_server.jvm.heap.utilization >= 85 | 서버별 편차, GC, 요청 대기열, 스토리지 지연과 컨테이너 제한 |
규칙은 장애 분류 근거이며 단일 시계열 경보를 대체하지 않습니다. 누락되거나 해석할 수 없는 시계열은 정상 또는 0으로 간주하지 않습니다. 필요한 신호를 모두 수집할 수 없으면 규칙은 판단 근거가 부족한 상태로 남습니다.
가용성 규칙은 Prometheus 시계열을 평가합니다. Community 프로토콜 진단의 Coordinator·TabletServer 결과와 서로 다른 시각 또는 대상 집합을 사용할 수 있으므로, 불일치가 발생하면 메트릭 target, 라벨, 마지막 수집 시각과 Coordinator API 결과를 함께 확인합니다.
MCP 리소스와 도구
MCP 카탈로그는 7개 읽기 전용 리소스와 6개 읽기 전용 도구를 제공합니다.
| 종류 | 이름 | 용도 |
|---|---|---|
| 리소스 | monitoring_overview | 대시보드와 메트릭 연결 상태 읽기 |
| 리소스 | diagnostics_summary, diagnostics_history | 현재 진단과 제한된 이력 위험 근거 읽기 |
| 리소스 | metrics_catalog, mapping_pack_catalog | 논리 메트릭과 Prometheus 매핑 메타데이터 읽기 |
| 리소스 | anomaly_rules | Enterprise 다중 신호 규칙 메타데이터 읽기 |
| 리소스 | software_inventory | 제한된 Fluss 소프트웨어 식별 근거 읽기 |
| 도구 | monitoring_overview, diagnostics_summary | 모니터링 맥락과 현재 진단 조회 |
| 도구 | diagnostics_detail | 지정한 진단 범주의 제한된 상세 근거 조회 |
| 도구 | metrics_query_resolve, mapping_pack_resolve | 논리 키를 메트릭 소스 쿼리와 매핑 팩으로 해석 |
| 도구 | anomaly_rules | Enterprise 규칙 팩 조회 |
입력이 필요한 도구는 다음과 같습니다.
| 도구 | 입력 | 필수 여부 | 허용값 |
|---|---|---|---|
diagnostics_detail | category | 필수 | cluster, replication, requests, storage, runtime |
metrics_query_resolve | logical_metric_key | 필수 | 현재 Community Fluss 메트릭 카탈로그의 논리 키 |
metrics_query_resolve | query_mode | 선택 | instant 또는 range |
diagnostics_history는 연결된 메트릭 소스에 위임된 제한형 이력 근거입니다. 메트릭 연결이 없거나 요청 구간에 표본이 없으면 빈 결과가 정상일 수 있습니다. software_inventory는 버전과 구성 식별을 위한 제한된 정보만 반환하며 자격 증명이나 원시 프로토콜 frame을 노출하지 않습니다.
Community Fluss 플러그인은 관리 경보 규칙 라우트를 제공하지 않으므로 MCP에도 alerts/rules 리소스나 도구가 없습니다. 진단 실행, catalog/data mutation, 구성·ACL·서버 태그·리밸런스 작업도 읽기 전용 MCP 표면에서 제외됩니다.
장애 대응 절차
클러스터 가용성 또는 복제 저하
monitoring_overview에서 메트릭 소스와 마지막 수집 시각을 확인합니다.diagnostics_summary의cluster와replication상태를 비교합니다.diagnostics_detail로 영향 범주를 열고 CoordinatorServer, TabletServer 및 버킷 단위 근거를 확인합니다.- 같은 시간 구간에서 이상징후 규칙의 논리 메트릭을 range 쿼리로 해석합니다.
- 오프라인 버킷과 복제본 상태를 복구한 후 메트릭과 프로토콜 진단이 모두 정상화됐는지 확인합니다.
요청 압박 또는 쓰기 만료
- 요청 대기열, 오류율, 지연 쓰기와 만료 쓰기를 같은 시간 구간에서 비교합니다.
- TabletServer 및 요청 유형별 편차와 복제·스토리지 진단을 확인합니다.
- producer 재시도 전에 accepted 여부가 불명확한 쓰기와 실제 실패를 구분합니다.
- 원인을 확인하기 전에 요청 동시성이나 재시도율을 반복해서 높이지 않습니다.
TabletServer 자원 압박
- CPU와 힙 사용률이 같은 TabletServer에서 동시에 높은지 확인합니다.
- GC, 요청 대기열, 오류율, 스토리지 지연 및 서버별 처리량을 비교합니다.
- hot server 또는 배치 불균형인지 전체 용량 부족인지 구분합니다.
- JVM·컨테이너 제한이나 리밸런스를 변경한 뒤 Community 운영 화면에서 사전 점검과 결과 재확인을 수행합니다.
문제 해결
| 증상 | 확인 순서 |
|---|---|
| EE 이상징후 또는 MCP 항목이 보이지 않음 | Enterprise 라이선스, anomaly.engine, mcp.gateway, 플러그인 버전과 contribution 로딩 상태 확인 |
| 이상징후 규칙 조회가 거부됨 | 대상 리소스 접근, viewer 역할과 fluss-plugin.anomaly.read 권한 확인 |
| 모든 규칙이 평가되지 않음 | Prometheus 리소스 연결, Coordinator·TabletServer target, 논리 메트릭 매핑과 마지막 수집 시각 확인 |
| 일부 규칙만 평가되지 않음 | 해당 규칙에 필요한 논리 키가 메트릭 카탈로그와 실제 원시 시계열에 모두 있는지 확인 |
| 프로토콜 진단과 가용성 규칙이 다름 | 두 근거의 관측 시각, 메트릭 target·라벨 범위와 Coordinator API 서버 목록 비교 |
MCP diagnostics_detail이 거부됨 | category를 허용된 다섯 값 중 하나로 지정하고 리소스 접근 권한 확인 |
| MCP 메트릭 해석이 실패함 | logical_metric_key가 현재 카탈로그에 있는지 확인하고 query_mode를 instant 또는 range로 지정 |
| 이력 진단이 비어 있음 | 연결된 메트릭 소스, 조회 시간 범위와 해당 구간 표본 존재 여부 확인 |
| MCP에서 진단 실행이나 운영 쓰기를 찾을 수 없음 | 의도된 읽기 전용 경계이며 Community 운영 화면의 RBAC 보호 작업 사용 |
데이터 보호와 한계
- EE MCP descriptor는 credential, 인증서 private key, token, row/key payload, 원시 protocol frame 또는 서버 오류 원문을 제공하지 않습니다.
- 이상징후 규칙은 Fluss 클러스터 전체 상태를 추측하지 않고 현재 연결된 논리 메트릭 근거만 평가합니다.
- MCP 조회 결과는 변경 승인이나 복구 실행을 의미하지 않습니다. 실제 mutation은 Community 운영 화면에서 권한, dry-run, 확인 문구, read-back과 감사 결과를 확인해야 합니다.
- 지원 기준 밖 Fluss 또는 fluss-go 조합에서는 먼저 Community 연결·진단 호환성을 검증한 후 Enterprise 분석 결과를 사용합니다.
에디션 경계
이상징후 규칙 팩, MCP 설명자와 Enterprise 현지화는 Enterprise 오버레이에 둡니다. Community 플러그인은 이 상용 contribution 없이도 독립적으로 설치하고 사용할 수 있습니다. EE는 CE의 운영 route를 복제하지 않고 등록된 contribution point를 통해 분석 메타데이터만 추가합니다.