---
title: 테이블 소개, 그리고 각 테이블이 설명하는 머신
description: >-
  sigiro_* 테이블은 OTLP를 전송한 대상의 텔레메트리를 보관합니다. sys_* 함수는 sigiro가 실행 중인 머신을 읽습니다. 이
  둘을 혼동하면 엉뚱한 머신의 정보를 얻게 됩니다.
sidebar:
  order: 2
---
sigiro는 두 종류의 테이블을 제공하며, 쿼리에서는 서로 비슷해 보입니다. 한 종류는
여러분의 서비스가 전송한 텔레메트리를 보관합니다. 다른 종류는 sigiro 자신이 실행
중인 머신을 읽습니다. 둘 다 CPU, 메모리 또는 디스크에 관한 질문에 답하지만, 어느
쪽도 그것이 어느 머신을 의미하는지 알려주지 않습니다.

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

## 두 계열, 두 대상

| 계열 | 무엇인가 | 누구의 머신인가 | 시간 |
| --- | --- | --- | --- |
| `sigiro_spans`, `sigiro_logs`, `sigiro_log_templates`, `sigiro_metrics_gauge`, `sigiro_metrics_sum`, `sigiro_metrics_histogram`, `sigiro_metrics_exp_histogram`, `sigiro_profiles`, `sigiro_anomalies` | 저장된 텔레메트리 | OTLP를 전송한 대상 — 여러분의 호스트에서, 어디에서 실행되든 여러분의 서비스 | 과거 이력, `timestamp` 컬럼 보유 |
| `sys_cpu_info()`, `sys_memory_info()`, `sys_disk_info()`, `sys_network_info()`, `sys_os_info()` | 실시간 테이블 함수 | 이 sigiro 프로세스가 실행 중인 단 하나의 머신 | 현재 시점의 측정값 하나, 이력 없음, 시간 컬럼 없음 |

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

## 함정, 예제 하나로

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

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

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

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

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

```sql
-- 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으로 제공합니다.
[대시보드 대신 증거에 관하여](/docs/explanation/evidence)에서 그 행들이 어떻게
생성되는지 설명합니다.

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

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

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_*` 결과는
  확신에 차 있으면서도 무관할 수 있습니다.

## 다음 읽을거리

- [대시보드 대신 증거에 관하여](/docs/explanation/evidence)
- [호스팅 sigiro로 텔레메트리 전송하기](/docs/how-to/hosted-onboarding#4-query-your-data-sql-api)
  — 적용되는 SQL 규칙과 함께 전체 테이블 목록