Prometheus 플러그인

TLS 설정 위치

TLS 모드·CA·클라이언트 인증서와 키·서버 이름·인증서 검증 설정은 보안 > TLS에 표시합니다. 주소·포트 등 실제 연결 설정은 기존 구역에 남습니다. 이 분류 변경은 필드 이름, 저장 값, 기본값, 비밀값 처리와 조건부 표시·검증을 바꾸지 않습니다.

기본 접근성 관측

리소스 개요는 메트릭 소스와 별개로 접근 가능·접근 불가·접근 미확인을 표시합니다. 성공한 접속 확인은 전체 멤버, 복제, 파티션이나 작업의 정상 상태를 보장하지 않습니다. 구체적인 도메인 상태는 진단과 도메인 경보에서 확인합니다. 기존 liveness/readiness 정보는 도메인 상세 증거이며 기본 접근성 경보의 조건이 아닙니다. 미확인은 발생 중인 경보를 복구시키지 않습니다.

TLS

연결 설정의 tls_insecure_skip_verify를 켜면 TLS 암호화는 유지하면서 서버 인증서 검증을 생략합니다. 기본값은 꺼짐이며, 검증을 생략할 때 CA 입력은 필요하지 않습니다. 서버가 상호 TLS를 요구하면 클라이언트 인증서와 키는 여전히 필요합니다. 서버 신원을 검증하려면 기존 CA 기반 검증을 사용하세요.

리소스 메트릭 설정에서 매핑 프로파일을 지정할 수 있습니다. 같은 소스와 프로파일의 리소스는 보정을 공유하며, 다른 이름을 사용하면 exporter 매핑을 분리합니다. 비워두면 기존 기본 프로파일을 유지합니다. 진단은 instant/range를 각각 검증하고 데이터 없음, 조회 실패, 매핑 오류를 구분합니다. Counter 이름은 검증·쿼리 점검에서 탐색하고 차트·알림은 캐시된 결과를 사용합니다. 재시작이나 캐시 제거 후에는 재검증하여 자동 이름 선택 결과를 다시 준비할 수 있습니다. 리소스 등록 시 권장 매핑팩은 Prometheus를 조회하지 않고 쿼리 문법을 검증합니다. 실제 데이터 유무 확인과 Counter 이름 탐색은 매핑 진단 또는 수동 미리보기에서 실행하세요.

Counter 메트릭은 _total 유무를 자동 보정합니다. 리소스의 라벨·시간 범위에 원래 이름이 있으면 우선 사용하며, 없을 때 counter 타입과 단위가 일치하는 메타데이터 및 같은 범위의 대체 이름이 확인되어야 보정합니다. 메타데이터가 없거나 타입이 충돌하거나 탐색 결과가 불완전하면 기존 매핑을 유지합니다. Prefix 설정을 먼저 적용하며 선택된 이름은 쿼리 정보에서 확인할 수 있습니다. Histogram 접미사·단위 환산은 명시적 매핑이 필요하며 offset/@ 조회는 보정하지 않습니다.

대상 상태는 관측된 정상 비율과 실패 대상 수를 작은 카드로 표시합니다. 상태 분포 원형 차트는 기본 배치에서 제외하지만 개인화에서 선택할 수 있습니다. Job별 비교는 전체 폭, 수집·규칙/알림 추세는 3열, 조회/스토리지 추세는 4열을 사용합니다.

관측 부재와 조회 실패는 정상 0건과 구분합니다. 저장한 배치와 조회 범위·예산은 유지합니다.

개수와 알림 수는 정수로 표시하고 단위 변환된 스토리지 바이트, 백분율, 속도, 지속 시간은 필요한 소수 자릿수를 유지합니다. Job 및 대상 상태 분포는 구성 시리즈를 합산하며 이미 집계된 조회는 단일 최신값으로 요약합니다. 데이터 없음은 관측된 0과 계속 구분합니다.

Prometheus 플러그인은 Konduo가 Prometheus 호환 HTTP API에서 시계열 데이터를 조회하고, 다른 리소스 플러그인의 논리 메트릭을 PromQL 쿼리로 실행할 수 있게 하는 메트릭 소스 플러그인입니다.

특징

• 리소스 대시보드와 알림 평가에 필요한 범위/즉시 쿼리를 실행합니다.
• 라벨 탐색, 쿼리 점검, 매핑팩 적용 상태 확인을 지원합니다.
• Prometheus 서버 자체를 리소스로 등록해 수집 대상 상태, TSDB, 규칙/평가, 런타임 신호를 볼 수 있습니다.
• 재적재, 스냅샷 같은 Prometheus 관리 작업은 설정과 확인 문구, 대기 시간으로 보호됩니다.

등록 전 확인

• Konduo 백엔드에서 Prometheus HTTP API에 접근할 수 있어야 합니다.
• URL, 인증 방식, 제한 시간, 쿼리 제한 정책을 준비합니다.
• 이 Prometheus 인스턴스를 관리형 메트릭 수집의 쓰기 대상으로 사용할 경우 --web.enable-remote-write-receiver 옵션으로 실행해야 합니다.
• 리소스 플러그인의 매핑팩을 적용해야 대시보드와 알림 규칙이 기대한 논리 메트릭을 찾을 수 있습니다.

운영 팁

리소스 메트릭 설정에서 기존 메트릭 이름 접두사와 새 메트릭 이름 접두사를 지정합니다. 기존 접두사를 비우고 새 접두사에 prefix_를 입력하면 모든 이름 앞에 추가합니다. 기존 pg_, 새 prefix_이면 pg_up을 prefix_up으로 조회하고, 일치하지 않는 이름은 유지합니다. 새 접두사를 비우면 기존 접두사를 제거하며, 둘 다 비우면 원래 이름을 사용합니다. 대시보드·알림·쿼리 검사·진단에 동일하게 적용됩니다. 제거 후 이름이 비거나 유효하지 않으면 오류를 반환합니다. 리소스 라벨 필터는 계속 필요하며, 접두사 외 이름이나 단위 차이는 매핑 보정이 필요합니다.

• 대시보드가 비어 있으면 수집 상태, 라벨 필터, 매핑팩 적용 여부를 같이 확인합니다.
• 쿼리 범위와 간격은 과도한 샘플을 만들지 않도록 제한합니다.
• 알림 쿼리 배치는 기본적으로 Prometheus 요청 4개를 동시에 실행합니다. 소스에서 429 응답이나 쿼리 부하가 발생하면 metric_query_batch_concurrency를 1로 설정해 순차 실행으로 되돌립니다. 16보다 큰 값은 제한되며 동시성은 대기 시간을 줄일 뿐 요청 수를 줄이지 않습니다.
• 단순 시리즈 selector의 구간별 최솟값/최댓값은 저장된 모든 샘플을 평가합니다. 파생 표현식은 요청한 샘플 간격으로 평가하므로 간격보다 짧은 spike나 dip을 놓칠 수 있으며, sampled 결과를 전체 구간의 완전한 부재로 해석하지 않습니다.
• Prometheus 수집 대상 상태는 대상 리소스의 직접 가용성을 대체하지 않고 메트릭 근거로 사용합니다.
• 지원되는 쿼리가 성공했지만 요청한 조회 범위에 ALERTS{alertstate="firing"} 이벤트 시계열이 없으면 수치·게이지·분포 패널은 체크와 활성 알림 없음 문구를 표시합니다.
• 시계열은 확대 화면에서도 선택한 시간 축과 옅은 점선 안내선, 작은 발생 이력 없음 문구를 표시합니다. 빈 시계열도 확대할 수 있으며 안내선은 측정값 0이 아닙니다. 실제 0 샘플은 차트로 유지합니다.
• 쿼리 정보에서 조회 모드와 범위를 확인하세요. 순간값 조회는 선택 기간 전체의 부재나 수집/리소스 정상을 확정하지 않습니다. 일반 데이터 누락과 쿼리 오류 표시는 그대로 유지하며 실패하거나 사용할 수 없는 쿼리는 unknown으로 남습니다.

운영 화면

• 메트릭 소스 화면은 Prometheus HTTP API 연결, 라벨 탐색, 쿼리 점검, 매핑팩 상태를 확인하는 진입점입니다.
• Prometheus 리소스 화면은 Prometheus 자체의 수집 대상, 규칙 그룹, 알림 상태, TSDB, 런타임 상태를 보여줍니다.
• 대상 상태 영역은 간결한 정상 비율 값, 정상/비정상 수 분포, Job별 분포를 나눠 각 패널이 서로 다른 점검 질문에 답하도록 구성합니다.
• 기본 대시보드는 대상 정상 비율과 처리량 외에도 스크레이프당 수락 샘플, 쿼리 평가 시간, TSDB 블록/WAL 저장공간, 규칙 평가 시간을 시계열로 보여줍니다.
• 쿼리/규칙 평가 시간은 최근 5분 평균입니다. 쿼리 속도 및 규칙 실행 간격과 함께 비교하고, TSDB 저장공간은 보존 기간과 compaction 상태를 함께 확인합니다.
• Prometheus 호환 백엔드가 Prometheus 자체 메트릭 이름을 제공하지 않으면 새 선택 메트릭 패널은 데이터 없음으로 표시될 수 있지만 매핑팩 검증은 실패하지 않습니다.
• 매핑팩 화면은 리소스 플러그인의 논리 메트릭 키가 어떤 PromQL로 해석되는지 확인하는 데 사용합니다.
• 쿼리 점검은 대시보드가 비었거나 알림 평가가 부분 상태일 때 실제 쿼리와 라벨 조건을 점검하는 도구입니다.

진단과 알림 관점

• Prometheus 플러그인은 다른 리소스의 메트릭 근거를 제공하는 기반이므로 수집 대상 상태, 수집 지연, 규칙 평가 상태가 중요합니다.
• 진단은 HTTP API 연결, 수집 대상 상태, 규칙 평가, 활성 알림, TSDB/런타임 압박, 매핑 범위를 분리해서 보여줍니다.
• Prometheus 자체 알림은 메트릭 플랫폼 위험을 다루고, Redis/Kafka/PostgreSQL 같은 대상 리소스의 장애 판정은 해당 플러그인과 Core 가용성이 담당합니다.
• 샘플 수가 과도하거나 쿼리가 느린 경우에는 범위, 간격, 라벨 필터, 대시보드 패널 수를 함께 조정해야 합니다.

관리 경계

• reload와 snapshot은 운영 영향이 있는 관리 작업이므로 확인 문구와 대기 시간을 유지합니다.
• 임의 PromQL 쿼리 기능은 운영 점검용이며, 장시간/고비용 쿼리를 실행하는 일반 분석 도구로 확장하지 않습니다.
• 관리형 수집의 쓰기 대상으로 사용할 때도 Prometheus는 샘플 저장소이며, 수집 주기와 대상 시스템 접근은 각 리소스 플러그인과 Core가 담당합니다.
• 매핑팩 오버라이드는 메트릭 키 차이를 흡수하는 수단이며, 리소스 상태를 임의로 정상화하는 우회 수단이 아닙니다.

대표 시나리오

• 리소스 대시보드가 비어 있으면 Prometheus 수집 대상 상태, 라벨 필터, 매핑팩 적용 여부, 쿼리 점검 결과를 순서대로 확인합니다.
• 알림 평가가 부분 상태이면 해당 논리 메트릭의 PromQL과 실제 시계열 라벨을 비교합니다.
• Prometheus 부하가 높으면 규칙 평가 지연, 쿼리 동시성, TSDB head block, 수집 간격을 함께 봅니다.
• 관리형 수집 샘플이 보이지 않으면 원격 쓰기 수신 옵션, Core 쓰기 상태, 리소스 식별 라벨을 확인합니다.

---

Prometheus Enterprise 확장

TLS 설정 위치

TLS 모드·CA·클라이언트 인증서와 키·서버 이름·인증서 검증 설정은 보안 > TLS에 표시합니다. 주소·포트 등 실제 연결 설정은 기존 구역에 남습니다. 이 분류 변경은 필드 이름, 저장 값, 기본값, 비밀값 처리와 조건부 표시·검증을 바꾸지 않습니다.

기본 접근성 관측

리소스 개요는 메트릭 소스와 별개로 접근 가능·접근 불가·접근 미확인을 표시합니다. 성공한 접속 확인은 전체 멤버, 복제, 파티션이나 작업의 정상 상태를 보장하지 않습니다. 구체적인 도메인 상태는 진단과 도메인 경보에서 확인합니다. 기존 liveness/readiness 정보는 도메인 상세 증거이며 기본 접근성 경보의 조건이 아닙니다. 미확인은 발생 중인 경보를 복구시키지 않습니다.

TLS

연결 설정의 tls_insecure_skip_verify를 켜면 TLS 암호화는 유지하면서 서버 인증서 검증을 생략합니다. 기본값은 꺼짐이며, 검증을 생략할 때 CA 입력은 필요하지 않습니다. 서버가 상호 TLS를 요구하면 클라이언트 인증서와 키는 여전히 필요합니다. 서버 신원을 검증하려면 기존 CA 기반 검증을 사용하세요.

리소스 메트릭 설정에서 매핑 프로파일을 지정할 수 있습니다. 같은 소스와 프로파일의 리소스는 보정을 공유하며, 다른 이름을 사용하면 exporter 매핑을 분리합니다. 비워두면 기존 기본 프로파일을 유지합니다. 진단은 instant/range를 각각 검증하고 데이터 없음, 조회 실패, 매핑 오류를 구분합니다. Counter 이름은 검증·쿼리 점검에서 탐색하고 차트·알림은 캐시된 결과를 사용합니다. 재시작이나 캐시 제거 후에는 재검증하여 자동 이름 선택 결과를 다시 준비할 수 있습니다. 리소스 등록 시 권장 매핑팩은 Prometheus를 조회하지 않고 쿼리 문법을 검증합니다. 실제 데이터 유무 확인과 Counter 이름 탐색은 매핑 진단 또는 수동 미리보기에서 실행하세요.

Counter 메트릭은 _total 유무를 자동 보정합니다. 리소스의 라벨·시간 범위에 원래 이름이 있으면 우선 사용하며, 없을 때 counter 타입과 단위가 일치하는 메타데이터 및 같은 범위의 대체 이름이 확인되어야 보정합니다. 메타데이터가 없거나 타입이 충돌하거나 탐색 결과가 불완전하면 기존 매핑을 유지합니다. Prefix 설정을 먼저 적용하며 선택된 이름은 쿼리 정보에서 확인할 수 있습니다. Histogram 접미사·단위 환산은 명시적 매핑이 필요하며 offset/@ 조회는 보정하지 않습니다.

대상 상태는 관측된 정상 비율과 실패 대상 수를 작은 카드로 표시합니다. 상태 분포 원형 차트는 기본 배치에서 제외하지만 개인화에서 선택할 수 있습니다. Job별 비교는 전체 폭, 수집·규칙/알림 추세는 3열, 조회/스토리지 추세는 4열을 사용합니다.

관측 부재와 조회 실패는 정상 0건과 구분합니다. 저장한 배치와 조회 범위·예산은 유지합니다.

개수와 알림 수는 정수로 표시하고 단위 변환된 스토리지 바이트, 백분율, 속도, 지속 시간은 필요한 소수 자릿수를 유지합니다. Job 및 대상 상태 분포는 구성 시리즈를 합산하며 이미 집계된 조회는 단일 최신값으로 요약합니다. 데이터 없음은 관측된 0과 계속 구분합니다.

Prometheus Enterprise 확장은 메트릭 소스 리소스에 MCP 설명자와 Prometheus 자체 원격 측정 이상 징후 규칙을 추가합니다. 수집, 적재, 카디널리티, 쿼리 압박을 분석해 메트릭 플랫폼 자체의 위험을 감지합니다.

메트릭 이름 접두사

리소스 메트릭 설정에서 기존 메트릭 이름 접두사와 새 메트릭 이름 접두사를 지정합니다. 기존 접두사를 비우고 새 접두사에 prefix_를 입력하면 모든 이름 앞에 추가합니다. 기존 pg_, 새 prefix_이면 pg_up을 prefix_up으로 조회하고, 일치하지 않는 이름은 유지합니다. 새 접두사를 비우면 기존 접두사를 제거하며, 둘 다 비우면 원래 이름을 사용합니다. 대시보드·알림·쿼리 검사·진단에 동일하게 적용됩니다. 제거 후 이름이 비거나 유효하지 않으면 오류를 반환합니다. 리소스 라벨 필터는 계속 필요하며, 접두사 외 이름이나 단위 차이는 매핑 보정이 필요합니다.

메트릭 해석

• 대상 상태 영역은 간결한 정상 비율 값, 정상/비정상 수 분포, Job별 분포를 나눠 각 패널이 서로 다른 점검 질문에 답하도록 구성합니다.

특징

• MCP에서 Prometheus 리소스 메타데이터, 진단, 메트릭 카탈로그, 이상 징후 규칙을 조회합니다.
• 선언형 메트릭 규칙은 수집 시간, 적재율, TSDB head series, 쿼리 비율 같은 논리 메트릭을 사용합니다.
• 시뮬레이터 시계열로 카디널리티와 적재 압박 시나리오를 검증합니다.
• Prometheus는 메트릭 제공자 역할을 유지하며 플러그인 모드 탐지기를 실행하지 않습니다.

등록 전 확인

• Prometheus API 엔드포인트와 쿼리 권한이 정상이어야 합니다.
• Prometheus 자체 메트릭을 수집하는 매핑팩을 연결합니다.
• MCP 사용자는 메트릭 소스 읽기 권한과 필요한 범위를 가져야 합니다.

운영 팁

• 카디널리티 증가는 익스포터, 라벨, 계측 변경과 함께 추적합니다.
• 수집 지연과 적재 압박이 같이 올라가면 대상 증가와 원격 쓰기 상태를 함께 확인합니다.
• 알림 쿼리 배치는 기본적으로 Prometheus 요청 4개를 동시에 실행합니다. 소스에서 429 응답이나 쿼리 부하가 발생하면 metric_query_batch_concurrency를 1로 설정해 순차 실행으로 되돌립니다. 16보다 큰 값은 제한되며 동시성은 대기 시간을 줄일 뿐 요청 수를 줄이지 않습니다.
• 단순 시리즈 selector의 구간별 최솟값/최댓값은 저장된 모든 샘플을 평가합니다. 파생 표현식은 요청한 샘플 간격으로 평가하므로 간격보다 짧은 spike나 dip을 놓칠 수 있으며, sampled 결과를 전체 구간의 완전한 부재로 해석하지 않습니다.
• 지원되는 쿼리가 성공했지만 요청한 조회 범위에 ALERTS{alertstate="firing"} 이벤트 시계열이 없으면 수치·게이지·분포 패널은 체크와 활성 알림 없음 문구를 표시합니다.
• 시계열은 확대 화면에서도 선택한 시간 축과 옅은 점선 안내선, 작은 발생 이력 없음 문구를 표시합니다. 빈 시계열도 확대할 수 있으며 안내선은 측정값 0이 아닙니다. 실제 0 샘플은 차트로 유지합니다.
• 쿼리 정보에서 조회 모드와 범위를 확인하세요. 순간값 조회는 선택 기간 전체의 부재나 수집/리소스 정상을 확정하지 않습니다. 일반 데이터 누락과 쿼리 오류 표시는 그대로 유지하며 실패하거나 사용할 수 없는 쿼리는 unknown으로 남습니다.
• 기본 대시보드는 대상 정상 비율과 처리량 외에도 스크레이프당 수락 샘플, 쿼리 평가 시간, TSDB 블록/WAL 저장공간, 규칙 평가 시간을 시계열로 보여줍니다.
• 쿼리/규칙 평가 시간은 최근 5분 평균입니다. 쿼리 속도 및 규칙 실행 간격과 함께 비교하고, TSDB 저장공간은 보존 기간과 compaction 상태를 함께 확인합니다.
• Prometheus 호환 백엔드가 Prometheus 자체 메트릭 이름을 제공하지 않으면 새 선택 메트릭 패널은 데이터 없음으로 표시될 수 있지만 매핑팩 검증은 실패하지 않습니다.

운영 시나리오

• Prometheus가 여러 리소스의 메트릭 소스일 때 수집 상태, 대상 변동, TSDB 카디널리티, 쿼리 압박을 먼저 확인해 관측 체계 자체의 신뢰도를 판단합니다.
• 특정 플러그인의 이상 징후가 갑자기 사라지거나 많아지면 Prometheus 매핑팩과 소스 원격 측정 상태를 함께 점검합니다.
• MCP 설명자는 메트릭 플랫폼 상태를 에이전트가 빠르게 확인하는 읽기 전용 카탈로그로 사용합니다.

경계

• Prometheus 플러그인은 메트릭 제공자이자 관측 대상이며, 플러그인 모드 이상 징후 탐지기를 실행하지 않습니다.
• 기록 규칙, 수집 설정, 원격 쓰기 설정 변경은 Prometheus 운영 경계에 속하며 이 확장 계층이 직접 변경하지 않습니다.

MCP diagnostic execution effects

The run_diagnostics tool changes diagnostic execution and cooldown state. Its descriptor declares operation_class: diagnostic_lifecycle; MCP advertises readOnlyHint=false, destructiveHint=false and idempotentHint=false. Diagnostic queries retain read-only hints. Both queries and actions continue to require mcp:invoke and the existing resource permissions/audit checks. Safety hints do not change authorization or guarantee safe retries.

MCP tool input contracts

Target, rule, and alert tools declare bounded limit/offset, substring search, and the applicable state/health/type filters. Raw PromQL tools consume end_time (and instant-query time/ts); range queries also consume start_time and step. Result limits are max_series (1–2000), max_samples (100–200000), and range-only max_data_points (200–10000). History and summary diagnostics declare lookback; static catalogs accept {}.

The advertised JSON Schema is checked before plugin dispatch. Omitted optional values retain plugin defaults. Arguments do not replace resource-instance authorization; stored connection credentials are supplied by Konduo. Open schemas are retained only for existing dynamic filters or aliases, and each advertised property describes its caller-facing meaning. Plugin result shapes can vary with product/version, available evidence, and partial failures; no stable outputSchema is promised for these dynamic responses. 클라이언트와 리소스 지원 범위는 Enterprise 소스 저장소의 enterprise/backend/docs/plugin-contract.md에 정의되어 있습니다.