테이블 소개, 그리고 각 테이블이 설명하는 머신

sigiro_* 테이블은 OTLP를 전송한 대상의 텔레메트리를 보관합니다. sys_* 함수는 sigiro가 실행 중인 머신을 읽습니다. 이 둘을 혼동하면 엉뚱한 머신의 정보를 얻게 됩니다.

sigiro는 두 종류의 테이블을 제공하며, 쿼리에서는 서로 비슷해 보입니다. 한 종류는 여러분의 서비스가 전송한 텔레메트리를 보관합니다. 다른 종류는 sigiro 자신이 실행 중인 머신을 읽습니다. 둘 다 CPU, 메모리 또는 디스크에 관한 질문에 답하지만, 어느 쪽도 그것이 어느 머신을 의미하는지 알려주지 않습니다.

이 페이지는 그 경계선을 긋습니다. 이는 이 섹션에서 가장 가치 있는 내용인데, 실패 양상이 오류 메시지가 아니기 때문입니다. 실패 양상은 올바르게 보이지만 여러분이 묻지 않은 머신을 설명하는 숫자입니다.

두 계열, 두 대상

sigiro_* 이름은 테이블입니다. sys_* 이름은 함수이며, 빈 괄호를 붙여 호출합니다. 이것이 눈에 보이는 유일한 차이이며, 차이로서는 충분하지 않습니다.

함정, 예제 하나로

어떤 에이전트가 이렇게 묻는다고 가정해 봅시다. checkout 서비스의 디스크가 가득 찼는가?

-- WRONG for that question
SELECT * FROM sys_disk_info();

이 쿼리는 성공합니다. 실제 마운트 지점과 실제 여유 바이트 수를 반환합니다. 그 안의 모든 숫자는 sigiro가 실행 중인 머신을 설명합니다. checkout이 다른 컨테이너, 다른 호스트, 또는 다른 리전에서 실행된다면 그 답은 checkout과 아무 관련이 없습니다. 호스팅 서비스에서는 그 답이 저희가 운영하는 머신을 설명하며, 여러분은 그 위에서 아무것도 실행하지 않습니다.

에이전트는 이를 알아챌 방법이 없습니다. 오류도, null 컬럼도, 응답 내 메시지도 없습니다. 그래서 에이전트는 확신에 차서 디스크 수치를 보고하고, 그 수치는 엉뚱한 머신에 관한 것입니다.

checkout에 관한 질문은 여러분의 서비스가 전송한 메트릭으로 답합니다.

-- RIGHT for that question
SELECT service_name, metric_name, value, timestamp
FROM sigiro_metrics_gauge
WHERE service_name = 'checkout'
  AND metric_name LIKE 'system.filesystem%'
  AND timestamp > now() - INTERVAL '1 hour'
ORDER BY timestamp DESC;

이것은 checkout 자신의 OpenTelemetry 호스트 메트릭이 checkout 자신의 머신에서 보고한 내용을, 여러분이 선택한 구간에 대해 읽습니다. 과거 이력이므로 한 시점이 아니라 추세를 볼 수 있습니다. 결과 행 집합이 비어 있다면, 그 또한 실질적이고 유용한 답입니다. 해당 서비스에 대해 호스트 메트릭을 전송하는 것이 없다는 뜻이며, 해결책은 다른 쿼리가 아니라 계측입니다.

sys_*가 존재하는 이유

sys_* 함수는 실수가 아닙니다. 이 함수들은 한 가지 질문에 잘 답합니다. 이 노드는 지금 어떤 상태인가? 자체 호스팅 플릿을 운영하는 운영자는 각 노드에 대해 이를 묻고, 그 답에는 텔레메트리 파이프라인이 필요하지 않습니다. 노드가 자신의 커널을 직접 읽기 때문입니다.

또한 이 함수들은 sigiro의 SQL 규칙에 대한 의도적인 예외입니다. 데이터베이스 외부를 읽는 다른 모든 함수는 차단되는데, 호출자가 경로를 지정할 수 있기 때문입니다. read_csv('/etc/passwd')가 바로 차단 목록이 막는 구멍입니다. sys_* 함수는 인자를 받지 않으므로 호출자가 선택할 경로가 없으며, 바로 그 속성 덕분에 통과할 수 있었습니다. sigiro는 인자를 동반한 모든 sys_* 호출을 거부합니다.

그 결과를 분명히 말해 둡니다. 자체 호스팅 노드에서 경계는 네트워크이므로, 쿼리 표면에 도달할 수 있는 누구나 sys_*를 읽을 수 있습니다. 호스팅 서비스에서 sys_*는 저희 머신을 설명하며 결코 여러분의 머신을 설명하지 않습니다. 두 경우 모두 규칙은 동일합니다. sys_*는 여러분에게 응답하는 프로세스에 관한 것입니다.

메트릭 테이블이 넷인 이유는 쓰기 경로에 있습니다

메트릭은 하나가 아닌 네 개의 테이블로 도착합니다.

• sigiro_metrics_gauge — 특정 시점의 값
• sigiro_metrics_sum — 카운터, 단조 증가일 수도 아닐 수도 있음
• sigiro_metrics_histogram — 명시적 버킷 경계
• sigiro_metrics_exp_histogram — 지수 버킷

단일 sigiro_metrics 테이블이 제안되었으나 기각되었습니다. OTLP는 이미 이 네 가지 형태를 서로 다른 필드로 전달하므로, 하나의 테이블은 삽입할 때마다 스키마 투영을 의미하게 됩니다. 해당되지 않는 형태에 대한 null 컬럼과, 어느 것인지 결정하는 매퍼가 필요해집니다. 네 개의 테이블은 각 OTLP 형태를 복사 없이, 투영 없이 삽입할 수 있게 합니다. 그 대가로 모든 메트릭을 한 번에 조회하려면 UNION ALL을 지불해야 하며, /v1/diagnose가 내부적으로 하는 일이 바로 그것입니다.

sigiro_anomalies는 이 계열에서 이질적인 존재입니다. 이 테이블은 텔레메트리를 보관하지 않습니다. 예약된 처리 과정이 이미 감지한 체제 변화(regime shift)를 보관하며, GET /v1/anomalies는 동일한 행을 타입이 지정된 JSON으로 제공합니다. 대시보드 대신 증거에 관하여에서 그 행들이 어떻게 생성되는지 설명합니다.

아직 스키마 엔드포인트가 없으며, 그것이 공백입니다

위의 모든 내용은 이제 여러분이 보유하고 있지만 에이전트는 갖지 못한 지식입니다.

sigiro는 스키마 설명을 공개하지 않습니다. /v1/schema는 없고, 테이블에 컬럼 주석도 없습니다. 그래서 POST /v1/query에 도달한 에이전트는 추측을 하거나, 이 사이트의 llms-full.txt를 읽습니다. 둘 다 위험할 만큼 자주 작동합니다. 디스크에 관한 질문에 sys_disk_info()를 추측하는 것은 훌륭한 추측이며, 그것이 잘못된 답을 만들어냅니다.

바로 그 이유로 저희는 이를 편의성 공백이 아니라 API에서 가장 가치 있는 공백으로 취급합니다. 기계가 읽을 수 있게 되어야 할 구분은 “로컬이냐 원격이냐”가 아닙니다. 그것은 이것입니다. sys_*는 sigiro가 실행 중인 머신에 대한 실시간 측정값이고, sigiro_metrics_*는 OTLP를 전송한 대상의 과거 텔레메트리입니다.

그 엔드포인트가 존재하기 전까지는 이 페이지가 기계가 읽을 수 있는 버전입니다. 이 페이지는 /docs/explanation/tables.md에서 Markdown으로 제공되며, llms.txt에 포함되어 있습니다.

매번 적용할 수 있는 규칙

질문이 어느 머신에 관한 것인지 물으십시오.

• 여러분이 계측한 서비스에 관한 것이라면 — sigiro_*를 사용하고, timestamp를 한정하십시오.
• sigiro 프로세스 자체에 관한 것이라면 — sys_*를 사용하고, 한 시점의 값을 예상하십시오.
• 확실하지 않다면 — sigiro_*를 사용하십시오. 빈 결과는 정직합니다. sys_* 결과는 확신에 차 있으면서도 무관할 수 있습니다.

다음 읽을거리

• 대시보드 대신 증거에 관하여
• 호스팅 sigiro로 텔레메트리 전송하기 — 적용되는 SQL 규칙과 함께 전체 테이블 목록