OBSERVABILITY

Prometheus·Grafana 로컬 관측 구성

공식 Prometheus 바이너리와 Grafana Ubuntu 저장소를 검증해 설치하고 두 UI를 loopback에 제한한 채 retention·최소 권한·TLS proxy·백업·복구 기준까지 구성합니다.

Prometheus 설치Grafana 설치모니터링 서버prometheus.ymlGrafana securityTSDB retention

지원 환경Ubuntu Server 24.04 LTS · systemd

예상 시간약 80분

난이도중급

검토일2026-09-04

BEFORE YOU START

시작 전에 준비하세요

공식 다운로드 페이지에서 기록한 Prometheus tarball URL·SHA-256·아키텍처

승인된 retention time·size와 별도 data volume 용량·IOPS

Grafana를 TLS reverse proxy 또는 SSH tunnel로만 접근하는 네트워크 경계

dashboard·datasource·Grafana DB와 Prometheus 설정·TSDB의 백업 정책

권장 대상 단일 관측 호스트에서 metrics 수집·dashboard를 시작하고 저장공간·접근제어·복구까지 책임질 운영 담당자

FOLLOW THE RECIPE

8단계 구성·점검 레시피

확인시스템을 변경하지 않는 점검 단계

지원 아키텍처·저장공간·포트 확인

관측 데이터 증가량과 compaction 여유를 계산하고 기존 9090·3000 listener와 package를 확인합니다. retention size는 compaction 중 일시 초과할 수 있습니다.

OS·아키텍처

cat /etc/os-release
uname -m

CPU·메모리·disk

nproc
free -h
df -hT / /var/lib

기존 listener

sudo ss -lntp | grep -E ':(9090|3000)\b'

기존 설치

systemctl status prometheus.service grafana-server.service --no-pager -l
dpkg-query -W grafana 2>/dev/null

공식 binary 아키텍처와 host가 일치합니다.
retention과 compaction을 감당할 별도 disk 여유가 있습니다.
9090·3000 port와 data path의 기존 소유자를 확인했습니다.

결과 읽기

disk 여유나 IOPS가 부족하거나 기존 데이터 소유가 불명확하면 설치를 진행하지 않습니다.

다음 판단

공식 checksum·repository key·기존 config를 확인합니다.

확인시스템을 변경하지 않는 점검 단계

공급망·백업·노출 사전 점검

공식 Prometheus 다운로드 페이지의 SHA-256과 Grafana key fingerprint를 변경 기록에 남기고 기존 설정·data·public exposure를 조사합니다.

0700 작업 디렉터리

umask 077
mktemp -d -p /var/tmp haru-prometheus.XXXXXXXX

출력된 절대 경로를 <PROMETHEUS_WORK_DIR>에 그대로 대입합니다.

Prometheus release 후보

stat -Lc '%a %U:%G %n' <PROMETHEUS_WORK_DIR>
curl -fL -o <PROMETHEUS_WORK_DIR>/prometheus.tar.gz <APPROVED_PROMETHEUS_TARBALL_URL>
sha256sum <PROMETHEUS_WORK_DIR>/prometheus.tar.gz

권한이 700임을 확인하고, 출력 hash를 공식 다운로드 페이지의 <APPROVED_PROMETHEUS_SHA256>와 사람이 대조합니다.

Grafana key 확인

curl -fL -o <PROMETHEUS_WORK_DIR>/grafana.asc https://apt.grafana.com/gpg-full.key
gpg --show-keys --with-fingerprint <PROMETHEUS_WORK_DIR>/grafana.asc

설정·data 권한

sudo stat -Lc '%a %U:%G %n' /etc/prometheus /var/lib/prometheus /etc/grafana /var/lib/grafana 2>/dev/null

방화벽

sudo ufw status verbose

Prometheus SHA-256과 Grafana key fingerprint를 공식 페이지와 대조했습니다.
기존 Grafana DB·dashboard·datasource와 TSDB backup 소유자를 확인했습니다.
9090·3000은 인터넷에 직접 공개하지 않습니다.

결과 읽기

checksum·key가 다르거나 기존 data backup이 없으면 변경을 중단합니다.

다음 판단

고정 binary와 package를 설치합니다.

변경패키지·설정·서비스 상태가 달라지는 단계

Prometheus binary와 Grafana 고정 package 설치

검증한 tarball만 풀어 전용 binary를 설치하고 Grafana stable repository는 별도 keyring과 signed-by로 등록합니다.

변경 단계입니다. 대상 서버, 백업 파일, 서비스 중단 영향과 바로 이전 상태로 돌아가는 방법을 다시 확인하세요.

Prometheus 압축 해제·binary 설치

mkdir -m 0700 <PROMETHEUS_WORK_DIR>/extract
tar -xzf <PROMETHEUS_WORK_DIR>/prometheus.tar.gz -C <PROMETHEUS_WORK_DIR>/extract --strip-components=1
sudo install -o root -g root -m 0755 <PROMETHEUS_WORK_DIR>/extract/prometheus /usr/local/bin/prometheus
sudo install -o root -g root -m 0755 <PROMETHEUS_WORK_DIR>/extract/promtool /usr/local/bin/promtool

Grafana keyring 설치·저장소 편집

sudo install -d -m 0755 /etc/apt/keyrings
sudo install -o root -g root -m 0644 <PROMETHEUS_WORK_DIR>/grafana.asc /etc/apt/keyrings/grafana.asc
sudoedit /etc/apt/sources.list.d/grafana.list

Grafana 고정 package

sudo apt update
apt-cache policy grafana
sudo apt install grafana=<APPROVED_GRAFANA_PACKAGE_VERSION>

버전

/usr/local/bin/prometheus --version
/usr/local/bin/promtool --version
/usr/sbin/grafana-server -v

설정 예시 · /etc/apt/sources.list.d/grafana.list

Grafana OSS stable repository

deb [signed-by=/etc/apt/keyrings/grafana.asc] https://apt.grafana.com stable main

공식 key fingerprint를 먼저 확인하며 beta repository를 섞지 않습니다.

Prometheus checksum과 실제 version이 승인값입니다.
Grafana repository는 stable·signed-by만 사용합니다.
beta와 enterprise·OSS 공급원을 혼용하지 않았습니다.

결과 읽기

package candidate·binary version이 승인값과 다르면 서비스를 만들지 않습니다.

다음 판단

전용 계정·config·unit·Grafana 설정을 백업하고 편집합니다.

변경패키지·설정·서비스 상태가 달라지는 단계

Prometheus·Grafana 설정 백업과 편집

전용 계정과 data path를 만들고 Prometheus config·unit, Grafana ini를 고유한 suffix로 백업합니다. 두 web server는 loopback에만 bind합니다.

변경 단계입니다. 대상 서버, 백업 파일, 서비스 중단 영향과 바로 이전 상태로 돌아가는 방법을 다시 확인하세요.

Prometheus 계정·경로

getent passwd prometheus >/dev/null || sudo useradd --system --home /var/lib/prometheus --shell /usr/sbin/nologin prometheus
sudo install -d -o root -g prometheus -m 0750 /etc/prometheus
sudo install -d -o prometheus -g prometheus -m 0750 /var/lib/prometheus

Prometheus config·unit 백업·편집

if sudo test -f /etc/prometheus/prometheus.yml; then sudo cp --archive --no-clobber /etc/prometheus/prometheus.yml /etc/prometheus/prometheus.yml.<BACKUP_SUFFIX>; fi
if sudo test -f /etc/systemd/system/prometheus.service; then sudo cp --archive --no-clobber /etc/systemd/system/prometheus.service /etc/systemd/system/prometheus.service.<BACKUP_SUFFIX>; fi
sudoedit /etc/prometheus/prometheus.yml
sudoedit /etc/systemd/system/prometheus.service

Grafana 설정 백업·편집

if sudo test -f /etc/grafana/grafana.ini; then sudo cp --archive --no-clobber /etc/grafana/grafana.ini /etc/grafana/grafana.ini.<BACKUP_SUFFIX>; fi
sudoedit /etc/grafana/grafana.ini

권한

sudo chown root:prometheus /etc/prometheus/prometheus.yml
sudo chmod 0640 /etc/prometheus/prometheus.yml
sudo stat -Lc '%a %U:%G %n' /etc/prometheus/prometheus.yml /etc/grafana/grafana.ini

설정 예시 · /etc/prometheus/prometheus.yml

로컬 self scrape 최소 구성

global:
  scrape_interval: 30s
  evaluation_interval: 30s

scrape_configs:
  - job_name: prometheus
    static_configs:
      - targets: ["127.0.0.1:9090"]

실제 target은 사설망 allowlist, TLS와 최소 권한 인증을 별도 설계합니다. 고카디널리티 label은 비용·용량을 급증시킵니다.

설정 예시 · /etc/systemd/system/prometheus.service

loopback·retention 제한 Prometheus unit

[Unit]
Description=Prometheus
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=prometheus
Group=prometheus
ExecStart=/usr/local/bin/prometheus --config.file=/etc/prometheus/prometheus.yml --storage.tsdb.path=/var/lib/prometheus --storage.tsdb.retention.time=<RETENTION_TIME> --storage.tsdb.retention.size=<RETENTION_SIZE> --web.listen-address=127.0.0.1:9090
Restart=on-failure
RestartSec=10s
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/lib/prometheus
UMask=0027

[Install]
WantedBy=multi-user.target

web lifecycle·admin API는 기본 비활성 상태로 둡니다. retention size보다 compaction 여유 disk가 더 필요합니다.

설정 예시 · /etc/grafana/grafana.ini

loopback·익명 차단 Grafana 조각

[server]
protocol = http
http_addr = 127.0.0.1
http_port = 3000
domain = <GRAFANA_DOMAIN>
root_url = https://<GRAFANA_DOMAIN>/
enforce_domain = true

[auth.anonymous]
enabled = false
hide_version = true

[auth.basic]
password_policy = true

[security]
cookie_secure = true
cookie_samesite = strict

cookie_secure는 승인된 HTTPS reverse proxy를 전제로 합니다. 서브경로로 공개하려면 root_url에 경로를 포함하고 serve_from_sub_path 설정과 proxy rewrite를 별도로 검증합니다. OAuth/SAML을 쓰면 SameSite 요구도 공식 문서와 재검토합니다.

config·unit·grafana.ini의 기존 파일은 백업했고, 원본이 없던 파일은 신규 생성으로 변경 기록에 남겼습니다.
Prometheus는 config 읽기·TSDB 쓰기만, Grafana는 package 기본 전용 계정으로 실행합니다.
9090·3000이 loopback이고 retention time·size가 승인값입니다.
scrape credential은 config literal이 아닌 제한된 파일을 사용합니다.

결과 읽기

config에 비밀 literal이나 public bind가 있으면 시작하지 않습니다.

다음 판단

promtool·systemd·Grafana 설정을 검증한 뒤 시작합니다.

변경패키지·설정·서비스 상태가 달라지는 단계

설정 검증 후 두 서비스 시작

Prometheus YAML과 unit을 검증하고 Grafana는 loopback 상태로 시작합니다. 초기 관리자 암호를 변경하기 전 외부 proxy에 연결하지 않습니다.

변경 단계입니다. 대상 서버, 백업 파일, 서비스 중단 영향과 바로 이전 상태로 돌아가는 방법을 다시 확인하세요.

Prometheus config

sudo -u prometheus /usr/local/bin/promtool check config /etc/prometheus/prometheus.yml
sudo systemd-analyze verify /etc/systemd/system/prometheus.service

서비스 시작

sudo systemctl daemon-reload
sudo systemctl enable --now prometheus.service grafana-server.service

loopback health

curl -fsS http://127.0.0.1:9090/-/ready
curl -fsS http://127.0.0.1:3000/api/health

listen 확인

sudo ss -lntp | grep -E '127\.0\.0\.1:(9090|3000)\b'

promtool·unit 검증이 성공합니다.
두 service가 active이고 loopback에만 listen합니다.
Grafana 초기 admin credential을 제한된 TLS 세션에서 즉시 변경했습니다.

결과 읽기

local health 실패 또는 wildcard bind이면 reverse proxy를 열지 않고 journal·config를 수정합니다.

다음 판단

target·TSDB·dashboard·TLS 접근을 검증합니다.

변경패키지·설정·서비스 상태가 달라지는 단계

target·TSDB·dashboard·재시작 검증

Prometheus runtime status와 target, TSDB disk, Grafana datasource·dashboard를 실제 사용자 권한으로 확인합니다. API 출력의 내부 주소와 label은 외부 공유 전에 마스킹합니다.

변경 단계입니다. 대상 서버, 백업 파일, 서비스 중단 영향과 바로 이전 상태로 돌아가는 방법을 다시 확인하세요.

서비스·health

systemctl status prometheus.service grafana-server.service --no-pager -l
curl -fsS http://127.0.0.1:9090/-/healthy
curl -fsS http://127.0.0.1:3000/api/health

Prometheus target

curl -fsS 'http://127.0.0.1:9090/api/v1/targets?state=active'

내부 target URL과 label이 포함되므로 제한된 터미널에서 확인합니다.

TSDB 사용량

sudo du -sh /var/lib/prometheus /var/lib/grafana
df -hT /var/lib

로그

journalctl -u prometheus.service -u grafana-server.service --since '-15 min' --no-pager

모든 필수 target이 up이고 scrape error가 없습니다.
Grafana datasource와 최소 dashboard query가 성공합니다.
disk 증가율과 retention·compaction 여유가 기준 범위입니다.
재시작 뒤에도 config·dashboard·datasource가 유지됩니다.

결과 읽기

target up만으로 alert·dashboard 정확성이 보장되지는 않으므로 알려진 fixture와 alert rule test를 추가합니다.

다음 판단

access·비밀·plugin·data backup을 점검합니다.

확인시스템을 변경하지 않는 점검 단계

접근제어·비밀·plugin·backup 보안

Grafana Viewer도 datasource에 임의 query를 보낼 수 있으므로 anonymous를 끄고 datasource credential 권한을 최소화합니다. Prometheus·Grafana port는 loopback을 유지합니다.

listen·방화벽

sudo ss -lntp | grep -E ':(9090|3000)\b'
sudo ufw status verbose

파일 권한

sudo stat -Lc '%a %U:%G %n' /etc/prometheus/prometheus.yml /var/lib/prometheus /etc/grafana/grafana.ini /var/lib/grafana

Grafana plugin 목록

sudo grafana cli plugins ls

unit sandbox

systemd-analyze security prometheus.service --no-pager

9090·3000은 loopback이며 TLS proxy·SSO·SSH tunnel만 접근합니다.
anonymous access는 꺼져 있고 admin 계정은 일상 dashboard 열람에 사용하지 않습니다.
datasource credential은 read-only·최소 범위이고 dashboard export에 secret이 없습니다.
plugin·binary·package는 승인 버전과 checksum으로 관리합니다.
Grafana DB·dashboard·datasource와 Prometheus config·TSDB의 암호화 backup·restore test가 있습니다.
<...> 자리표시자는 승인된 리터럴 값으로 직접 치환하고 외부 입력으로 shell 명령을 조립하거나 eval하지 않습니다.

결과 읽기

public UI, default credential, writable config, 검증되지 않은 plugin이면 운영 사용을 중단합니다.

다음 판단

현재 data snapshot과 config backup으로 package·binary rollback 경계를 확인합니다.

변경패키지·설정·서비스 상태가 달라지는 단계

config·binary·package와 data 복구

설정 rollback과 data rollback을 분리합니다. TSDB·Grafana SQLite를 파일 단위로 복원할 때는 서비스를 중지하고 같은 시점 snapshot을 사용합니다.

변경 단계입니다. 대상 서버, 백업 파일, 서비스 중단 영향과 바로 이전 상태로 돌아가는 방법을 다시 확인하세요.

현재 상태·버전

/usr/local/bin/prometheus --version
/usr/sbin/grafana-server -v
sha256sum /etc/prometheus/prometheus.yml /etc/grafana/grafana.ini

서비스 중지

sudo systemctl stop prometheus.service grafana-server.service

승인된 점검창과 monitoring blind spot 대체 수단이 있을 때만 실행합니다.

A. backup이 있는 설정 복원

if sudo test -f /etc/prometheus/prometheus.yml.<BACKUP_SUFFIX>; then sudo cp --archive /etc/prometheus/prometheus.yml.<BACKUP_SUFFIX> /etc/prometheus/prometheus.yml; fi
if sudo test -f /etc/systemd/system/prometheus.service.<BACKUP_SUFFIX>; then sudo cp --archive /etc/systemd/system/prometheus.service.<BACKUP_SUFFIX> /etc/systemd/system/prometheus.service; fi
if sudo test -f /etc/grafana/grafana.ini.<BACKUP_SUFFIX>; then sudo cp --archive /etc/grafana/grafana.ini.<BACKUP_SUFFIX> /etc/grafana/grafana.ini; fi

B. backup이 없는 신규 설정 격리

sudo systemctl disable --now prometheus.service grafana-server.service
sudo install -d -o root -g root -m 0700 <APPROVED_QUARANTINE_DIR>
if sudo test -f /etc/prometheus/prometheus.yml; then sudo mv --no-clobber /etc/prometheus/prometheus.yml <APPROVED_QUARANTINE_DIR>/prometheus.yml.new; fi
if sudo test -f /etc/systemd/system/prometheus.service; then sudo mv --no-clobber /etc/systemd/system/prometheus.service <APPROVED_QUARANTINE_DIR>/prometheus.service.new; fi
if sudo test -f /etc/grafana/grafana.ini; then sudo mv --no-clobber /etc/grafana/grafana.ini <APPROVED_QUARANTINE_DIR>/grafana.ini.new; fi
if sudo test -L /etc/systemd/system/multi-user.target.wants/prometheus.service; then sudo mv --no-clobber /etc/systemd/system/multi-user.target.wants/prometheus.service <APPROVED_QUARANTINE_DIR>/prometheus.service.link; fi
if sudo test -L /etc/systemd/system/multi-user.target.wants/grafana-server.service; then sudo mv --no-clobber /etc/systemd/system/multi-user.target.wants/grafana-server.service <APPROVED_QUARANTINE_DIR>/grafana-server.service.link; fi
sudo systemctl daemon-reload

backup이 없고 변경 기록으로 신규 생성 파일·link임이 확인될 때만 A 대신 실행합니다. binary·package·TSDB·Grafana DB는 purge하지 않습니다.

검증·재시작

if sudo test -f /etc/prometheus/prometheus.yml; then sudo -u prometheus /usr/local/bin/promtool check config /etc/prometheus/prometheus.yml; fi
if sudo test -f /etc/systemd/system/prometheus.service; then sudo systemd-analyze verify /etc/systemd/system/prometheus.service; sudo systemctl daemon-reload; sudo systemctl start prometheus.service grafana-server.service; curl -fsS http://127.0.0.1:9090/-/ready; curl -fsS http://127.0.0.1:3000/api/health; fi
systemctl is-enabled prometheus.service grafana-server.service || true
systemctl is-active prometheus.service grafana-server.service || true

선택한 config·binary·Grafana package·data schema가 호환됩니다.
동일 시점 snapshot이 필요한 data rollback을 단순 config rollback과 섞지 않았습니다.
target·dashboard·alert·disk 지표가 회복됐습니다.

결과 읽기

Grafana downgrade와 DB schema, Prometheus downgrade와 TSDB format은 호환되지 않을 수 있어 공식 release note와 snapshot 복구 시험 없이 강행하지 않습니다.

다음 판단

blind spot 시간과 변경·복구 version/checksum, 누락 metrics를 기록합니다.

SECURITY CHECK

운영 전 마지막 보안 점검

Prometheus tarball SHA-256과 Grafana repository key·signed-by를 공식 문서에서 확인합니다.
Prometheus·Grafana는 전용 비 root 계정과 loopback listener를 사용합니다.
Grafana anonymous·기본 admin 사용을 제한하고 datasource credential은 read-only 최소 권한입니다.
scrape·datasource secret은 config·dashboard export·shell history에 평문으로 남기지 않습니다.
retention·compaction disk 여유·backup 암호화·restore test·monitoring blind spot 대체책을 둡니다.
<...> 자리표시자는 승인된 리터럴 값으로 직접 치환하고 외부 입력으로 shell 명령을 조립하거나 eval하지 않습니다.

COMMON ERRORS

자주 막히는 지점

Prometheus target DOWN

증상: Targets 화면에 connection refused·timeout·x509가 나타납니다.
가능한 원인: target listener·firewall·DNS·TLS·인증 또는 scrape path가 맞지 않을 수 있습니다.
확인 순서: Prometheus host에서 제한된 curl로 경로를 확인하고 TLS 검증을 끄지 않습니다.

트러블슈팅으로 이어보기

Prometheus disk 급증

증상: TSDB가 retention 예상보다 빠르게 증가하고 disk alert가 발생합니다.
가능한 원인: 고카디널리티 label, scrape interval·target 증가와 compaction 임시 공간이 원인일 수 있습니다.
확인 순서: label·series·증가율을 확인하고 무작정 TSDB 파일을 삭제하지 않습니다.

트러블슈팅으로 이어보기

Grafana login 또는 datasource 실패

증상: UI health는 정상이지만 로그인·query가 실패합니다.
가능한 원인: cookie_secure와 TLS proxy, datasource URL·credential·RBAC가 맞지 않을 수 있습니다.
확인 순서: HTTPS 경계·로그와 최소 권한 datasource 계정을 확인하고 anonymous로 우회하지 않습니다.

트러블슈팅으로 이어보기

PRIMARY REFERENCES

공식 문서

설치 저장소와 지원 버전은 바뀔 수 있습니다. 검토일 이후에는 링크된 공식 문서와 현재 서버의 패키지 후보 버전을 함께 확인하세요.

시작 전에 준비하세요

8단계 구성·점검 레시피

운영 전 마지막 보안 점검

자주 막히는 지점

Prometheus target DOWN

Prometheus disk 급증

Grafana login 또는 datasource 실패

공식 문서

설치 후 문제라면 여기서 이어가세요

함께 볼 구성 레시피