문제 해결
문제 해결 (Troubleshooting)
이 섹션은 이미지 렌더러 문제 해결에 대한 일반적인 질문에 답해요. 이 안내는 자체 관리형(self-managed) Grafana 사용자에게 유용하며, 이미지 렌더러가 관리되므로 Grafana Cloud 사용자에게는 크게 유용하지 않아요.
출처: 문서
본문
이 섹션은 이미지 렌더러 문제 해결에 대한 일반적인 질문에 답해요. 이 안내는 자체 관리형 Grafana 사용자에게 유용해요. 이미지 렌더러가 관리되므로 Grafana Cloud 사용자에게는 크게 유용하지 않아요.
사용 가능한 구성 옵션 (Available configuration options)
사용 가능한 모든 옵션을 보려면 다음을 실행해요:
docker run --rm grafana/grafana-image-renderer:latest server --help
서비스 기능의 대부분은 구성 가능한 옵션이 있어요. 이미지 렌더러를 문제 해결할 때 이 옵션들이 가장 먼저 변경해야 할 것들인 경우가 많아요.
이 안내서의 나머지 부분은 이 옵션들이 무엇이고 무엇을 하는지 명확히 해서 올바른 실험과 변경을 할 수 있게 해줘요.
구성 파일 형식과 경로 (Configuration file formats and paths)
서비스는 현재 작업 디렉터리에서 구성 파일을 읽어요. Docker 이미지에서는 기본적으로 /home/nonroot/예요.
파일 이름은 config.json, config.yaml, 또는 config.yml 중 하나여야 해요.
이미지 렌더러 모니터링 (Monitor the image renderer)
Prometheus 또는 Grafana Mimir로 메트릭을, OpenTelemetry 호환 트레이싱 백엔드(예: Grafana Tempo)로 트레이스를 모니터링할 수 있어요. 둘 다 설정하는 것을 권장해요:
- HTTP 포트(기본
:8081)의/metrics로 메트릭 스크레이퍼를 지정해요. - 서비스(
--tracing.endpoint)를 트레이싱 백엔드로 지정해요.
사전 구축된 모니터링 대시보드는 예시 대시보드를 참고해요.
HTTP 서버 바인드 주소 변경 (Change the HTTP server bind address)
--server.addr 옵션을 사용해 HTTP 서버 바인드 주소를 변경해요. 특정 주소가 지정되지 않으면 모든 인터페이스에서 수신해요. 포트만 변경하는 문법은 :8081 또는 다른 포트 번호예요.
여러 인증 토큰 사용 (Use multiple authentication tokens)
옵션을 여러 번 지정해요. 예: --server.auth-token <token1> --server.auth-token <token2>.
JSON 또는 YAML을 사용한다면 목록을 사용할 수 있어요:
server:
auth-token:
- <token1>
- <token2>
환경 변수의 경우 쉼표로 구분된 목록을 사용해요.
로깅 레벨 변경 (Change the logging level)
--log.level 옵션으로 로그 레벨을 변경해요. 유효한 값은 debug, info, warn, error예요. debug는 매우 장황해요. 프로덕션 배포는 보통 info 또는 warn을 사용해야 해요.
HTTP 서버에 TLS 설정 (Set up TLS on the HTTP server)
다음 옵션으로 HTTP 서버를 TLS(HTTPS)로 제공할 수 있어요:
- --server.certificate-file: PEM 형식의 TLS 인증서 파일 경로
- --server.key-file: PEM 형식의 TLS 개인 키 파일 경로. 주어진 인증서 파일과 일치하는 키여야 해요.
- --server.min-tls-version: 수락할 최소 TLS 버전. 유효한 값은
1.0,1.1,1.2(기본),1.3이에요. 기본값은 대부분의 보안에 민감한 사용자에게 충분해요.
상호 TLS(mTLS)는 현재 지원되지 않아요.
트레이싱 백엔드와 mTLS 설정 (Set up mTLS with the tracing backend)
다음 옵션으로 트레이싱 백엔드에 대한 연결의 mTLS를 설정할 수 있어요:
- --tracing.trusted-certificate: PEM 형식의 신뢰된 CA 인증서 파일 경로. 트레이싱 백엔드의 인증서를 검증하는 데 사용돼요.
- --tracing.client-certificate: PEM 형식의 클라이언트 인증서 파일 경로. 트레이싱 백엔드에 인증하는 데 사용돼요.
- --tracing.client-key: PEM 형식의 클라이언트 개인 키 파일 경로. 주어진 클라이언트 인증서 파일과 일치하는 키여야 해요.
커스텀 브라우저 바이너리 사용 (Use a custom browser binary)
--browser.path 옵션으로 브라우저 바이너리를 설정해요. 브라우저는 Chrome DevTools Protocol을 지원해야 하므로 선택지가 다소 제한돼요. Chromium, Google Chrome, Microsoft Edge, Brave 및 Chromium 기반의 유사 브라우저에서 잘 작동해요. Chromium만 공식적으로 지원돼요. 버그가 Chromium으로 재현되지 않으면 우선순위가 낮아지거나 수정 없이 닫힐 수 있어요.
GPU 가속 사용 (Use GPU acceleration)
--browser.gpu 옵션으로 브라우저에서 GPU 가속을 활성화해요. Docker, Kubernetes 같은 일부 환경이나 다른 컨테이너·VM 런타임에서는 GPU를 서비스로 전달하기 위해 추가 구성이 필요할 수 있어요.
브라우저에서 커스텀 플래그 활성화 (Enable custom flags in the browser)
--browser.flag 옵션으로 브라우저에 플래그를 전달해요. 형식은 --${flag}=${value} 또는 --${flag}이며 -- 접두사가 필요해요. 파서는 각 브라우저 플래그를 기준으로 분할하며, 플래그 사이에 공백이 필요해요. 두 개 이상의 브라우저 플래그를 전달할 때는 아래 예시처럼 --browser.flag 옵션을 따옴표로 묶어야 해요.
예를 들어 --browser.flag="--headless=false --host-resolver-rules=MAP * 127.0.0.1, EXCLUDE grafana --no-sandbox"는 헤드풀(headful) 모드를 활성화하고, 브라우저가 grafana 호스트를 제외한 모든 네트워크 요청을 127.0.0.1로 해석하도록 강제하며, 샌드박스 모드를 비활성화해요.
브라우저 샌드박스 활성화 (Enable the browser sandbox)
--browser.sandbox 옵션으로 샌드박스를 활성화해요. 일부 Linux 배포판, Docker, Kubernetes, OpenShift 및 기타 컨테이너·VM 설정에서는 즉시 작동하지 않을 수 있어요. 다양한 가상화 기능, seccomp 프로필, AppArmor 프로필, Linux capabilities 등을 활성화해야 할 수 있어요.
요청 격리를 위한 Linux 네임스페이스 사용 (Use Linux namespaces for request isolation)
Caution
Linux 네임스페이스를 활성화하는 옵션이 있지만, 이 기능은 지원되지 않아요. 위험을 감수하고 진행하세요. 버그를 보고하기 전에 이 옵션이 비활성화되어 있는지 확인하세요.
각 렌더링 요청에 새 Linux 네임스페이스를 사용해 서비스와 다른 요청으로부터 전체 브라우저를 격리하려면 --browser.namespaced 옵션을 사용해요. 이 기능은 Linux와 다양한 capabilities 및 AppArmor 프로필 설정이 필요해요.
기본 브라우저 시간대 변경 (Change the default browser time zone)
Note
모든 요청이 요청 쿼리 파라미터에서 이를 오버라이드할 수 있어요.
기본 시간대를 변경하려면 --browser.timezone 옵션을 IANA 시간대 이름으로 설정해요. 예: America/Los_Angeles 또는 Europe/Berlin. 많은 컨테이너가 TZ 환경 변수를 자동으로 설정해요. 이 값이 기본으로 사용돼요.
브라우저의 모든 요청에 헤더 추가 (Add a header to every request from the browser)
Note
대상 웹사이트의 CORS 설정에 따라 모든 요청이 깨질 수 있어요.
--browser.header <name>=<value>로 새 헤더를 설정할 수 있어요. 이 헤더는 브라우저가 만드는 모든 요청에 추가돼요.
브라우저의 모든 요청에 트레이스 헤더 전달 (Pass through a trace header to every request from the browser)
트레이싱이 설정되어 있으면 기본적으로 활성화돼요. 나가는 요청은 Traceparent 헤더를 받아요. 서비스로 들어오는 요청에 Traceparent 헤더가 있으면 그 값이 사용돼요. 그렇지 않으면 모든 요청에 대해 새 트레이스가 시작돼요.
불완전한 출력과 요청 타임아웃 이해 (Understand incomplete outputs and request timeouts)
브라우저는 웹 페이지가 준비될 때까지 기다려요. 이는 다음 모두가 완료되거나 타임아웃될 때까지 기다려서 이루어져요:
- 모든 웹 포트를 스크롤합니다(즉, 전체 페이지 로드). 매 스크롤 후 브라우저는
--browser.scroll-wait옵션이 선언한 기간(기본 50밀리초)을 기다려요. - 브라우저는
--browser.readiness.prior-wait옵션이 선언한 기간(기본 1초)을 기다려요. - 전체 시퀀스는
--browser.readiness.timeout옵션이 선언한 기간(기본 30초) 후에 타임아웃돼요:- 시퀀스는
--browser.readiness.interval옵션이 선언한 기간(기본 100밀리초)마다 반복돼요. - 브라우저는 모든 Grafana 쿼리가 완료될 때까지 기다려요. 단,
--browser.readiness.disable-query-wait옵션이 활성화된 경우는 제외예요. 이 기능은 Scenes가 활성화되어 있어야 해요. Scenes가 활성화되지 않으면 검사가 조용히 건너뛰어져요. 쿼리가--browser.readiness.give-up-on-all-queries옵션이 선언한 기간 내에 완료되지 않으면 검사가 조용히 건너뛰어져요. 기본적으로 이 타임아웃은 비활성화돼요. --browser.readiness.give-up-on-first-query옵션이 선언한 기간 내에 첫 번째 쿼리가 감지되지 않으면 검사가 조용히 건너뛰어져요. 기본적으로 이 타임아웃은 3초예요.--browser.readiness.wait-for-n-query-cycles가 1보다 큰 값으로 설정되면 서비스는 진행 전에 N개의 전체 쿼리 사이클이 성공할 때까지 기다려요. 각 쿼리 사이클은--browser.readiness.interval옵션이 선언한 기간으로 구분돼요. 이 사이클 중 쿼리 타임아웃이 지나면 검사가 조용히 건너뛰어져요.- 브라우저는 모든 네트워크 요청이 완료될 때까지 기다려요. 단,
--browser.readiness.disable-network-wait옵션이 활성화된 경우는 제외예요. 네트워크 요청이--browser.readiness.network-idle-timeout옵션이 선언한 기간 내에 완료되지 않으면 검사가 조용히 건너뛰어져요. 기본적으로 이 타임아웃은 비활성화돼요. - 브라우저는 웹 페이지의 레이아웃이 안정화(더 이상 데이터 변경 없음)될 때까지 기다려요. 이는
--browser.readiness.disable-dom-hashcode-wait옵션으로 비활성화할 수 있어요. 웹 페이지가--browser.readiness.dom-hashcode-timeout옵션이 선언한 기간 내에 안정화되지 않으면 검사가 조용히 건너뛰어져요. 기본적으로 이 타임아웃은 비활성화돼요.
- 시퀀스는
서비스가 컨테이너의 모든 메모리를 소모 (The service eats up all the memory in the container)
GOMEMLIMIT 환경 변수를 컨테이너 메모리 제한보다 낮은 값(예: 1GiB)으로 설정해요. Chromium이 요청을 제공하려면 여유 메모리가 필요하므로 값은 컨테이너 메모리 제한과 같아서는 안 돼요. 컨테이너 메모리 제한에 할당된 8 GiB마다 이 환경 변수에 1 GiB를 추가할 것을 권장해요.
지원되지 않는 CPU 아키텍처 (Unsupported CPU architectures)
지원되지 않는 CPU 아키텍처의 경우 GitHub에서 이슈를 열 수 있어요. 또는 GitHub 저장소의 지침에 따라 서비스를 직접 컴파일해요.
에어갭된 환경에서 이미지 렌더러 사용 (Use the image renderer service in an air-gapped environment)
에어갭(air-gapped) 환경은 공개 인터넷에 접근할 수 없고 Docker를 지원하지 않는 등 요구 사항이 있을 수 있는 환경이에요. Grafana Enterprise 고객은 고객 지원으로 더 많은 도움을 받을 수 있어요.
Docker 사용 시 (With Docker)
시작하기 전에 다음이 있는지 확인하세요:
- USB 스틱, SD 카드, 외장 하드 드라이브 등 환경으로 데이터를 전송하는 수단
- 에어갭 환경의 Docker
- 인터넷에 연결된 환경의 Docker
이미지의 TAR 파일을 내보내려면:
docker image save -o grafana-image-renderer.tar grafana/grafana-image-renderer:latest
에어갭 환경과 다른 CPU 아키텍처를 사용한다면 이미지를 저장할 때 --platform을 지정해야 할 수 있어요. 예를 들어 에어갭 x86_64(amd64) 머신이 있다면 --platform linux/amd64를 사용해요.
다음으로 파일을 머신으로 전송해요. 마지막으로 에어갭 환경에서 이미지를 가져와요:
docker image load grafana-image-renderer.tar
Docker 없이 (Without Docker)
시작하기 전에 다음이 있는지 확인하세요:
- USB 스틱, SD 카드, 외장 하드 드라이브 등 환경으로 데이터를 전송하는 수단
Linux와 Windows용 바이너리 파일을 GitHub Releases 페이지에서 릴리스해요. 시스템에 맞는 바이너리를 다운로드해 머신으로 전송해요. Chromium 기반 브라우저도 별도로 설치해야 해요.
Grafana가 docker화되지 않은 상태에서 Docker 사용 (Use Docker without Grafana being dockerised)
host networking을 사용하거나 바이너리 릴리스를 사용할 수 있어요.
Docker 없이 Windows에서 이미지 렌더러 사용 (Use the image renderer service on Windows without Docker)
GitHub Releases 페이지에서 Windows 바이너리를 다운로드할 수 있어요. 예를 들어 ARM64 Windows 호스트에서 Brave 브라우저와 함께 이미지 렌더러를 사용하려면:
.\grafana-image-renderer-windows-arm64.exe server --browser.path "C:\Program Files\BraveSoftware\Brave-Browser\Application\brave.exe"
브라우저는 별도로 설치해야 하고 Chromium 기반이어야 해요.
Chromium의 커스텀 CA 인증서 (Custom CA certificates in Chromium)
CA 인증서가 문제인지 식별하는 것은 서비스 로그에서 net::ERR_CERT_AUTHORITY_INVALID 오류를 확인해서 이루어져요. 이 오류를 찾으려면 --log.level debug 옵션으로 디버그 로깅을 활성화해야 할 수 있어요.
컨테이너화되지 않은 Linux (Non-containerized Linux)
컨테이너화되지 않은 Linux에서는 nss 도구(Debian에서는 libnss3-tools)가 필요해요. 또한 서비스를 실행하는 사용자의 $HOME 디렉터리를 알아야 하는데, eval echo ~<username>(예: eval echo ~grafana) 또는 getent passwd <username>(예: getent passwd grafana)을 실행해 찾을 수 있어요. 해당 사용자로 다음을 실행해요:
certutil -d sql:"$HOME"/.pki/nssdb -A -n internal-root-ca -t C -i /path/to/internal-root-ca-here.crt.pem
다른 도구가 필요할 수도 있어요. 오류 메시지가 환경에서 무엇이 빠졌는지 나타낼 가능성이 높아요.
컨테이너화되지 않은 Windows (Non-containerized Windows)
컨테이너화되지 않은 경우에는 Linux와 동일하게 하지만 전역 저장소에 대해 수행해요:
certutil –addstore "Root" <path>/internal-root-ca-here.crt.pem
컨테이너 (Container)
가장 쉬운 방법은 공식 이미지를 기반으로 CA 인증서를 직접 Docker 이미지에 통합하는 것이에요:
# Consider using a pinned version.
FROM grafana/grafana-image-renderer:latest
# Elevate our permissions to access system resources.
USER root
RUN mkdir -p /usr/local/share/ca-certificates/
# Convert from .pem to .crt
RUN openssl x509 -inform PEM -in rootCA.pem -out /usr/local/share/ca-certificates/rootCA.crt
# Regenerate the CA certificates in the container.
RUN update-ca-certificates --fresh
# Reassume the nonroot user for the service execution.
USER nonroot
# Note: for Kubernetes, OpenShift, and other setups, this may need a numeric ID. See the upstream Dockerfile for which UID to use.
# Some CA certificates also need to explicitly be included in the user's network security services database.
RUN mkdir -p /home/nonroot/.pki/nssdb
RUN certutil -d sql:/home/nonroot/.pki/nssdb -A -n internal-root-ca -t C -i /usr/local/share/ca-certificates/rootCA.crt
PDF 내보내기에서 왜곡된 패널 (Distorted panels in the PDF export)
이것은 대부분 Grafana에서 오래된 PDF 렌더링 엔진을 사용하기 때문이에요. 이것이 해당되는지 확인하려면 Grafana 구성에서 newPDFRendering 기능 플래그가 명시적으로 false로 설정되었는지 확인해요. 이 문제를 해결하려면 기능 토글 오버라이드를 제거해요.
구성 디버깅 (Debug the configuration)
Note
여기 권장되는 명령은 비밀과 민감한 정보를 평문으로 출력해요. 출력을 공유하거나 로그에 저장할 때 주의하세요.
서비스가 예상대로 작동하지 않는 것처럼 보일 때는 구성이 유효하지 않기 때문일 수 있어요. 플래그가 유효하지 않으면 서비스가 시작되지 않지만, 구성 파일에는 알 수 없는 키가 포함될 수 있고 조용히 무시돼요.
구성이 유효하고 기대한 대로인지 디버깅하려면 print-config 명령을 실행해 구성을 나타내는 Go 구조의 전체 덤프를 얻을 수 있어요. 예를 들어:
docker run --rm -v ./config.json:/home/nonroot/config.json grafana/grafana-image-renderer:latest print-config
이 명령은 server 명령과 정확히 같은 플래그와 구성 파일을 사용해요.
접근 가능한 도메인 제한 (Limiting accessible domains)
Chrome 정책을 사용해 브라우저가 접근할 수 있는 도메인을 제한할 수 있어요. 이를 제한하려면 Chrome 정책 JSON 파일을 /etc/chromium/policies/managed/에 마운트해요. 내용은 예를 들어:
{
"URLBlocklist": ["*"],
"URLAllowlist": ["https://*", "chrome://*"]
}