가이드

작성자 Matt Connor 2026-08-06 · 업데이트됨 2026-08-13

Superlog 셀프 호스팅 설치 방법 및 주요 기능

Q: OTLP 익스포터는 어떤 포트를 가리켜야 하는가?

README에서 http://localhost:4101로 지정한 Superlog 수집 프록시를 가리켜야 합니다. 이 프록시는 /v1/traces, /v1/logs, /v1/metrics를 서비스하며, x-api-key 헤더나 authorization: bearer 헤더에서 가져온 프로젝트 수집 키로 인증을 수행합니다. 포트 4318은 하위의 OpenTelemetry collector이며, 그곳으로 직접 데이터를 내보내면 데이터에 프로젝트 ID를 부여하는 구성 요소인 프록시를 거치지 않게 됩니다. PORT이 설정되지 않으면 프록시는 포트 4000으로 대체하므로, 4101이라고 가정하기 전에 ss -lntp를 실행하여 바인딩된 포트를 확인하십시오.

Q: 커밋을 고정해야 하는가, 아니면 main 브랜드를 추적해야 하는가?

커밋을 고정하십시오. 2026년 8월 기준으로 저장소에 릴리스 태그가 없으므로, main이 유일하게 변하는 대상이며 매주 여러 번의 커밋이 발생합니다. 테스트한 SHA를 기록하고 해당 버전을 배포하십시오. 업데이트하기 전에 변경 사항(diff)을 읽어보십시오. git log --oneline ..main이 검토 대상이며, 버전 업데이트 후 새로 필요한 변수가 있는지 확인하려면 애플리케이션별 .env.example 파일을 가장 먼저 살펴보아야 합니다.

Superlog를 사용해 OTLP 트레이스, 로그, 메트릭을 인시던트로 자동 분류하는 방법을 알아봅니다. Docker Compose로 Postgres와 ClickHouse를 구성하고, 릴리스 태그가 없는 저장소에서 직접 서비스를 빌드하여 운영하는 실무 가이드를 제공합니다.

Superlog 셀프 호스팅 시 설치되는 항목

Superlog를 셀프 호스팅하려면 저장소를 복제한 뒤, Docker Compose로 Postgres, ClickHouse, OpenTelemetry collector를 실행하고, 데이터베이스 마이그레이션을 한 번 수행한 다음, 4개의 Node 서비스를 소스에서 직접 시작해야 합니다. 애플리케이션은 OTLP(OpenTelemetry protocol) 트레이스, 로그, 메트릭을 수신 포트로 전송하며, Superlog는 이를 핑거프린팅하여 반복되는 항목을 하나의 인시던트로 그룹화하고, 에이전트가 1차 분류를 수행합니다. 설치에는 오후 반나절 정도가 소요됩니다. 시작하기 전에 리소스 점유율과 실제 제한 사항을 확인하는 것이 좋습니다.

Superlog는 Apache 2.0 라이선스를 따르며 github.com/superloglabs/superlog에서 확인할 수 있습니다. 2026년 8월 기준으로 약 1.2k개의 스타를 받았고, main에는 약 460개의 커밋이 있으나 릴리스 태그는 전혀 없습니다. 마지막 지점이 설치 방식에 영향을 줍니다. git checkout v1.0.0에는 체크아웃할 항목이 없으므로, 직접 커밋을 고정하거나 복제한 시점의 최신 main 상태로 실행해야 합니다.

Uptime Kuma와 Langfuse가 답하지 못하는 Superlog만의 기능

외부에서 보기에 셀프 호스팅 모니터링 도구들은 서로 비슷해 보입니다. 하지만 실제로는 그렇지 않으며, 잘못된 도구를 운영하면 아무런 이득 없이 서버 자원만 낭비하게 됩니다.

Uptime Kuma는 외부에서 엔드포인트를 프로브(probe)하며 서비스가 가동 중인지에 대한 질문에만 답합니다.
Zabbix는 Ubuntu 24.04의 호스트와 서비스를 감시하며, 설정한 임계값에 따라 CPU, 메모리, 디스크 및 서비스 상태를 확인합니다.
Langfuse는 LLM 호출을 추적하며, 각 호출의 프롬프트, 모델, 토큰, 지연 시간 및 비용을 기록합니다.
Superlog는 일반적인 서비스가 이미 내보내고 있는 텔레메트리 데이터를 수집하여 반복되는 장애를 인시던트(incident)로 변환합니다.

Superlog는 '무엇이 고장 났고, 왜 고장 났는가'라는 다른 차원의 질문을 다룹니다. 이 도구는 LLM 호출에 관여하지 않으며 외부에서 프로브를 수행하지도 않습니다. 일반적인 애플리케이션 코드에서 OTLP를 수집하고, 온콜(on-call) 담당자가 수행할 첫 번째 단계인 트리아주(triage) 과정을 에이전트가 대신 처리합니다.

VPS 예산 측면에서 중요한 차이점은 스토리지입니다. Uptime Kuma는 수천 개의 체크 결과만 저장하므로 1 GB RAM에서도 원활하게 작동합니다. 반면 Superlog는 컬럼형 저장소(column store)를 사용합니다. 텔레메트리는 한 번 기록된 뒤 수백만 개의 행에 걸쳐 시간 범위별로 쿼리되기 때문입니다. 이것이 바로 ClickHouse가 필요한 이유이며, Postgres가 적합하지 않은 이유입니다. Postgres는 여전히 스택에 남아 프로젝트, 사용자, 인시던트, 수집 키와 같은 소규모 관계형 데이터를 관리합니다.

docker compose up -d는 실제로 무엇을 시작합니까?

세 개의 컨테이너가 시작되지만, 그중 Superlog는 포함되어 있지 않습니다. 한 번의 명령어로 설치가 완료될 것이라 기대하는 사용자들에게는 의외일 수 있습니다.

postgres:16: 호스트 포트 5434로 게시됨
clickhouse/clickhouse-server:26.1: HTTP용 8123 포트 및 네이티브 프로토콜용 9000 포트
otel/opentelemetry-collector-contrib:0.150.1: gRPC용 4317 포트 및 HTTP 기반 OTLP용 4318 포트

Superlog 애플리케이션은 호스트에서 소스 코드를 통해 실행되며, pnpm dev에 의해 시작됩니다. 2026년 8월 기준으로 저장소에 프로덕션용 compose 파일이 포함되어 있지 않으므로, 장기적인 설치를 위해서는 각 앱의 start 스크립트를 감싸는 systemd 유닛을 직접 작성하거나, 트리에 포함된 앱별 Dockerfile을 사용해야 합니다.

스팬(span)이 이동하는 경로를 기억하십시오. 아래에서 발생하는 모든 오류는 이 경로의 특정 구간이 단절되었음을 의미합니다. 애플리케이션은 OTLP 데이터를 Superlog 수신 프록시로 전송합니다. 프록시는 수집 키(ingest key)로 요청을 인증하고 프로젝트 ID를 기록한 뒤, 이를 수집기(collector)로 전달합니다. 수집기는 클라이언트가 설정하려고 시도한 superlog.* 속성을 제거하고, 프록시가 제공한 헤더에서 superlog.project_id을 추가한 뒤, 데이터를 배치(batch) 처리하여 ClickHouse에 기록합니다. 이후 웹 앱과 API는 ClickHouse에서 텔레메트리 데이터를, 그 외 모든 정보는 Postgres에서 읽어옵니다.

속성 제거 과정은 단순한 장식이 아니라 실제 다중 테넌시(multi-tenancy) 제어 기능입니다. 이 과정이 없다면 유효한 수집 키를 가진 누구나 스스로 superlog.project_id를 설정하여 다른 프로젝트의 데이터 영역에 기록할 수 있게 됩니다.

VPS는 어느 정도 크기여야 합니까?

낮은 수집 볼륨의 단일 노드 설치라면 4 vCPU, 8 GB RAM, 40 GB SSD를 계획하십시오. 이는 측정값이 아닌 계획을 위한 최소 기준이므로, 시작 크기로 간주하고 실제 트래픽에 맞춰 조정하십시오.

메모리는 네 곳에서 사용됩니다. ClickHouse는 충분한 RAM이 있는 환경을 전제로 설계되었으며 기본 설정도 이를 따릅니다. Postgres 16은 원격 측정 데이터가 아닌 메타데이터를 보관하므로 메모리 사용량이 적습니다. 컬렉터 역시 마찬가지입니다. 하지만 4개의 Node 프로세스는 다릅니다. Vite 개발 서버와 3개의 tsx watch 프로세스는 각각 수백 MB를 점유하며, 이것이 2 GB 사양의 서버에서 pnpm dev을 실행하는 것이 어려운 이유입니다.

디스크는 더 조용하게 발생하는 문제입니다. 이 모노레포의 pnpm install은 단 하나의 스팬(span)을 수집하기도 전에 AWS SDK, ClickHouse 클라이언트, OpenTelemetry SDK, React 툴체인을 불러옵니다. 이후 ClickHouse는 트래픽에 따라 용량이 증가합니다. 다음 두 가지를 측정하십시오:

df -h /
free -m
docker stats --no-stream
docker compose exec clickhouse clickhouse-client --database superlog --query "SELECT table, formatReadableSize(sum(bytes_on_disk)) AS size FROM system.parts WHERE active AND database = 'superlog' GROUP BY table ORDER BY sum(bytes_on_disk) DESC"

분당 수백 개의 스팬을 전송하는 소규모 서비스 환경에서는 서버 부하가 적고 ClickHouse도 대부분 유휴 상태를 유지합니다. 문제가 되는 부하는 급증하는 트래픽입니다. 예를 들어 잘못된 배포로 인해 분당 수천 개의 동일한 오류가 발생하는 경우입니다. 핑거프린팅(fingerprinting) 기술이 이를 하나의 인시던트로 통합하여 보여주더라도, ClickHouse는 그 아래의 모든 행을 기록합니다.

보존 기간은 직접 설정해야 합니다. 컬렉터의 ClickHouse 익스포터는 테이블, otel_traces, otel_logs 및 메트릭 유형별 테이블을 생성하며, infra/collector/config.yaml의 설정에서 지정한 경우에만 TTL(Time To Live)이 적용됩니다. 자동으로 만료되는 데이터는 없으므로, 계획을 세우지 않으면 바쁜 한 달 뒤 디스크가 가득 찰 수 있습니다.

고정된 커밋에서 설치하기

git clone https://github.com/superloglabs/superlog.git
cd superlog
git tag -l
git log -1 --format='%H %cs %s'

git tag -l 아무것도 출력되지 않는 것이 2026년 8월 기준 정상적인 결과입니다. 테스트를 마친 커밋을 선택하고 해당 커밋에 머무르십시오:

git checkout 0d3a6c8bb63eda3493e6ba0003e7c2a70750bc1e

다음은 툴체인입니다:

node -v
corepack enable
corepack prepare pnpm@9.12.0 --activate
pnpm -v

package.json는 engines.node을 >=20.0.0로, packageManager를 pnpm@9.12.0으로 선언합니다. 이전 버전의 Node에서 설치를 실행하면 pnpm이 ERR_PNPM_UNSUPPORTED_ENGINE과 함께 중단되며, 필요한 버전을 명시합니다. Ubuntu 24.04 아카이브의 nodejs 패키지는 20보다 낮으므로, NodeSource나 nvm을 통해 Node 20 이상을 설치하십시오. 저장소는 .nvmrc를 포함하고 있으므로, nvm을 사용 중이라면 nvm use이 의도된 버전을 선택합니다.

pnpm install
docker compose up -d
docker compose ps

up -d이 준비 완료를 의미한다고 믿지 말고 상태 확인(health check)을 기다리십시오. Postgres와 ClickHouse 모두 compose 파일에 상태 확인을 선언합니다:

curl -sS http://127.0.0.1:8123/ping
pg_isready -h 127.0.0.1 -p 5434 -U postgres

ClickHouse는 Ok.로 응답하고 pg_isready은 accepting connections로 응답합니다. 8123 포트에서 연결이 거부되면 컨테이너가 시작 중이거나 종료된 상태입니다. docker compose logs clickhouse를 통해 상태를 확인하십시오. 커널이 메모리 부족으로 프로세스를 종료한 경우 docker inspect $(docker compose ps -q clickhouse) | grep -i oomkilled은 true을 보고하며, 이는 설정 오류가 아니라 서버 사양이 너무 낮음을 의미합니다.

다음은 마이그레이션과 애플리케이션입니다:

pnpm --filter @superlog/db db:migrate
pnpm dev

포트 번호가 5432가 아닌 5434임을 유의하십시오. compose 파일은 호스트에 이미 설치된 Postgres와 충돌하지 않도록 Postgres를 5434 포트에 게시하며, 앱의 .env.example 파일은 DATABASE_URL=postgres://postgres:postgres@localhost:5434/superlog를 통해 이를 맞춥니다. Postgres가 이미 실행 중인 서버에서 마이그레이션을 5432 포트로 지정하면 연결이 거부되거나, 더 심각하게는 잘못된 데이터베이스에 마이그레이션이 적용될 수 있습니다.

pnpm dev은 저장소의 Procfile에 나열된 네 가지 프로세스인 api, web, worker, proxy를 시작합니다. 각 프로세스는 출력을 tmp/logs/로 리다이렉트하므로, tail -f tmp/logs/proxy.log에서 수집 과정을 모니터링할 수 있습니다. README에 따르면 웹 앱은 http://localhost:5173, API는 http://localhost:4100, OTLP 수신은 http://localhost:4101에서 실행됩니다.

어떤 포트가 실제로 바인딩되었는지 확인한 뒤 연결을 시도하십시오:

ss -lntp | grep -E '4100|4101|5173'
curl -sS http://127.0.0.1:4101/health

이는 나중에 중요해집니다. 프록시는 PORT 환경 변수에서 자신의 포트를 읽으며, PORT이 설정되지 않은 경우 4000 포트를 기본값으로 사용합니다. 개발 스택은 이를 자동으로 설정하지만, 직접 작성한 systemd 유닛은 그렇지 않습니다. 따라서 4000 포트에서 대기 중인 프록시를 대상으로 4101 포트에 익스포터를 연결하면 연결 거부 오류가 발생하며 다른 단서는 제공되지 않습니다.

트레이스 하나를 전송하여 오류를 발생시키고 인시던트 확인하기

웹 앱에서 프로젝트를 생성하고 ingest key를 복사합니다. 수집 서버는 모든 요청을 이 키로 인증하므로, 키 없이 전송된 텔레메트리는 ClickHouse에 도달하지 않습니다.

표준 환경 변수를 사용하여 OpenTelemetry SDK를 수집 서버로 지정합니다.

export OTEL_SERVICE_NAME=checkout-api
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4101
export OTEL_EXPORTER_OTLP_HEADERS='x-api-key=YOUR_INGEST_KEY'

수집 서버는 x-api-key 헤더에서 키를 읽으며, 익스포터 설정이 더 쉬운 경우 authorization: bearer YOUR_INGEST_KEY도 허용합니다. 이 서버는 3개의 표준 OTLP 경로인 /v1/traces, /v1/logs, /v1/metrics와 /health를 제공합니다.

주의해야 할 함정이 하나 있습니다. OTEL_EXPORTER_OTLP_ENDPOINT는 베이스 URL이며 SDK는 여기에 신호 경로를 덧붙입니다. OTEL_EXPORTER_OTLP_TRACES_ENDPOINT과 같은 신호별 변수는 경로를 덧붙이지 않고 그대로 사용합니다. 신호별 변수를 http://127.0.0.1:4101로 설정하면 모든 익스포트가 /로 전송되는데, 이는 유효한 경로가 아니므로 데이터가 도착하지 않습니다. 결과적으로 앱은 정상처럼 보이지만 SDK 로그에는 익스포트 실패가 기록됩니다.

Node 서비스의 경우 코드 수정 없이 파이프라인을 검증할 수 있습니다.

npm install @opentelemetry/api @opentelemetry/auto-instrumentations-node
node --require @opentelemetry/auto-instrumentations-node/register server.js

이제 의도적으로 오류를 발생시킵니다. 예외를 던지는 경로라면 무엇이든 상관없습니다.

curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3000/boom

첫 번째 공백이 실패 지점을 알려주므로 순서대로 홉을 확인합니다.

tail -n 50 tmp/logs/proxy.log
docker compose exec clickhouse clickhouse-client --database superlog --query 'SELECT count() FROM otel_traces'

웹 앱은 비어 있는데 otel_traces의 카운트가 증가한다면 프로젝트 불일치이므로 ingest key가 어떤 프로젝트에 속하는지 확인하십시오. 프록시 로그에 활동이 있는데 카운트가 변하지 않는다면 컬렉터나 ClickHouse 쓰기 문제이므로 docker compose logs collector을 읽어보십시오. 프록시 로그에 아무런 활동이 없다면 익스포터가 수집 서버에 도달하지 못한 것이므로 포트, 경로 또는 키 거부 여부를 확인해야 합니다.

웹 앱에서는 반복되는 실패가 요청당 한 줄씩 기록되지 않고 하나의 인시던트로 통합됩니다. Superlog는 들어오는 신호를 핑거프린팅하여 일치하는 것끼리 그룹화합니다. 이는 4,000개의 동일한 오류가 받은 편지함을 채우는 것과 하나의 페이지에 요약되는 것의 차이입니다. 이후 에이전트가 해당 그룹에 대한 조사 내용을 작성합니다.

조사 단계는 모델을 호출하므로 워커에 모델 제공자 설정이 필요합니다. 외부 문서 대신 고정한 커밋의 각 앱 디렉터리 내 .env.example 파일에서 변수 이름을 확인하십시오. 이 변수들은 main에 따라 변경될 수 있기 때문입니다. GitHub 및 Sentry 통합도 마찬가지이며, 각각 docs/github-app-setup.md과 docs/sentry-app-setup.md에 자체 설정 문서가 있고 웹훅 페이로드는 docs/webhooks.md에 문서화되어 있습니다.

인테이크는 비공개로 유지하고 에이전트는 읽기 전용으로 설정하기

Docker는 기본적으로 컨테이너 포트를 0.0.0.0에 게시합니다. Docker는 ufw보다 먼저 패킷을 평가하는 DOCKER-USER 체인에 자체 규칙을 작성하므로, 이렇게 게시된 포트는 ufw를 우회합니다. 공인 IP를 사용하는 VPS에서 배포된 compose 파일은 ClickHouse HTTP를 8123번 포트에, Postgres를 5434번 포트에 노출하여 인터넷에서 접근할 수 있게 합니다. 해당 파일의 자격 증명은 개발용 기본값으로, ClickHouse 사용자는 default에 비밀번호가 없으며, Postgres는 사용자명과 비밀번호 모두 postgres로 설정되어 있습니다.

이 포트들을 루프백(loopback) 주소에 바인딩하십시오. compose 파일의 모든 게시된 포트는 호스트 측 설정을 환경 변수에서 가져오므로, 저장소 루트에 .env 파일을 생성하는 것만으로 충분합니다.

POSTGRES_HOST_PORT=127.0.0.1:5434
CLICKHOUSE_HTTP_HOST_PORT=127.0.0.1:8123
CLICKHOUSE_TCP_HOST_PORT=127.0.0.1:9000
COLLECTOR_GRPC_HOST_PORT=127.0.0.1:4317
COLLECTOR_HTTP_HOST_PORT=127.0.0.1:4318

결과를 신뢰하기 전에 확인한 후 컨테이너를 다시 생성하십시오.

docker compose config
docker compose up -d
ss -lntp | grep -E '5434|8123|9000|4317|4318'

docker compose config은 해석된 파일을 출력하므로, 추측하는 대신 127.0.0.1:5434:5432을 읽어 확인할 수 있습니다. 이때 ss는 127.0.0.1:5434을 표시해야 하며 0.0.0.0:5434를 표시해서는 안 됩니다. ports를 재선언하는 compose 오버라이드 파일로 이 문제를 해결하려 하지 마십시오. Compose는 포트 목록을 교체하는 것이 아니라 파일 간에 병합하므로, 결국 두 바인딩이 모두 적용되어 공개 포트가 여전히 열려 있게 됩니다.

인테이크(intake)도 동일한 주의가 필요합니다. 인제스트 키(ingest key)는 헤더를 통해 전송되므로 앞단에 TLS(transport layer security)가 필요합니다. 프록시 앞의 nginx나 Caddy에서 TLS를 종료하거나, 인제스트를 사설 네트워크 또는 WireGuard 터널 내부로 유지하십시오. 5173번 포트의 웹 앱은 Vite 개발 서버이므로 인터넷에 노출될 이유가 전혀 없습니다.

다음은 에이전트 자체에 대한 설정입니다. Superlog의 핵심은 에이전트가 문제를 조사하고 수정안을 제안한다는 점이며, 여기서 중요한 단어는 '제안'입니다. 실제 사고 몇 건에서 에이전트가 작동하는 것을 지켜볼 때까지는 운영 환경에 대해 읽기 전용 권한을 유지하십시오. GitHub App에 읽기 권한을 부여하고, 검토 가능한 풀 리퀘스트를 생성하도록 하십시오. 원격 측정 데이터를 읽고 패치를 작성하는 에이전트는 유용합니다. 서비스를 재시작할 수 있는 에이전트는 차원이 다른 위험을 수반하므로, 이는 기본값으로 상속받는 것이 아니라 의도적으로 결정해야 합니다. 비용 또한 동일한 주의가 필요합니다. 모든 조사는 모델 호출을 발생시키기 때문입니다. 소음이 많은 운영 시스템에 에이전트를 적용하기 전에 VPS에서의 에이전트 사용 예산을 설정하고, 예상치 못한 풀 리퀘스트가 발생했을 때 추적할 수 있도록 에이전트가 실제로 수행한 작업 기록을 유지하십시오.

발생 가능한 오류와 해당 오류를 지칭하는 문자열

pnpm install 중 발생하는 ERR_PNPM_UNSUPPORTED_ENGINE은 Node 버전이 20 미만임을 의미합니다. node -v 명령으로 이를 한 줄로 확인할 수 있습니다.
마이그레이션 중 발생하는 ECONNREFUSED 127.0.0.1:5434는 compose 스택이 실행 중이지 않거나, DATABASE_URL에 잘못된 포트가 지정되었음을 의미합니다.
ClickHouse가 반복적으로 재시작되는 현상은 대개 메모리 문제입니다. docker compose logs clickhouse을 읽어본 뒤, 컨테이너에서 OOMKilled 값이 true인지 확인하십시오.
웹 애플리케이션은 비어 있는데 익스포터가 성공을 보고한다면, 데이터가 프록시를 거치지 않고 4318 포트의 수집기로 직접 전달되어 프로젝트 스탬핑이 누락된 경우입니다.
프로덕션 설치 환경에서 4101 포트에 Connection refused가 발생하면 프록시가 PORT=4000로 대체(fallback)된 것입니다. 유닛 파일에 PORT를 명시적으로 설정하십시오.
0.0.0.0:8123을 출력하는 docker compose ps은 루프백 바인딩이 적용되지 않았음을 의미합니다. docker compose config을 실행하여 확인된 포트들을 읽어보십시오.

Flawless, HyperProbe 및 Superlog의 위치

이 범주는 아직 초기 단계이며, 에이전트가 접근할 수 있는 범위에 따라 도구가 나뉩니다. Flawless는 Kubernetes를 대상으로 하는 오픈 소스 AI SRE(Site Reliability Engineering) 도구로, 파이프라인을 직접 소유하기보다 기존의 Prometheus, Loki, Grafana 스택에서 데이터를 읽어옵니다. HyperProbe는 정반대의 방식을 취합니다. 2026년 8월 기준으로 비공개 소스인 호스팅 제품이며, 실행 중인 프로세스 내부에 읽기 전용 프로브를 배치하여 변수 상태를 캡처하고, 이를 MCP(Model Context Protocol)를 통해 어시스턴트에 노출합니다.

Superlog는 이 두 도구의 중간에 위치합니다. OTLP 수집부터 ClickHouse 저장소까지 파이프라인 전체를 직접 소유하며, 에이전트를 수정 단계가 아닌 트리아주(triage) 단계에 배치합니다. 이러한 설계 때문에 Superlog를 자체 호스팅하는 것은 단순히 컨테이너를 띄워두는 수준을 넘어 인프라 운영의 결정이 됩니다. Superlog를 실행한다는 것은 곧 컬럼형 저장소(column store)를 운영한다는 의미이며, 이는 직접 소유한 다른 데이터베이스와 동일한 수준의 관리가 필요함을 뜻합니다.

FAQ

자가 호스팅 Superlog는 RAM이 얼마나 필요한가?

낮은 수집 볼륨의 단일 노드 기준으로 RAM 8 GB, vCPU 4개, 디스크 40 GB를 계획하십시오. 이 스택은 Postgres, ClickHouse, OpenTelemetry collector, 그리고 4개의 Node 프로세스로 구성되며, ClickHouse는 여유 자원을 필요로 합니다. 1 GB 또는 2 GB VPS로는 부족합니다. pnpm install 자체만으로도 무거우며, 부하가 걸리면 ClickHouse가 커널의 OOM(Out of Memory) 킬러에 의해 종료됩니다. 여기에 명시된 수치를 포함하여 공개된 어떤 수치도 맹신하지 말고, docker stats --no-stream 및 free -m을 사용하여 직접 수치를 측정하십시오.

OTLP 익스포터는 어떤 포트를 가리켜야 하는가?

README에서 http://localhost:4101로 지정한 Superlog 수집 프록시를 가리켜야 합니다. 이 프록시는 /v1/traces, /v1/logs, /v1/metrics를 서비스하며, x-api-key 헤더나 authorization: bearer 헤더에서 가져온 프로젝트 수집 키로 인증을 수행합니다. 포트 4318은 하위의 OpenTelemetry collector이며, 그곳으로 직접 데이터를 내보내면 데이터에 프로젝트 ID를 부여하는 구성 요소인 프록시를 거치지 않게 됩니다. PORT이 설정되지 않으면 프록시는 포트 4000으로 대체하므로, 4101이라고 가정하기 전에 ss -lntp를 실행하여 바인딩된 포트를 확인하십시오.

Superlog가 Uptime Kuma나 Zabbix를 대체하는가?

아닙니다. Uptime Kuma는 엔드포인트가 네트워크 외부에서 응답하는지 확인하며, Zabbix는 설정한 임계값에 따라 호스트 및 서비스 메트릭을 감시합니다. Superlog는 애플리케이션이 방출하는 트레이스, 로그, 메트릭을 소비하고 반복되는 장애를 인시던트로 그룹화합니다. 텔레메트리 파이프라인을 실행 중인 서버 자체가 죽었을 때도 보고할 수 있도록, 외부 업타임 프로브를 별도로 유지하십시오.

Superlog 에이전트가 운영 시스템을 변경할 수 있는가?

사용자가 부여한 권한 범위 내에서만 가능합니다. 에이전트의 출력은 조사 결과와 제안된 변경 사항이며, 사람이 이를 검토해야 합니다. 처음에는 GitHub App의 권한을 읽기 전용 및 풀 리퀘스트 생성으로 제한하고, 워커가 보유한 자격 증명도 읽기 권한으로 한정하십시오. 운영 환경에 대한 쓰기 권한 부여는 신중하게 결정해야 합니다. 텔레메트리를 읽고 검토용 패치를 작성하는 에이전트보다 서비스를 재시작할 수 있는 에이전트가 훨씬 더 큰 위험 요소를 내포하기 때문입니다.

커밋을 고정해야 하는가, 아니면 main 브랜드를 추적해야 하는가?

커밋을 고정하십시오. 2026년 8월 기준으로 저장소에 릴리스 태그가 없으므로, main이 유일하게 변하는 대상이며 매주 여러 번의 커밋이 발생합니다. 테스트한 SHA를 기록하고 해당 버전을 배포하십시오. 업데이트하기 전에 변경 사항(diff)을 읽어보십시오. git log --oneline <old-sha>..main이 검토 대상이며, 버전 업데이트 후 새로 필요한 변수가 있는지 확인하려면 애플리케이션별 .env.example 파일을 가장 먼저 살펴보아야 합니다.

#superlog#observability #opentelemetry #clickhouse#ai-sre