빠른 시작

하나의 docker 명령으로 sigiro를 실행하십시오. OpenTelemetry가 이를 가리키도록 설정하십시오. 그런 다음 무엇이 변했고 그 이유가 무엇인지 물어보십시오. 5분이 걸립니다. 컬렉터도 설정 파일도 필요하지 않습니다.

이 튜토리얼에서는 sigiro 서버를 시작하고, 사용자 서비스의 텔레메트리를 전송하며, 두 가지 질문을 던집니다. 마지막에는 진단 결과를 읽고 그 근거가 되는 SQL을 실행합니다. 5분이 걸립니다.

sigiro는 하나의 프로세스입니다. 컬렉터를 배포하지 않으며 설정 파일도 작성하지 않습니다.

1. 실행하기

curl -fsSL https://sigiro.com/install | sh
sigiro serve

이 스크립트는 사용자의 운영체제와 프로세서를 읽습니다. 그런 다음 다운로드한 파일의 SHA-256을 게시된 체크섬과 비교하여 확인합니다. 바이너리는 ~/.local/bin에 기록됩니다. 다른 디렉터리를 사용하려면 SIGIRO_INSTALL_DIR을 설정하십시오.

빌드는 arm64용 Linux와 macOS, 그리고 x86-64용 Linux에 대해 제공됩니다. 다른 플랫폼에서는 컨테이너를 사용하십시오.

docker run -p 4317:4317 -p 4318:4318 -p 9999:9999 ghcr.io/sigiroai/sigiro

컨테이너를 재시작해도 데이터를 유지하려면 -v sigiro-data:/var/lib/sigiro를 추가하십시오.

세 개의 포트는 각각 하나의 기능을 담당합니다:

포트	프로토콜
`4317`	gRPC를 통한 OTLP
`4318`	HTTP를 통한 OTLP
`9999`	쿼리 및 진단 API

최초 시작 시 sigiro는 쿼리 확장 기능을 다운로드합니다. 여기에는 30~90초가 걸릴 수 있으므로, 서버가 요청을 받아들이기 전에 잠시 대기 시간이 발생합니다. 이후의 시작은 즉시 이루어집니다. sigiro는 데이터를 SIGIRO_DATA_DIR에 기록합니다. 이 디렉터리는 바이너리의 경우 ~/.local/share/sigiro이며, 이미지의 경우 /var/lib/sigiro입니다.

서버가 키를 요구하지 않는다는 점에 유의하십시오. 자체 호스팅 서버는 어떤 요청도 인증하지 않으므로, 사설 네트워크 내에 두십시오. 네트워크가 보안 경계입니다.

2. 텔레메트리 전송하기

스택에 있는 모든 OpenTelemetry SDK 또는 컬렉터는 변경 없이 동작합니다. 표준 환경 변수가 sigiro를 가리키도록 설정하십시오:

OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 \
OTEL_SERVICE_NAME=checkout \
  <your-app-start-command>

코드에 아직 계측이 적용되지 않았다면, 직접 손으로 추가하지 마십시오. 먼저 에이전트로 코드 계측하기를 따른 후 이곳으로 돌아오십시오.

이제 서비스로 실제 트래픽을 일부 전송하고, 텔레메트리가 도착했는지 확인하십시오:

curl http://localhost:9999/v1/services

응답은 services 배열을 포함한 JSON 객체입니다. 첫 요청 이후 몇 초 내에 해당 배열에 사용자 서비스가 나타납니다. 배열이 비어 있다면, HTTP를 통한 OTLP의 경우 포트가 4318인지, gRPC를 통한 OTLP의 경우 4317인지 확인하십시오.

3. 무엇이 변했는지 묻기

anomalies는 이 루프의 진입점입니다. 각 서비스의 최근 기준선에서 벗어난 변화를 가장 큰 변화 순으로 반환합니다.

sigiro anomalies
sigiro anomalies --service checkout

여기서는 아무것도 설정하지 않습니다. 선택해야 할 임계값이 없으며, 항상 느리지만 안정적인 서비스는 이상 징후가 아닙니다. sigiro가 이를 어떻게 판단하는지 읽으려면 대시보드 대신 증거에 대하여를 참조하십시오.

시작한 지 얼마 되지 않은 서버에서는 목록이 비어 있을 수 있다는 점에 유의하십시오. sigiro는 무엇이든 비교하기 전에 5분 단위 버킷의 이력이 어느 정도 필요하므로, 서비스를 잠시 실행한 후 다시 질의하십시오.

4. 이유를 묻기

diagnose는 하나의 서비스와 시간 범위에 대해 구조화된 증거 블록 하나를 반환합니다. 이 블록은 주의를 기울일 만한 항목의 순위 목록으로 시작합니다. 그 아래에는 오류 수, 각 작업별 오류 분류, 각 모델별 LLM 통계, 샘플링된 스팬, 그리고 중복이 제거된 로그 패턴이 담겨 있습니다. 모든 행에는 바로 실행할 수 있는 SQL 쿼리도 함께 포함됩니다.

sigiro diagnose checkout
sigiro diagnose checkout --from $(date -v-1H +%s)

이 명령은 들여쓰기된 JSON을 출력합니다. 먼저 findings 배열을 읽으십시오. 이 배열은 심각한 항목이 먼저 오도록 정렬되어 있으며, 각 항목에는 읽을 수 있는 summary와 실행할 수 있는 drill_down_sql이 담겨 있습니다.

에이전트는 HTTP를 통해 동일한 질문을 던집니다. HTTP 요청에는 명시적인 시간 범위가 필요하며, 두 타임스탬프 모두 Unix 에포크 이후의 마이크로초입니다:

curl -X POST http://localhost:9999/v1/diagnose \
  -H 'content-type: application/json' \
  -d "{\"service\":\"checkout\",
       \"from_ts\":$(( $(date +%s) - 900 ))000000,
       \"to_ts\":$(date +%s)000000}"

CLI의 --from/--to 플래그는 에포크 초를 받으며, CLI는 시간 범위를 기본적으로 최근 15분으로 설정합니다. HTTP 본문은 마이크로초를 받으며 어떤 기본값도 적용하지 않습니다. sigiro는 HTTP 경로에서 초 단위 값이 전달되면 단위를 명시한 메시지와 함께 이를 거부하므로, 잘못된 단위는 빈 범위를 반환하는 대신 명확하게 실패합니다.

5. 행의 근거가 되는 쿼리 실행하기

증거 블록이 질문에 답하지 못한다면, 해당 행이 제공한 SQL을 실행하십시오. 텔레메트리는 여러 테이블의 집합이며, 쿼리 요청의 본문은 JSON이 아니라 원시 SQL입니다:

curl -X POST http://localhost:9999/v1/query \
  --data "SELECT service_name, count(*) AS errors
          FROM sigiro_spans
          WHERE status_code = 2 AND timestamp > now() - INTERVAL '1 hour'
          GROUP BY 1 ORDER BY errors DESC"

응답은 행 객체의 JSON 배열입니다. status_code는 OTLP 열거형이므로 2는 오류를 의미합니다.

이 쿼리가 timestamp의 범위를 한정한다는 점에 유의하십시오. 모든 쿼리에서 timestamp의 범위를 한정하십시오. sigiro는 보조 인덱스를 유지하지 않으므로, 범위가 한정된 쿼리는 소수의 파일만 읽고 범위가 한정되지 않은 쿼리는 모든 파일을 읽습니다.

sigiro_spans는 아홉 개 테이블 중 하나입니다. 호스팅 가이드는 아홉 개 테이블 전체와 각 테이블에 적용되는 규칙을 나열하며, 테이블에 대하여는 각 테이블 계열이 무엇을 측정하는지 설명합니다.

지금까지 한 일

서버를 시작하고, OpenTelemetry를 전송하고, 무엇이 변했는지 묻고, 그 이유를 묻고, 그 답변 중 하나를 입증하는 쿼리를 실행했습니다. 이것이 에이전트가 스스로 실행하는 루프 전체입니다.

다음 단계

에이전트로 코드 계측하기 — 서비스에 아직 OpenTelemetry가 적용되지 않은 경우
호스팅 sigiro로 텔레메트리 전송하기 — 서버를 직접 운영하고 싶지 않은 경우
CLI 참조 — 나머지 네 개의 서브커맨드, 그리고 모든 플래그와 환경 변수
GET /openapi.json — 기계가 읽을 수 있는 전체 API이며, 키는 필요하지 않습니다