InfluxDB 데이터 소스 문제 해결

이 문서는 InfluxDB 데이터 소스를 구성하거나 사용할 때 겪을 수 있는 일반적인 문제에 대한 해결책을 제공해요. 문제는 일반적인 설정·사용 워크플로우 순서대로 정리되어 있어요. 구성 지침은 InfluxDB 데이터 소스 구성을 참고하세요.

출처: Troubleshoot InfluxDB data source issues

본문

연결 오류

다음 오류는 Grafana가 InfluxDB에 연결을 설정하거나 유지하지 못할 때 발생해요.

"Plugin health check failed" 또는 "An error occurred within the plugin"

증상:

InfluxDB를 사용하는 모든 패널이 "An error occurred within the plugin" 반환
새 InfluxDB 데이터 소스 추가가 "Plugin health check failed"로 실패
연결 설정이 UI에서 비어 보임

가능한 원인과 해결책:

원인	해결책
플랫폼 중단	모든 InfluxDB 패널이 동시에 실패하면 자체 구성을 조사하기 전에 Grafana Cloud 상태 페이지에서 활성 장애를 확인해요. 고객 측 조치 없이 해결되는 일시적 플랫폼 문제일 수 있어요.
인증 실패	Grafana 서버 로그에서 인증 관련 오류를 확인해요. 자격 증명이 만료되거나 교체되지 않았는지 확인해요.
일시적 네트워크 문제	오류가 스스로 해결될 수 있어요. 몇 분 기다렸다 Save & test를 재시도해요. 계속되면 Grafana와 InfluxDB 사이의 네트워크 연결을 확인해요.

InfluxDB에 연결 실패

오류 메시지: error performing influxQL query 또는 error performing flux query 또는 error performing sql query

원인: Grafana가 InfluxDB 서버에 네트워크 연결을 설정할 수 없음.

해결책:

데이터 소스 구성의 InfluxDB URL이 올바른지 확인해요.
InfluxDB가 실행 중이고 Grafana 서버에서 접근 가능한지 확인해요.
URL에 프로토콜(http:// 또는 https://)이 포함됐는지 확인해요.
포트가 올바른지 확인해요(InfluxDB 기본 API 포트는 8086).
연결을 차단하는 방화벽 규칙이 없는지 확인해요.
Grafana Cloud라면 InfluxDB 인스턴스가 공개적으로 접근 불가한 경우 Private data source connect를 구성했는지 확인해요.

PDC 연결이 "no such host"로 실패

오류 메시지: socks connect tcp ... -> influxdb.host:8086: dial tcp: lookup ... no such host

원인: Private data source connect (PDC)를 사용할 때 SOCKS 프록시 터널을 통해 InfluxDB URL을 확인할 수 없음.

해결책:

InfluxDB URL로 127.0.0.1이나 localhost를 사용하지 마세요. PDC는 SOCKS 프록시로 트래픽을 터널링하는데, 이 프록시는 루프백 주소를 확인할 수 없어요.
대신 머신의 LAN IP 주소나 확인 가능한 호스트 이름을 사용해요.
PDC 에이전트가 실행되는 네트워크에서 호스트 이름이 확인 가능한지 확인해요.
구성 변경 없이 오류가 갑자기 나타났다면 Grafana Cloud 상태 페이지에서 활성 장애를 확인해요.

인증서 갱신 실패 후 PDC 연결 중단

증상:

이전에 작동하던 PDC 연결 데이터 소스가 중단
PDC 에이전트 로그에 SSH 인증서 갱신·서명 오류
SOCKS 프록시 연결 오류로 쿼리 실패

원인: PDC 에이전트가 Grafana Cloud API 토큰으로 SSH 인증서를 주기적으로 갱신해요. 토큰이 잘못됐거나 만료됐거나 삭제됐으면 인증서 갱신이 실패하고, 현재 인증서가 만료되면 연결이 중단돼요.

해결책:

PDC 에이전트 로그에서 인증 또는 인증서 서명 오류를 확인해요.
PDC 에이전트 구성의 API 토큰이 유효한지 확인해요. 토큰이 만료됐거나 삭제됐다면 Grafana Cloud의 PDC 연결 페이지에서 새 토큰을 생성해 에이전트 구성을 업데이트해요.
토큰 업데이트 후 PDC 에이전트를 다시 시작해요.
에이전트 오류 코드, 로그 해석, 토큰 관리 지침은 Troubleshoot PDC issues 참고.

TLS 인증서 오류

오류 메시지: x509: certificate signed by unknown authority 또는 유사한 TLS 검증 오류

원인: InfluxDB가 Grafana 서버가 신뢰하는 CA(인증 기관)가 서명하지 않은 TLS 인증서를 제시함. 자체 서명 인증서와 내부 회사 CA에서 일반적. TLS 검증은 종단 간 적용되므로 PDC로 연결할 때도 이 오류가 발생해요.

해결책:

InfluxDB 데이터 소스는 각 데이터 소스 인스턴스에 대한 TLS 구성을 지원해요. 데이터 소스 설정에서 Auth and TLS/SSL Settings를 펼치고 CA cert를 활성화한 뒤 CA 인증서를 붙여넣어요. 자세한 내용은 Auth and TLS/SSL settings 참고.
InfluxDB 서버가 클라이언트 인증서를 요구한다면 TLS client auth를 활성화하고 서버 이름, 클라이언트 인증서, 클라이언트 키를 제공해요.
최후의 수단으로 Skip TLS verify를 활성화해 인증서 검증을 건너뛸 수 있어요. Grafana는 중간자 공격에 대한 보호를 비활성화하므로 프로덕션에서 권장하지 않아요.

Request timed out

오류 메시지: context deadline exceeded 또는 request timeout 또는 dial tcp <IP>:<port>: i/o timeout

원인: 응답을 받기 전에 InfluxDB 연결이 타임아웃됨. 인프라 변경(데이터베이스 호스트 마이그레이션 등)이 동시에 일어나는 Grafana 업그레이드 후에 흔함.

해결책:

Grafana 서버에서 InfluxDB 엔드포인트로의 네트워크 연결을 확인해요. DNS 해석, 방화벽 규칙, 포트 접근을 확인해요.
InfluxDB 호스트 IP 주소나 호스트 이름이 변경되지 않았는지 확인해요. 특히 인프라 마이그레이션이나 Grafana 업그레이드 후에 중요해요.
Grafana와 InfluxDB 사이의 네트워크 지연을 확인해요.
InfluxDB가 과부하되거나 성능 문제를 겪지 않는지 확인해요.
Advanced HTTP Settings 아래의 데이터 소스 구성에서 타임아웃 설정을 늘려요.
쿼리의 시간 범위나 복잡성을 줄여요.

인증 오류

다음 오류는 인증 자격 증명 또는 권한에 문제가 있을 때 발생해요.

Unauthorized (401)

오류 메시지: "401 Unauthorized" 또는 "authorization failed"

원인: 인증 자격 증명이 유효하지 않거나 없음. 자격 증명이 유효해도 일시적 네트워크 문제가 인증 오류로 표시될 수 있어요.

해결책:

오류가 간헐적이거나 구성 변경 없이 나타났다면 몇 분 기다렸다 Save & test를 재시도해 자격 증명을 교체하기 전에 일시적 네트워크 문제를 배제해요.
데이터 소스 구성의 토큰 또는 비밀번호가 올바른지 확인해요.
Flux와 SQL에서는 토큰이 만료되지 않았는지 확인해요.
InfluxDB 2.x의 InfluxQL에서는 토큰이 Token <your-token> 값의 Authorization 헤더로 설정됐는지 확인해요.
InfluxDB 1.x에서는 사용자 이름과 비밀번호가 올바른지 확인해요.
토큰이 지정된 버킷이나 데이터베이스에 접근하는 데 필요한 권한을 갖고 있는지 확인해요.

Forbidden (403)

오류 메시지: "403 Forbidden" 또는 "access denied"

원인: 인증된 사용자 또는 토큰이 요청한 리소스에 접근할 권한이 없음.

해결책:

토큰이 지정된 버킷이나 데이터베이스에 읽기 권한이 있는지 확인해요.
InfluxDB UI의 API Tokens 아래에서 토큰 권한을 확인해요.
Flux 쿼리의 organization ID가 올바른지 확인해요.
InfluxDB 2.x의 InfluxQL에서는 DBRP 매핑이 올바르게 구성됐는지 확인해요.

구성 오류

다음 오류는 데이터 소스가 올바르게 구성되지 않았을 때 발생해요.

URL 미구성

오류 메시지: missing URL from datasource configuration

원인: 데이터 소스 URL 필드가 비어 있음.

해결책:

Grafana에서 데이터 소스 구성을 열어요.
URL 필드에 프로토콜과 포트를 포함한 InfluxDB 인스턴스의 전체 URL을 입력해요(예: http://localhost:8086).
Save & test를 클릭해 연결을 확인해요.

알 수 없는 Influx 버전

오류 메시지: "unknown influx version"

원인: 데이터 소스 설정에서 쿼리 언어가 제대로 구성되지 않음.

해결책:

Grafana에서 데이터 소스 구성을 열어요.
Flux, InfluxQL, 또는 SQL 중 유효한 쿼리 언어가 선택되어 있는지 확인해요.
쿼리 언어를 InfluxDB 버전에 맞춰요.

InfluxDB 버전	권장 쿼리 언어	참고
1.x	InfluxQL	Flux는 1.8+부터 사용 가능하지만 InfluxQL이 기본 언어
2.x (OSS/Cloud)	Flux	InfluxQL은 v1 호환 API로도 사용 가능하지만 DBRP mapping 필요
3.x / Cloud Dedicated / Cloud Serverless	SQL 또는 InfluxQL	Flux는 InfluxDB 3.x에서 지원 안 함

각 쿼리 언어는 서로 다른 API 엔드포인트를 사용해요. InfluxDB 버전에 잘못된 언어를 선택하면 상태 확인과 쿼리가 실패해요.

잘못된 데이터 소스 정보 수신

오류 메시지: invalid data source info received

원인: 데이터 소스 구성이 불완전하거나 손상됨.

해결책:

데이터 소스를 삭제하고 다시 만들어요.
쿼리 언어에 따라 모든 필수 필드가 채워졌는지 확인해요:
- Flux: URL, Organization, Token, Default Bucket
- InfluxQL: URL, Database, User, Password
- SQL: URL, Database, Token

DBRP 매핑 필요

오류 메시지: InfluxDB 2.x에서 InfluxQL로 "database not found" 또는 쿼리가 데이터를 반환하지 않음

원인: InfluxDB 2.x의 InfluxQL 쿼리는 Database and Retention Policy(DBRP) 매핑이 필요해요.

해결책:

CLI나 API로 InfluxDB에 DBRP 매핑을 만들어요.
Manage DBRP Mappings 참고.
Grafana의 데이터베이스 이름이 DBRP 매핑과 일치하는지 확인해요.

브라우저 접근 모드 비활성화

오류 메시지: Direct browser access in the InfluxDB datasource is no longer available. Switch to server access mode.

원인: 데이터 소스가 더 이상 지원되지 않는 직접 브라우저 접근으로 구성됨.

해결책:

Grafana에서 데이터 소스 구성을 열어요.
접근 모드를 **Server (default)**로 변경해요.
Save & test를 클릭해 연결을 확인해요.

CSP 위반

증상:

InfluxDB 플러그인을 참조하는 브라우저 콘솔의 CSP 위반 오류
프록시 요청의 net::ERR_ABORTED
InfluxDB 플러그인이 브라우저에서 InfluxDB로 직접 연결 시도

원인: 구버전 Grafana를 실행 중. 브라우저 접근 모드는 Grafana 9.2.0에서 제거됐고, 이전 버전은 CSP 정책을 위반하는 직접 브라우저 연결을 시도할 수 있어요. 현재 버전의 데이터 소스는 서버(프록시) 접근만 지원하는데, 이 경우 Grafana 서버가 모든 쿼리를 InfluxDB로 보내고 브라우저는 InfluxDB에 직접 연결하지 않아요.

해결책:

최신 안정 Grafana 릴리스로 업그레이드해요. InfluxDB 데이터 소스는 Grafana 12.3.0 이상이 필요해요.
업그레이드 후 데이터 소스 접근 모드가 **Server (default)**로 설정되어 있는지 확인해요.

상태 확인 오류

다음 오류는 Save & test로 데이터 소스 연결을 검증할 때 발생해요. 각 쿼리 언어는 다른 상태 확인 쿼리를 사용해요.

Flux 상태 확인 오류

"error performing flux query" - 상태 확인 쿼리 buckets() 실행 실패. URL이 올바르고 도달 가능한지, 토큰이 유효하고 만료되지 않았는지, organization ID가 올바른지 확인.

"error reading buckets" - buckets() 쿼리가 실행됐지만 오류 반환. 토큰이 버킷 나열 권한이 있는지, organization ID가 토큰의 organization과 일치하는지 확인.

"error getting flux query buckets" - buckets() 쿼리가 오류 없이 실행됐지만 데이터 없음. 토큰 권한, organization ID, InfluxDB 실행·접근 가능 여부 확인.

InfluxQL 상태 확인 오류

"error performing influxQL query" - 상태 확인 쿼리 SHOW MEASUREMENTS 실행 실패. URL, 사용자 이름·비밀번호(InfluxDB 2.x는 토큰), 데이터베이스 이름 존재 확인.

"error reading influxDB" - SHOW MEASUREMENTS가 실행됐지만 오류 반환. 데이터베이스 이름, 사용자의 SHOW MEASUREMENTS 권한, InfluxDB 2.x DBRP 매핑 확인.

"error connecting InfluxDB influxQL" - 상태 확인은 완료됐지만 응답을 처리할 수 없음. 데이터베이스 이름, 권한, 데이터베이스 존재·measurement 포함 여부, 2.x DBRP 매핑 확인.

SQL 상태 확인 오류

"error performing sql query" - 상태 확인 쿼리 select 1이 FlightSQL 엔드포인트에서 실행 실패. URL(gRPC/FlightSQL로 연결), 토큰 유효성·권한, TLS 인증서 구성(TLS 없이 연결하면 Insecure Connection 토글), InfluxDB 3.x 인스턴스 실행·FlightSQL 엔드포인트 접근 가능 여부 확인.

0 measurements found

오류 메시지: datasource is working. 0 measurements found

원인: 연결은 성공했지만 데이터베이스에 measurement가 없음.

해결책:

올바른 데이터베이스에 연결하고 있는지 확인해요.
데이터베이스에 데이터가 기록됐는지 확인해요.
데이터베이스가 새 것이라면 연결을 확인하려고 테스트 데이터를 추가해요.

쿼리 오류

다음 오류는 쿼리 문법 또는 실행에 문제가 있을 때 발생해요.

쿼리 문법 오류

오류 메시지: "error parsing query: found THING" 또는 "failed to parse query: found WERE, expected ; at line 1, char 38"

원인: 쿼리에 잘못된 문법이 있음.

해결책:

오타나 잘못된 키워드가 있는지 쿼리 문법을 확인해요.
InfluxQL에서는 쿼리가 올바른 문법을 따르는지 확인해요:

   SELECT <field> FROM <measurement> WHERE <condition>

SQL에서는 쿼리가 InfluxDB 3.x가 지원하는 표준 SQL 문법을 사용하는지 확인해요. SQL 모드에서 InfluxQL 특화 문법(예: GROUP BY time())을 사용하는 것이 일반적인 문제예요. 지원 함수는 InfluxDB SQL reference 참고.
Flux에서는 올바른 파이프-포워드 문법과 함수 호출을 확인해요.
InfluxDB UI나 CLI로 쿼리를 직접 테스트해요.

쿼리 타임아웃 한도 초과

오류 메시지: "query-timeout limit exceeded"

원인: 쿼리가 InfluxDB의 구성된 타임아웃 한도보다 오래 걸림.

해결책:

쿼리의 시간 범위를 줄여요.
스캔되는 데이터를 제한하는 더 구체적인 필터를 추가해요.
관리자 접근이 있다면 InfluxDB의 쿼리 타임아웃 설정을 늘려요.
복잡성을 줄이도록 쿼리를 최적화해요.

너무 많은 시리즈 또는 데이터 포인트

오류 메시지: "max-series-per-database limit exceeded" 또는 "A query returned too many data points and the results have been truncated"

원인: 쿼리가 구성된 한도가 허용하는 것보다 많은 데이터를 반환함.

해결책:

쿼리의 시간 범위를 줄여요.
반환되는 시리즈 수를 제한하는 필터를 추가해요.
Advanced Database Settings의 데이터 소스 구성에서 Max series 설정을 늘려요.
데이터 포인트 수를 줄이는 집계 함수를 사용해요.
SQL에서는 $__dateBin(time)을 사용해 데이터를 시간 버킷으로 집계하고 카디널리티를 줄여요.
Flux에서는 aggregateWindow()를 사용해 데이터를 다운샘플링해요.

FlightSQL 오류 (SQL 쿼리 언어)

오류 메시지: "flightsql: " 접두사 뒤에 gRPC 오류 설명이 오는 메시지.

원인: SQL(FlightSQL) 백엔드가 InfluxDB 3.x와 통신 중 오류 발생.

가능한 원인과 해결책:

오류 코드	원인	해결책
`InvalidArgument`	SQL 쿼리 문법이 유효하지 않음	쿼리 문법 오류 확인
`PermissionDenied`	토큰이 요청한 리소스에 접근 권한 없음	토큰이 데이터베이스 읽기 권한이 있는지 확인
`NotFound`	요청한 테이블이나 데이터베이스가 없음	쿼리의 데이터베이스·테이블 이름 확인
`Unavailable`	InfluxDB 서버에 도달할 수 없음	InfluxDB 실행·URL 확인
`Unauthenticated`	토큰이 없거나, 유효하지 않거나, 만료됨	데이터 소스 구성의 토큰 업데이트

시간 열 없음

오류 메시지: "no time column found"

원인: 시계열 시각화에 필요한 시간 열이 쿼리 결과에 없음.

해결책:

쿼리에 시간 필드가 포함됐는지 확인해요.
Flux에서는 출력에 _time이 포함됐는지 확인해요.
SQL에서는 쿼리가 타임스탬프 열을 반환하는지 확인해요.
시간 필드가 필터링되거나 제외되지 않았는지 확인해요.

어노테이션 오류

다음 오류는 대시보드에서 InfluxDB 어노테이션을 사용할 때 발생해요.

"Query missing in annotation definition"

원인: 어노테이션 쿼리 필드가 비어 있음.

해결책:

업데이트할 대시보드로 이동해 Edit을 클릭해요.
Dashboard options 아이콘을 클릭해 사이드바를 열어요.
Annotations 섹션을 펼쳐요.
InfluxDB 어노테이션을 선택해요.
Open query editor를 클릭해 Annotation Query 대화 상자를 열어요.
InfluxQL Query 필드에 유효한 쿼리를 입력해요. 쿼리 WHERE $timeFilter를 포함해야 해요. 예:

   SELECT title, description FROM events WHERE $timeFilter ORDER BY time ASC

"Flux requires the standard annotation query"

원인: Flux 데이터 소스가 표준 Flux 쿼리 편집기 대신 레거시 InfluxQL 어노테이션 편집기를 사용함.

해결책:

기존 어노테이션 쿼리를 삭제해요.
새 어노테이션 쿼리를 만들고 Flux 구성 InfluxDB 데이터 소스를 선택해요.
time과 text 필드가 있는 데이터 프레임을 반환하는 Flux 쿼리를 작성해요. 예:

   from(bucket: "events")
     |> range(start: v.timeRangeStart, stop: v.timeRangeStop)
     |> filter(fn: (r) => r["_measurement"] == "deployments")

그래프에 어노테이션이 나타나지 않음

원인: 어노테이션은 구성됐지만 대시보드에 보이지 않음.

해결책:

Explore에서 테스트해 어노테이션 쿼리가 데이터를 반환하는지 확인해요.
대시보드 시간 범위가 어노테이션 이벤트 기간을 포함하는지 확인해요.
대시보드에서 어노테이션 토글이 활성화되어 있는지 확인해요(상단 메뉴 막대의 어노테이션 아이콘).
InfluxQL에서는 쿼리 WHERE $timeFilter가 포함됐는지 확인해요.
쿼리가 여러 열을 반환한다면 필드 매핑(Text, Tags, TimeEnd)이 올바르게 설정됐는지 확인해요.

알림 오류

다음 오류는 Grafana Alerting과 함께 InfluxDB 쿼리를 사용할 때 발생해요.

알림 규칙이 템플릿 변수 오류로 실패

원인: 알림 쿼리에 $hostname이나 $region 같은 템플릿 변수가 포함됨.

해결책:

알림 쿼리는 템플릿 변수를 사용할 수 없어요. Grafana는 대시보드 컨텍스트 없이 백엔드에서 알림 규칙을 평가하기 때문이에요. 템플릿 변수를 하드코딩된 값으로 바꿔요.

알림 규칙을 열어요.
$variable 참조를 리터럴 값으로 바꿔요.
알림 규칙을 저장해요.

대시보드 패널과 알림 규칙 양쪽에 같은 쿼리가 필요하다면 두 개의 별도 쿼리를 유지해요. 하나는 대시보드용 변수 쿼리, 하나는 알림용 하드코딩 값 쿼리.

알림 평가가 "no data" 반환

원인: 알림 쿼리가 Grafana가 평가할 수 있는 시계열 데이터를 반환하지 않음.

해결책:

먼저 Explore에서 쿼리를 테스트해 데이터를 반환하는지 확인해요.
InfluxQL에서는 쿼리가 GROUP BY time($__interval)과 함께 집계 함수(예: mean, sum, count)를 사용하는지 확인해요.
Flux에서는 aggregateWindow()를 사용해 시간 버킷 결과를 만들어요.
SQL에서는 $__dateBin(time) 또는 $__timeGroup(time)을 사용해 시간으로 집계해요.
알림 평가 시간 범위에 데이터가 포함되는지 확인해요. 알림은 대시보드 시간 선택기가 아닌 고정 시간 범위를 사용해요.
데이터 소스 설정에서 Save & test를 클릭해 데이터 소스 연결이 작동하는지 확인해요.

템플릿 변수 오류

다음 문제는 InfluxDB 쿼리에서 템플릿 변수를 사용할 때 발생해요.

변수 드롭다운이 오래되거나 과거 값을 표시

원인: SHOW TAG VALUES 같은 메타데이터 쿼리가 대시보드 시간 범위가 아닌 전체 보존 기간의 값을 반환함. 오래전에 보고를 멈춘 호스트나 센서도 드롭다운에 나타나요.

해결책:

변수 쿼리에 시간 조건을 추가해요. InfluxQL은 WHERE $timeFilter, SQL은 WHERE $__timeFilter(time).
변수의 Refresh 옵션을 On time range change로 설정해요.
예시는 Scope variables to the dashboard time range 참고.

다중 선택 변수가 쿼리를 깨뜨림

원인: 변수에 Multi-value 또는 Include all value 옵션이 활성화되면 Grafana가 선택 값을 (server1|server2) 같은 정규식 그룹으로 보간함. =로 비교하거나 변수를 정규식으로 감싸지 않는 쿼리는 실패하거나 데이터를 반환하지 않음.

해결책:

InfluxQL에서는 =~ 연산자를 사용하고 변수를 정규식으로 감싸요: "hostname" =~ /^$host$/.
SQL에서는 IN 연산자를 사용해요: host IN ($host).
동작 예시는 Choose a variable syntax 참고.

변수 값이 예기치 않게 이스케이프됨

원인: 변수가 multi-value이거나 정규식 안에서 사용될 때 Grafana가 변수 값의 특수 문자를 이스케이프함. 경로나 표현식 같은 특수 문자를 의도적으로 담은 커스텀 변수 값이 InfluxDB에 수정된 상태로 도착.

해결책:

${path:raw} 같은 raw 형식 옵션을 사용해 이스케이프 없이 리터럴 값을 보간해요. 자세한 내용은 Prevent unwanted value escaping 참고.

변수 드롭다운에 빈 또는 중복 항목 포함

원인: 변수 쿼리가 중복 값을 반환함. Grafana가 결과를 중복 제거하지만 플러그인 버전에 따라 중복이 드롭다운의 빈 항목으로 나타날 수 있어요.

해결책:

고유 값을 반환하도록 변수 쿼리를 업데이트해요. SQL에서는 SELECT DISTINCT 사용. InfluxQL SHOW 메타데이터 쿼리는 이미 고유 값을 반환하므로 보존 정책 간 중복을 확인해요.
또는 변수의 Regex 옵션을 사용해 결과를 필터링해요.

기타 일반적인 문제

다음 문제는 특정 오류 메시지를 생성하지 않지만 일상 사용 중 흔히 발생해요.

"Data source was not found"

증상:

대시보드 패널이 "data source was not found" 표시
패널 편집기에서 데이터 소스를 다시 선택하면 수동으로 쿼리 재실행이 동작

원인: 대시보드 패널이 이전 또는 삭제된 데이터 소스 UID를 참조함. 데이터 소스를 삭제·재생성하면 새 데이터 소스가 다른 UID를 받기 때문에 발생해요. 대시보드 스키마 마이그레이션도 잘못된 데이터 소스 참조를 남길 수 있으므로, 대시보드를 새 스키마 버전으로 마이그레이션한 후 패널을 확인하세요.

해결책:

InfluxDB 데이터 소스의 현재 UID를 찾아요. Connections > Data sources로 이동해 데이터 소스를 열고 페이지 URL에서 UID를 복사해요.
모든 오래된 참조를 한 번에 찾으려면 대시보드 설정에서 대시보드 JSON 모델을 열고 패널 오류 메시지에 표시된 UID를 검색해요.
각 영향을 받는 패널을 편집해 드롭다운에서 올바른 InfluxDB 데이터 소스를 다시 선택하거나, JSON 모델에서 오래된 UID를 바꾸고 대시보드를 저장해 참조를 수정해요.
이 문제를 피하려면 데이터 소스를 삭제·재생성하는 대신 기존 데이터 소스를 업데이트해요.

Telegraf 지표를 Grafana Cloud로 보낼 때 404 Not Found

오류 메시지: Telegraf가 Grafana Cloud InfluxDB 호환 엔드포인트에 쓸 때 "404 Not Found".

원인: Telegraf influxdb_v2 출력 플러그인이 Grafana Cloud 지표 엔드포인트와 호환되지 않음. PrivateLink나 표준 InfluxDB 호환 쓰기 엔드포인트를 사용할 때 흔히 발생.

해결책:

Telegraf 구성에서 출력 플러그인을 influxdb_v2에서 influxdb(v1)로 전환해요.
엔드포인트 URL과 자격 증명이 Grafana Cloud InfluxDB 구성 페이지에 표시된 것과 일치하는지 확인해요.
변경 후 Telegraf를 다시 시작해요.

빈 쿼리 결과

원인: 쿼리가 데이터를 반환하지 않음.

해결책:

시간 범위에 데이터베이스의 데이터가 포함되는지 확인해요.
measurement와 필드 이름이 올바른지 확인해요. SQL에서는 InfluxDB 3.x의 테이블 이름이 대소문자를 구분해요.
InfluxDB UI나 CLI에서 쿼리를 직접 테스트해요.
필터가 모든 데이터를 제외하지 않는지 확인해요.
SQL에서는 쿼리가 대시보드 시간 범위를 사용하도록 $__timeFilter(time) 매크로가 포함됐는지 확인해요.
InfluxQL에서는 보존 정책이 선택한 시간 범위의 데이터를 포함하는지 확인해요.

문자열로 저장된 숫자 값이 빈 패널 표시

증상:

쿼리가 결과를 반환하는데 시계열 패널에 데이터가 표시되지 않음
테이블 보기에는 값이 나타나지만 그래프로 그릴 수 없음

원인: InfluxDB는 필드가 처음 기록될 때 데이터 유형을 설정해요. 숫자 값이 문자열로 기록됐다면(예: line protocol에서 따옴표 처리) InfluxDB가 문자열로 반환하고 Grafana가 그래프로 그릴 수 없어요. 이는 Grafana가 아닌 InfluxDB의 데이터 문제예요.

해결책:

임시 해결책으로 패널에 Convert field type 변환을 추가하고 필드를 Number로 변환해요.
근본 원인을 고치려면 쓰기 시점에 데이터 유형을 수정해요. InfluxDB는 기존 필드의 유형을 바꿀 수 없으므로 새 필드나 measurement에 데이터를 써야 할 수 있어요.
이전 Grafana 버전에서는 Convert field type 변환이 null 값을 0으로 변환했어요. 현재 버전은 null 값을 보존해요. 변환 후 null이 0으로 표시된다면 Grafana를 업그레이드해요.

패널 값이 보기 모드와 편집 모드에서 다름

원인: Grafana가 시간 범위와 최대 데이터 포인트 수(패널 너비 기준)에서 쿼리 간격($__interval)을 계산해요. 편집 모드에서 렌더링된 패널은 대시보드 보기에서와 너비가 다르므로, time($__interval)으로 그룹화하는 쿼리가 다른 버킷 크기로 집계되어 다른 값을 표시할 수 있어요. 두 결과 모두 올바르며 다른 해상도로 집계된 것이에요.

해결책:

값을 일관되게 만들려면 패널 쿼리 옵션에서 고정 Min interval 또는 Max data points 값을 설정해요.
또는 GROUP BY time($__interval) 대신 GROUP BY time(1m) 같은 명시적 간격을 쿼리에서 사용해요.

범례 또는 툴팁 색상이 시리즈와 일치하지 않음

원인: 쿼리가 같은 이름을 가진 여러 시리즈를 반환함. 쿼리가 시리즈를 구분하는 태그로 그룹화하지 않거나, 별칭이 구분 정보를 숨길 때 흔히 발생. Grafana는 시리즈 이름으로 색상과 툴팁 값을 할당하므로 중복 이름이 범례와 호버 툴팁에 잘못된 색상이나 값을 표시하게 해요.

해결책:

각 시리즈를 고유하게 만드는 태그로 그룹화해요(예: GROUP BY "hostname").
ALIAS 필드에서 $tag_hostname 같은 별칭 패턴을 사용해 각 시리즈가 고유한 표시 이름을 갖게 해요. 자세한 내용은 Alias patterns 참고.
패널 인스펙터로 각 반환 시리즈가 고유한 이름을 갖는지 확인해요.

느린 쿼리 성능

원인: 쿼리 실행에 오랜 시간이 걸림.

해결책:

쿼리의 시간 범위를 줄여요.
스캔되는 데이터를 제한하는 더 구체적인 필터를 추가해요.
데이터 포인트 수를 줄이도록 Min time interval 설정을 늘려요.
InfluxDB 서버 성능과 리소스 사용률을 확인해요.
SQL에서는 집계 함수와 함께 $__dateBin(time)을 사용해 데이터를 다운샘플링하고, 쿼리 범위를 좁히는 WHERE 절을 추가해요.
Flux에서는 시각화 전에 aggregateWindow()를 사용해 데이터를 다운샘플링해요.
데이터를 사전 집계하는 지속 쿼리나 태스크 사용을 고려해요.

InfluxDB가 Grafana로부터 높은 쿼리 볼륨을 받음

증상:

InfluxDB 서버에 예기치 않은 쿼리 부하
트래픽이 Grafana에서 발생하는지 확실하지 않음

원인: 대시보드의 모든 패널은 대시보드가 새로고침될 때마다 InfluxDB로 쿼리를 보내요. 쿼리 볼륨은 패널 수, 패널당 쿼리 수, 새로고침 간격, 동시 조회 인원 수에 따라 확장돼요. 예를 들어 20개 패널이 10초마다 새로고침되는 대시보드는 뷰어마다 분당 최소 120개 쿼리를 생성해요.

해결책:

대시보드 새로고침 간격을 늘리거나 필요하지 않은 곳에서 자동 새로고침을 꺼요.
대시보드당 패널과 쿼리 수를 줄여요.
각 쿼리의 해상도를 줄이도록 Min time interval 설정을 늘려요.
Grafana Enterprise와 Grafana Cloud에서는 query caching을 활성화해 캐시 창 내의 동일한 쿼리를 InfluxDB에 닿지 않고 캐시에서 제공해요.
트래픽이 Grafana Cloud 인스턴스에서 발생하는지 확인하려면 소스 IP 주소를 Grafana Cloud allowlist와 비교해요.

데이터가 지연되거나 최근 포인트 누락

원인: 시각화가 가장 최근 데이터를 표시하지 않음.

해결책:

대시보드 시간 범위와 새로고침 설정을 확인해요.
Min time interval이 너무 높게 설정되지 않았는지 확인해요.
InfluxDB가 데이터 쓰기를 완료했는지 확인해요.
Grafana와 InfluxDB 사이의 시계 동기화 문제를 확인해요.

디버그 로깅 활성화

주의: 13.1.0보다 이전 InfluxDB 플러그인 버전은 기본 로그 레벨에서 API 토큰을 Grafana 서버 로그에 일반 텍스트로 기록할 수 있었어요. 로그로 문제 해결하기 전에 플러그인 버전 13.1.0 이상으로 업그레이드하세요. 로그 파일을 민감한 것으로 취급하고 노출됐을 수 있는 토큰을 교체하세요.

문제 해결을 위한 상세 오류 정보를 캡처하려면:

구성 파일에서 Grafana 로그 레벨을 debug로 설정해요:

[log]
level = debug

/var/log/grafana/grafana.log(또는 설정한 로그 위치)에서 로그를 검토해요.
요청·응답 세부 정보를 포함한 InfluxDB 특정 항목을 찾아요.
문제 해결 후 과도한 로그 양을 피하려면 로그 레벨을 info로 재설정해요.

추가 도움말

이 가이드의 해결책을 시도했는데도 문제가 계속되면:

API별 지침은 InfluxDB 문서를 확인해요.
Grafana 커뮤니티 포럼에서 유사한 이슈를 검토해요.
알려진 버그는 GitHub의 InfluxDB 데이터 소스 이슈를 검토해요.
Enterprise, Cloud Pro, Cloud Contracted 사용자라면 Grafana Support에 문의해요.
이슈를 보고할 때 다음을 포함해요:
- Grafana 버전
- Administration > Plugins 페이지에서 확인한 InfluxDB 데이터 소스 플러그인 버전
- InfluxDB 버전과 제품(OSS, Cloud, Enterprise)
- 쿼리 언어(Flux, InfluxQL, SQL)
- 오류 메시지(민감 정보 편집)
- 재현 단계
- 데이터 소스 설정, HTTP 메서드, TLS 설정 같은 관련 구성(토큰, 비밀번호 등 자격 증명 편집)

더 알아보기 (Learn more)

Configure the InfluxDB data source - 데이터 소스 구성
InfluxDB query editor - 쿼리 편집기
InfluxDB template variables - 템플릿 변수
InfluxDB documentation - InfluxDB 공식 문서
Troubleshoot InfluxDB data source issues - 원문 문서