본문으로 건너뛰기
sigiro
한국어
English简体中文日本語한국어
Esc
↑↓이동↵열기⌘J미리보기
이 페이지에서

호스티드 sigiro로 텔레메트리 전송

OAuth 액세스 토큰으로 호스티드 sigiro에 OpenTelemetry를 전송한 뒤 SQL로 조회합니다. 운영할 인프라는 없으며, 초대 기반 베타 기간에는 저희가 각 테넌트를 설정합니다.

이 가이드는 저희가 운영하는 sigiro 호스트로 OpenTelemetry를 전송하는 방법과 데이터를 다시 조회하는 방법을 설명합니다. 직접 운영해야 하는 인프라는 없습니다.

sigiro는 트레이스, 로그, 메트릭, 프로파일을 읽습니다. 신규 사용자는 터미널에서 다음을 실행하십시오.

sigiro signup --name "Your Name" --email you@example.com
sigiro auth status

CLI는 운영체제 자격 증명 저장소에 인증 정보를 저장합니다. 아래의 <your-sigiro-host>를 운영자가 제공한 호스트로 바꾸십시오.

1. 가입하고 로그인하기

호스팅 인증은 Better Auth가 제공합니다. Organizations는 테넌트입니다. sigiro signup은 6자리 OTP를 이메일로 보내고 터미널에서 안전하게 입력하도록 한 뒤, 개인 워크스페이스를 정확히 하나 생성·활성화하고 브라우저 없이 OAuth 디바이스 인증을 내부에서 완료하며 자격 증명을 OS 자격 증명 저장소에 저장합니다. 기존 계정은 브라우저 기반 sigiro auth login을 사용하십시오. OAuth API를 수동으로 호출하거나 토큰을 복사하지 마십시오.

동일한 토큰으로 OTLP 인제스트와 API 쿼리를 인증합니다.

2. OpenTelemetry 익스포터를 sigiro로 지정하기

HTTP 기반의 표준 OTLP를 사용하십시오. 인증에는 표준 Authorization: Bearer 헤더를 사용합니다.

OTLP/HTTP:

export OTEL_EXPORTER_OTLP_ENDPOINT="https://<your-sigiro-host>"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer $(sigiro auth token)"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"

sigiro auth token은 저장된 세션을 갱신한 뒤 수명이 짧은 액세스 토큰을 출력합니다. 이 방식은 대화형 테스트에만 사용하고 장시간 실행되는 수집기의 비밀 값으로 사용하지 마십시오.

엔드포인트에는 포트를 붙이지 않습니다. 호스티드 sigiro는 표준 HTTPS 포트에서 OTLP를 종료하므로 https://api.sigiro.com 자체가 전체 엔드포인트입니다. 셀프 호스팅 퀵스타트의 :4318을 복사하지 마십시오. api.sigiro.com에서는 해당 포트가 연결을 거부하며, 연결에 실패한 SDK는 그 실패를 여기가 아니라 여러분의 서비스 로그에 기록합니다. 호스트가 다른 경우에는 운영자에게 문의하십시오.

api.sigiro.com에서는 OTLP/gRPC를 사용할 수 없습니다. 포트 4317은 닫혀 있고 gRPC 서비스 경로도 라우팅되지 않습니다. HTTP를 사용하시고, 다른 호스트에서 gRPC를 쓸 수 있다고 가정하기 전에 운영자에게 문의하십시오.

SDK는 각 시그널을 해당 표준 OTLP 경로(/v1/traces, /v1/logs, /v1/metrics, /v1development/profiles)로 전송하며, 이 경로를 위 엔드포인트 뒤에 덧붙입니다. 익스포터가 시그널별 엔드포인트를 받는 방식이라면 전체 경로를 지정하십시오. HTTP는 gzip을 지원하며 엔드포인트는 TLS를 사용합니다. 하나의 요청은 압축 해제 후 8 MB 이하여야 합니다. 기본 SDK 배치 크기는 이 한도보다 충분히 작습니다.

3. 데이터 수신 확인하기

텔레메트리를 전송하십시오. 플러시 간격이 약 1초이므로 몇 초 정도 기다리십시오. 그런 다음 다음 쿼리를 실행하십시오:

curl -s "https://<your-sigiro-host>/v1/query" \
  -H "Authorization: Bearer <oauth-access-token>" \
  --data 'SELECT count(*) AS n FROM sigiro_spans'

n이 0이 아니면 트레이스가 수신되고 있다는 뜻입니다. 첫 배치를 보낸 다음에만 쿼리하십시오. 데이터를 한 번도 전송하지 않은 신규 테넌트에는 스토리지가 없습니다.

4. 데이터 쿼리하기 (SQL API)

  • 엔드포인트: 메인 HTTPS 포트의 POST /v1/query.
  • 인증: Authorization: Bearer <oauth-access-token>.
  • 본문: JSON이 아닌 원시 SQL 문자열.
  • 응답: 행 객체로 구성된 JSON 배열. x-sigiro-truncated: true|false 헤더는 sigiro가 결과를 제한했는지 여부를 알려줍니다.

각 테넌트는 격리된 카탈로그를 가지므로 자신의 데이터만 볼 수 있습니다.

테이블: sigiro_spans, sigiro_logs, sigiro_metrics_gauge, sigiro_metrics_sum, sigiro_metrics_histogram, sigiro_metrics_exp_histogram, sigiro_profiles, 그리고 sigiro_anomalies 테이블. sigiro_anomalies 테이블은 미리 계산된 국면 전환(regime shift)을 담고 있습니다. 이상 탐지 패스가 이 전환을 지속적으로 기록합니다. GET /v1/anomalies는 동일한 전환을 타입이 지정된 JSON으로 제공합니다. 속성 컬럼(*_attributes, events_json 등)은 JSON 텍스트를 담습니다. 필드를 읽으려면 json_extract(col, '$.key') 또는 col ->> 'key'를 사용하십시오.

각 계열이 무엇을 측정하는지, 그리고 확신에 찬 오답을 만들어내는 한 가지 이름 충돌에 대해서는 테이블 소개를 참고하십시오.

허용되는 SQL: sigiro_* 테이블에 대한 SELECT만 가능합니다. sigiro는 쓰기와 DDL을 거부합니다. 또한 파일, URL, S3 리더(read_csv, read_parquet, glob 등)를 차단합니다. 조인, 윈도 함수, 집계 함수, json_extract는 모두 동작합니다.

CTE는 거부됩니다. WITH 절은 그 내용이 무엇이든 검증에 실패합니다. 파생 테이블 서브쿼리로 다시 작성하십시오: SELECT ... FROM (SELECT ...) t. 하나의 공유 카탈로그가 모든 테넌트를 담고 있으므로, 호스티드 서비스는 information_schema도 차단합니다.

예시:

-- Slowest operations, last hour
SELECT service_name, span_name,
       approx_quantile(duration, 0.95) / 1000.0 AS p95_ms, count(*) AS n
FROM sigiro_spans
WHERE timestamp > now() - INTERVAL '1 hour'
GROUP BY 1, 2 ORDER BY p95_ms DESC LIMIT 10;
-- Error-log rate per route, last 15 min
SELECT service_name, log_attributes ->> 'http.route' AS route, count(*) AS errors
FROM sigiro_logs
WHERE timestamp > now() - INTERVAL '15 minutes' AND severity_number >= 17
GROUP BY 1, 2 ORDER BY errors DESC;

5. 제한

제한 값 초과 시 sigiro의 동작
쿼리 타임아웃 10초 sigiro가 쿼리를 거부합니다 (400)
결과 행 수 100,000 sigiro가 응답을 절단하고 x-sigiro-truncated: true를 설정합니다
쿼리 메모리 약 400 MB 쿼리가 실패합니다 (400)
인제스트 본문 8 MB (압축 해제 기준) 413 (HTTP) / RESOURCE_EXHAUSTED (gRPC)
SQL/API 요청 속도 테넌트당 5 req/s, 버스트 20 429
OTLP/HTTP 요청 속도 소스당 50 req/s, 버스트 100 429

sigiro에는 보조 인덱스가 없습니다. 따라서 모든 쿼리를 timestamp로 제한하십시오. 제한을 두면 속도가 빨라집니다. 또한 타임아웃과 절단도 방지됩니다.

6. 데이터 보존

베타 기간에는 sigiro를 기록 시스템이 아니라 실시간 쿼리 서비스로 취급하십시오. 현재 보존 기간은 운영자에게 문의하십시오. 장기간 보관해야 하는 데이터는 내보내 두십시오.

다음 단계

이 페이지가 도움이 되었나요?