Microsoft SQL Server 데이터 소스 문제 해결

이 문서는 Grafana에서 Microsoft SQL Server(MSSQL) 데이터 소스를 구성하거나 사용할 때 겪을 수 있는 일반적인 문제에 대한 해결책을 제공해요. 구성, 연결, PDC, 인증, 쿼리, 성능, 알림, 템플릿 변수 순서로 진단해 보세요.

출처: Troubleshoot Microsoft SQL Server data source issues

본문

구성 오류

이 오류는 Grafana에서 데이터 소스 구성을 설정하거나 접근할 때 발생해요.

구성 양식이 표시되지 않음

증상: 데이터 소스 설정 페이지에 구성 필드 없이 Delete와 Back 버튼만 표시됨.

원인: 로그인한 사용자에게 데이터 소스를 구성할 충분한 권한이 없음. Organization administrator 역할(또는 datasources:write 권한이 있는 커스텀 RBAC 역할)이 있는 사용자만 데이터 소스 구성 양식에 접근할 수 있어요.

해결책:

조직 관리자에게 Organization administrator 역할을 부여해 달라고 하거나, 데이터 소스 쓰기 권한이 있는 커스텀 RBAC 역할을 할당해 달라고 요청해요.
또는 관리자에게 대신 데이터 소스를 구성해 달라고 하거나 프로비저닝으로 YAML에 데이터 소스를 정의해요.

연결 오류

이 오류는 Grafana가 Microsoft SQL Server에 연결을 설정하거나 유지하지 못할 때 발생해요.

서버에 연결할 수 없음

오류 메시지: Unable to open tcp connection 또는 dial tcp: connection refused

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

해결책:

SQL Server가 실행 중이고 접근 가능한지 확인해요.
데이터 소스 구성의 호스트와 포트가 올바른지 확인해요. 기본 SQL Server 포트는 1433.
Grafana와 SQL Server 사이의 연결을 차단하는 방화벽 규칙이 없는지 확인해요.
SQL Server가 원격 연결을 허용하도록 구성되어 있는지 확인해요.
Grafana Cloud라면 SQL Server 인스턴스가 공개적으로 접근 불가한 경우 Private data source connect를 구성했는지 확인해요.

연결 타임아웃

오류 메시지: "Connection timed out" 또는 "I/O timeout"

원인: 응답을 받기 전에 SQL Server 연결이 타임아웃됨.

해결책:

Grafana와 SQL Server 사이의 네트워크 지연을 확인해요.
SQL Server가 과부하되거나 성능 문제를 겪지 않는지 확인해요.
Additional settings 아래의 데이터 소스 구성에서 Connection timeout 설정을 늘려요.
네트워크 장치(로드 밸런서, 프록시)가 연결을 타임아웃시키는지 확인해요.

암호화 관련 연결 실패

오류 메시지: "TLS handshake failed" 또는 "certificate verify failed"

원인: Grafana의 암호화 설정과 SQL Server가 지원하거나 요구하는 것 사이에 불일치가 있음.

해결책:

구버전 SQL Server(2008, 2008R2)에서는 데이터 소스 구성에서 Encrypt 옵션을 Disable 또는 False로 설정해요.
Encrypt가 True라면 SQL Server가 유효한 TLS 인증서를 갖고 있는지 확인해요.
인증서가 Grafana 서버에서 신뢰되는지(시스템 CA 번들이나 TLS/SSL Root Certificate에 지정) 확인해요.
인증서의 호스트 이름이 구성된 Host 값과 일치하지 않으면(예: 로드 밸런서나 PDC 사용 시) Hostname in server certificate을 인증서의 CN 또는 SAN과 일치하도록 설정해요.
테스트용 임시 임시 해결책으로 Skip TLS Verify를 활성화해요(프로덕션에는 권장하지 않음).
최적의 호환성을 위해 SQL Server 버전의 최신 서비스 팩을 사용하는지 확인해요.

FIPS 활성 Grafana에서 TLS 핸드셰이크 실패

오류 메시지: "TLS handshake failed" 또는 "no cipher suite supported by both client and server"

원인: BoringCrypto(FIPS 준수 빌드)를 사용하는 Grafana 빌드는 FIPS 140-3 암호화 요구 사항을 적용해요. 구버전 암호화 제품군(TLS 1.0, RC4, 3DES)만 지원하는 SQL Server 인스턴스는 이러한 빌드와 호환되지 않아요.

해결책:

SQL Server 인스턴스를 FIPS 승인 암호화 제품군(AES 기반)으로 TLS 1.2를 지원하도록 업그레이드해요.
SQL Server 호스트에서 Windows 레지스트리 또는 SQL Server Network Configuration에서 TLS 1.2가 활성화되어 있는지 확인해요.
SQL Server를 업그레이드할 수 없다면 비-FIPS Grafana 빌드를 사용해요.
SQL Server 오류 로그에서 "TLS handshake" 항목을 확인해 어떤 TLS 버전을 지원하는지 확인해요.

PDC 통한 TLS 인증서 오류

오류 메시지: Private data source connect로 연결할 때 "certificate verify failed" 또는 "x509: certificate signed by unknown authority"

원인: SQL Server의 TLS 인증서는 Grafana Cloud가 아닌 PDC 에이전트의 관점에서 검증 가능해야 해요. SQL Server가 프라이빗 CA 인증서를 사용하면 PDC 에이전트 호스트가 그 CA를 신뢰해야 해요.

해결책:

PDC 에이전트 호스트의 시스템 신뢰 저장소에 프라이빗 CA 인증서를 설치해요.
또는 데이터 소스의 TLS/SSL Root Certificate 필드에 CA 인증서 경로를 지정해요(경로는 Grafana Cloud가 아닌 PDC 에이전트에서 접근 가능해야 해요).
인증서의 호스트 이름이 PDC 에이전트가 보는 것과 일치하지 않으면 Hostname in server certificate을 올바른 값으로 설정해요.
PDC 에이전트 호스트에서 인증서가 유효한지(만료되지 않았는지) 확인해요: openssl s_client -connect <SQL_SERVER_HOST>:1433 -starttls mssql.

명명된 인스턴스 연결 문제

오류 메시지: "Cannot connect to named instance" 또는 인스턴스 이름 사용 시 연결 실패

원인: Grafana가 SQL Server 명명된 인스턴스를 해석할 수 없음.

해결책:

Host 필드에서 hostname\instancename 또는 hostname\instancename,port 형식을 사용해요.
SQL Server 머신에서 SQL Server Browser 서비스가 실행 중인지 확인해요.
Browser 서비스를 사용할 수 없으면 포트 번호를 직접 지정해요: hostname,port.
SQL Server Browser 서비스를 사용한다면 UDP 포트 1434가 열려 있는지 확인해요.

Private data source connect (PDC) 오류

이 오류는 Grafana Cloud에서 Private data source connect로 온프레미스 또는 프라이빗 네트워크 SQL Server에 도달할 때 발생해요.

PDC로 연결 시 "no such host"

오류 메시지: dial tcp: lookup sqlserver.internal.example.com: no such host

원인: PDC 에이전트가 자체 네트워크에서 SQL Server 호스트 이름을 해석할 수 없음. 흔한 경우:

데이터 소스 구성의 호스트 이름이 프라이빗 네트워크 안에서 해석되지 않는 공개 DNS 이름
PDC 에이전트 호스트가 내부 DNS 서버에 접근하지 못함
클러스터 또는 Availability Group Listener DNS 항목이 잘못 구성됨

해결책:

데이터 소스 Host 필드에서 PDC 에이전트 네트워크에서 해석 가능한 호스트 이름(예: 내부 FQDN이나 IP 주소, 공개 DNS 이름 아님)을 사용해요.
PDC 에이전트 호스트가 호스트 이름을 해석할 수 있는지 확인해요: 에이전트 머신에서 nslookup <SQL_SERVER_HOST> 실행.
클러스터나 Availability Group Listener를 사용한다면 Listener DNS 레코드가 존재하고 에이전트 네트워크에서 올바른 IP로 해석되는지 확인해요.
PDC 에이전트 호스트에 올바른 DNS 서버가 구성되어 있는지 확인해요.

유지보수 또는 IP 변경 후 PDC 연결 중단

원인: 인프라 유지보수 후 PDC SSH 터널 엔드포인트 IP가 변경되어 기존 연결이 끊김.

해결책:

PDC 에이전트 서비스를 다시 시작해 업데이트된 엔드포인트로 SSH 터널을 재설정해요.
Grafana Cloud 스택의 Connections > Private data source connect에서 PDC 에이전트 상태가 정상 연결로 표시되는지 확인해요.
네트워크가 아웃바운드 트래픽에 IP 기반 방화벽 규칙을 사용한다면 허용 목록을 업데이트해요. PDC 엔드포인트 IP는 유지보수 기간 중 변경될 수 있어요.
가능하면 IP 기반 규칙 대신 DNS 기반 허용 목록을 사용해 앞으로의 중단을 피해요.

PDC 활성화 시 자격 증명이 유지되지 않음

원인: 알려진 문제로 PDC가 활성화되면 데이터 소스 사용자 이름이 유지되지 않을 수 있음.

해결책:

PDC를 활성화한 후 먼저 데이터 소스 구성을 저장하고, 사용자 이름과 비밀번호를 다시 입력한 뒤 다시 저장해요.
Save & test를 클릭해 자격 증명이 저장되고 연결이 성공하는지 확인해요.
문제가 계속되면 PDC를 비활성화하고 자격 증명을 저장한 다음 PDC를 다시 활성화해 보세요.

Grafana Cloud에서 프라이빗 SQL Server에 연결할 수 없음

원인: PDC를 구성하지 않고 Grafana Cloud에서 온프레미스 또는 프라이빗 네트워크 SQL Server에 연결을 시도함.

해결책:

Grafana Cloud는 공개적으로 접근할 수 없는 모든 SQL Server에 Private data source connect (PDC)가 필요해요.
Grafana Cloud 데이터 소스 연결은 고정 IP 주소를 사용하지 않으므로 방화벽 허용 목록만으로는 작동하지 않아요.
포트 1433에서 SQL Server에 도달할 수 있는 프라이빗 네트워크의 호스트에 PDC 에이전트를 설치·구성해요.
PDC 에이전트 호스트가 Grafana Cloud PDC 엔드포인트에 포트 22로 아웃바운드 연결을 허용하는지 확인해요.

설정 지침은 Grafana Cloud에서 온프레미스 SQL Server 연결을 참고하세요.

인증 오류

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

사용자 로그인 실패

오류 메시지: "Login failed for user 'username'" 또는 "Authentication failed"

원인: 인증 자격 증명이 유효하지 않거나 사용자에게 데이터베이스 접근 권한이 없음.

해결책:

사용자 이름과 비밀번호가 올바른지 확인해요.
사용자가 SQL Server에 존재하고 활성화되어 있는지 확인해요.
사용자가 지정된 데이터베이스에 접근 권한이 있는지 확인해요.
Windows 인증에서는 자격 증명이 올바른 형식(DOMAIN\User)인지 확인해요.
SQL Server 인증 모드가 사용 중인 로그인 유형(SQL Server Authentication, Windows Authentication 또는 Mixed Mode)을 허용하는지 확인해요.

로그인 실패 - ``(빈 사용자 이름)

오류 메시지: "Login failed for user ''". Grafana가 SQL Server에 연결할 때 저장된 사용자 이름이 비어 보임.

원인: 특정 Grafana 릴리스 채널의 알려진 문제로 SQL Server Authentication 사용자 이름이 UI에는 저장된 것으로 보이지만 연결 시 서버에 빈 문자열을 보냄. "fast" 릴리스 채널에서 확인됨.

해결책:

이 문제가 발생하면 "fast"에 있는 경우 "steady" 릴리스 채널로 전환해요.
업그레이드하거나 채널을 전환한 후 데이터 소스 구성을 열고 사용자 이름과 비밀번호를 다시 입력한 뒤 Save & test를 클릭해 자격 증명이 올바르게 저장되는지 확인해요.
다시 저장한 후에도 문제가 계속되면 브라우저 캐시를 지우고 다시 시도해요.

비밀번호에 특수 문자가 포함되면 연결 실패

오류 메시지: 자격 증명에 세미콜론(;)이나 닫는 중괄호(})가 포함될 때 "Login failed for user" 또는 "Connection string parse error"

원인: v13.0 이전 Grafana 버전에서는 사용자 이름이나 비밀번호의 세미콜론과 닫는 중괄호가 MSSQL 연결 문자열에서 제대로 이스케이프되지 않아 인증 실패를 일으켰음.

해결책:

이러한 특수 문자를 올바르게 처리하는 Grafana v13.0 이상으로 업그레이드해요.
업그레이드할 수 없다면 ;와 } 문자를 피하도록 SQL Server 비밀번호를 변경해요.

데이터베이스 접근 거부

오류 메시지: Cannot open database 'dbname' requested by the login

원인: 인증된 사용자에게 지정된 데이터베이스에 접근할 권한이 없음.

해결책:

데이터 소스 구성의 데이터베이스 이름이 올바른지 확인해요.
사용자가 적절한 권한으로 데이터베이스에 매핑되어 있는지 확인해요.
필요한 테이블에 최소한 SELECT 권한을 부여해요:

USE [your_database]
GRANT SELECT ON dbo.YourTable TO [your_user]

사용자에게 public 역할의 충돌하는 권한이 없는지 확인해요.

Windows Authentication (Kerberos) 문제

오류 메시지: "Kerberos authentication failed" 또는 "Cannot initialize Kerberos"

원인: Kerberos 구성이 잘못되었거나 불완전함.

해결책:

데이터 소스 설정에서 Kerberos 구성 파일(krb5.conf) 경로가 올바른지 확인해요. 기본 경로는 /etc/krb5.conf.
keytab 인증에서는 keytab 파일이 존재하고 Grafana 서비스 계정이 읽을 수 있는지 확인해요.
Kerberos 구성에서 realm과 KDC 설정이 올바른지 확인해요.
DNS가 KDC 서버를 올바르게 해석하는지 확인해요.
SQL Server 인스턴스에 서비스 주체 이름(SPN)이 등록되어 있는지 확인해요.

참고: Kerberos 인증은 Grafana Cloud에서 지원되지 않아요. 대신 SQL Server Authentication 또는 Azure Entra ID를 사용하세요.

Availability Group Listener와 `KDC_ERR_C_PRINCIPAL_UNKNOWN`

오류 메시지: SQL Server Availability Group Listener로 연결할 때 "KDC_ERR_C_PRINCIPAL_UNKNOWN"

원인: SQL Server 인스턴스에 등록된 SPN이 Availability Group Listener의 DNS 이름과 일치하지 않음. Kerberos 인증은 클라이언트가 연결하는 호스트 이름과 일치하는 SPN이 필요해요.

해결책:

Availability Group Listener DNS 이름에 대한 SPN을 등록해요:

setspn -S MSSQLSvc/<LISTENER_FQDN>:1433 <DOMAIN>\<SERVICE_ACCOUNT>
setspn -S MSSQLSvc/<LISTENER_FQDN> <DOMAIN>\<SERVICE_ACCOUNT>

SPN이 올바르게 등록됐는지 확인해요: setspn -L <DOMAIN>\<SERVICE_ACCOUNT>.
krb5.conf에 Listener의 도메인에 대한 올바른 realm 매핑이 포함되는지 확인해요.
여러 realm을 사용한다면 krb5.conf에 cross-realm 신뢰 항목을 추가해요.

Windows 인증의 신뢰되지 않은 도메인 오류

오류 메시지: "The login is from an untrusted domain and cannot be used with Windows authentication"

원인: Grafana 서버의 도메인이 SQL Server의 도메인과 신뢰 관계가 없거나, Kerberos realm 구성이 도메인 간에 올바르게 매핑되지 않음.

해결책:

Grafana 서버의 도메인과 SQL Server의 도메인 사이에 신뢰 관계가 존재하는지 확인해요.
krb5.conf에 두 도메인 모두에 대한 realm 매핑이 포함되는지 확인해요:

[realms]
DOMAIN_A.COM = {
  kdc = kdc1.domain_a.com
}
DOMAIN_B.COM = {
  kdc = kdc1.domain_b.com
}

[domain_realm]
.domain_a.com = DOMAIN_A.COM
.domain_b.com = DOMAIN_B.COM

크로스 도메인 접근이 필요하다면 SQL Server 서비스 계정에 위임 권한이 있는지 확인해요.
대안으로 도메인 신뢰가 필요 없는 SQL Server Authentication 또는 Azure Entra ID (App Registration)을 사용해요.

Azure Entra ID 인증 오류

오류 메시지: "AADSTS error codes" 또는 "Azure AD authentication failed"

원인: Azure Entra ID(이전 Azure AD) 인증이 잘못 구성됨.

해결책:

App Registration 인증의 경우:
- 테넌트 ID, 클라이언트 ID, 클라이언트 시크릿이 올바른지 확인해요.
- 앱 등록이 Azure SQL 데이터베이스의 사용자로 추가됐는지 확인해요.
- 클라이언트 시크릿이 만료되지 않았는지 확인해요.
Managed Identity 인증의 경우:
- Grafana 서버 구성에 managed_identity_enabled = true가 설정되어 있는지 확인해요.
- 관리 ID가 Azure SQL 데이터베이스에 추가됐는지 확인해요.
- Grafana를 호스팅하는 Azure 리소스에 관리 ID가 활성화되어 있는지 확인해요.
Current User 인증의 경우:
- Grafana 서버 구성에 user_identity_enabled = true가 설정되어 있는지 확인해요.
- 앱 등록이 Access Tokens와 ID Tokens를 모두 발급하도록 구성됐는지 확인해요.
- 필요한 API 권한(user_impersonation for Azure SQL)이 구성됐는지 확인해요.

자세한 Azure 인증 구성은 Microsoft SQL Server 데이터 소스 구성을 참고하세요.

쿼리 오류

이 오류는 쿼리 문법 또는 구성에 문제가 있을 때 발생해요.

시간 열을 찾을 수 없거나 유효하지 않음

오류 메시지: "Could not find time column" 또는 time series 시각화에 데이터가 표시되지 않음

원인: 쿼리가 time series 시각화에 제대로 서식된 time 열을 반환하지 않음.

해결책:

Time series 형식을 사용할 때 쿼리에 time 이름의 열이 포함되는지 확인해요.
$__time() 매크로로 날짜 열 이름을 바꿔요: $__time(your_date_column).
시간 열이 유효한 SQL 날짜/시간 유형(datetime, datetime2, date)이거나 Unix epoch 값을 포함하는지 확인해요.
ORDER BY로 결과 집합이 시간 열로 정렬되는지 확인해요.

매크로 확장 오류

오류 메시지: "Error parsing query" 또는 매크로가 쿼리에 확장되지 않은 채로 보임

원인: Grafana 매크로가 올바르지 않게 사용됨.

해결책:

매크로 문법을 확인해요: $_timeFilter(column)이 아닌 $__timeFilter(column) 사용.
매크로는 저장 프로시저 내부에서 동작하지 않아요. 명시적 날짜 매개변수를 사용해요.
매크로에 전달되는 열 이름이 테이블에 존재하는지 확인해요.
쿼리 실행 후 Generated SQL을 클릭해 확장된 쿼리를 보고 매크로 확장을 디버깅해요.

시간대 및 시간 이동 문제

원인: 시계열 데이터가 이동된 것처럼 보이거나 예상 시간과 정렬되지 않음.

해결책:

시간대 문제를 피하려면 데이터베이스에 타임스탬프를 UTC로 저장해요.
시간 매크로($__time, $__timeFilter 등)는 항상 UTC 값으로 확장돼요.
타임스탬프가 로컬 시간으로 저장돼 있다면 쿼리에서 UTC로 변환해요:

SELECT
  your_datetime_column AT TIME ZONE 'Your Local Timezone' AT TIME ZONE 'UTC' AS time,
  value
FROM your_table

시간 매크로에 시간대 매개변수를 전달하지 마세요. 지원되지 않아요.

쿼리가 너무 많은 행을 반환

오류 메시지: "Result set too large" 또는 브라우저가 응답하지 않음

원인: 쿼리가 효율적으로 처리할 수 있는 것보다 더 많은 데이터를 반환함.

해결책:

데이터를 대시보드 시간 범위로 제한하려면 $__timeFilter(column)으로 시간 필터를 추가해요.
원시 행을 반환하는 대신 GROUP BY와 함께 집계(AVG, SUM, COUNT)를 사용해요.
결과를 제한하는 TOP 절을 추가해요: SELECT TOP 1000 ....
데이터를 시간 간격으로 집계하려면 $__timeGroup() 매크로를 사용해요.

저장 프로시저가 데이터를 반환하지 않음

원인: 저장 프로시저 출력이 올바르게 캡처되지 않음.

해결책:

저장 프로시저가 변수 할당만이 아닌 SELECT 문을 사용하는지 확인해요.
SET NOCOUNT ON이 있다면 제거하거나 뒤에 SELECT 문이 오는지 확인해요.
저장 프로시저 매개변수가 올바르게 전달되는지 확인해요.
동일한 매개변수로 SQL Server Management Studio에서 저장 프로시저를 직접 테스트해요.

저장 프로시저 사용에 대한 자세한 내용은 쿼리 편집기 문서를 참고하세요.

성능 문제

이 문제는 느린 쿼리나 높은 리소스 사용과 관련돼요.

느린 쿼리 실행

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

해결책:

데이터 볼륨을 제한하도록 대시보드 시간 범위를 줄여요.
WHERE 절과 시간 필터에 사용되는 열에 인덱스를 추가해요.
개별 행을 반환하는 대신 집계를 사용해요.
데이터 포인트 수를 줄이도록 Min time interval 설정을 늘려요.
SQL Server Management Studio에서 쿼리 실행 계획을 검토해 병목을 식별해요.

연결 풀 고갈

오류 메시지: "Too many connections", "Connection pool exhausted" 또는 "failed to connect to server"

원인: 데이터베이스에 대한 동시 연결이 너무 많음. 알림 평가와 대시보드 쿼리가 같은 풀에서 연결을 두고 경쟁하므로, 이는 대시보드는 계속 작동하는데 알림이 간헐적으로 실패하는 것으로 나타나는 경우가 흔함.

해결책:

데이터 소스 구성에서 Max open 연결 한도를 늘려요. 50에서 100 값은 동시 대시보드와 알림이 있는 대부분의 배포를 처리해요.
유휴 연결을 자동 관리하려면 Auto max idle을 활성화해요.
오래된 연결이 재활용되도록 Max lifetime을 14400(4시간)으로 설정해요.
동시에 같은 데이터 소스를 질의하는 패널 수를 줄이거나, 무거운 대시보드를 여러 페이지로 나눠요.
연결을 잡고 있을 수 있는 장기 실행 쿼리가 있는지 확인해요(SQL Server의 sys.dm_exec_sessions 검토).
대시보드는 작동하는데 알림이 간헐적으로 실패하면 동시 부하에서 연결 풀 고갈의 강력한 신호예요.

읽기 전용 복제본이 있는 느린 대시보드 로드

증상: 대시보드 로드가 처음에 5~6분 걸리거나, 쿼리가 예상보다 크게 느림.

원인: 데이터 소스가 Host 필드에 ApplicationIntent=ReadOnly로 구성되어 모든 쿼리를 읽기 전용 보조 복제본으로 라우팅함. 복제본이 충분하지 않거나, 인덱스가 부족하거나, 복제 지연이 있으면 쿼리가 기본보다 훨씬 느림.

해결책:

호스트 필드에서 ApplicationIntent=ReadOnly를 제거해 쿼리를 기본 인스턴스로 다시 라우팅해요.
읽기 전용 복제본을 사용해야 한다면 기본과 동일한 인덱스와 리소스를 갖는지 확인해요.
느린 기간에 복제본의 복제 지연과 리소스 사용률(CPU, I/O)을 확인해요.
복제본 쿼리용 별도 데이터 소스를 만들고 저지연이 필요하지 않은 특정 대시보드에만 사용하는 것을 고려해요.

알림 오류

이 오류는 Grafana Alerting에서 Microsoft SQL Server 쿼리를 사용할 때 발생해요.

대시보드는 작동하는데 알림이 간헐적으로 실패

원인: 연결 풀 고갈. 알림 평가와 대시보드 쿼리가 같은 연결 풀을 공유함. 동시 부하에서 알림 평가는 빈 연결을 기다리다 타임아웃될 수 있음.

해결책: 위 성능 문제 섹션의 Connection pool exhaustion을 참고하세요.

알림 쿼리가 데이터를 반환하지 않음

원인: 알림 쿼리는 대시보드 쿼리와 다른 요구 사항이 있음.

해결책:

쿼리 형식이 Time series로 설정되어 있는지 확인해요(Table 형식은 알림에 지원되지 않음).
쿼리가 템플릿 변수를 사용하지 않는지 확인해요(알림 쿼리는 대시보드 변수를 해석할 수 없음).
쿼리가 알림 평가 시간 범위 내에서 데이터를 반환하는지 확인해요.
고정 시간 범위로 Explore에서 쿼리를 테스트해 결과를 반환하는지 확인해요.

자세한 내용은 Microsoft SQL Server 알림을 참고하세요.

템플릿 변수 오류

이 오류는 쿼리에서 템플릿 변수를 사용할 때 발생해요.

템플릿 변수 쿼리 실패

원인: 변수 쿼리가 예기치 않은 결과나 오류를 반환함.

해결책:

변수 쿼리 문법이 단일 열을 반환하는 유효한 SQL인지 확인해요.
데이터 소스 연결이 작동하는지 확인해요.
사용자가 변수 쿼리에서 참조하는 테이블에 접근 권한이 있는지 확인해요.
변수 쿼리로 사용하기 전에 쿼리 편집기에서 쿼리를 테스트해요.

multi-value 변수로 이중 따옴표가 쿼리를 깨뜨림

원인: Grafana v11.3부터 IN과 함께 사용되는 multi-value 변수는 자동으로 따옴표 처리됨. 변수를 수동으로 따옴표로 감쌌다면(예: WHERE col IN ('${var}')) 값이 이제 이중 따옴표(''value'')가 되어 쿼리 실패를 일으킴.

해결책:

변수 주변의 수동 따옴표를 제거해요: WHERE col IN ('${var}') 대신 WHERE col IN ($var) 사용.
단일 값 비교에는 sqlstring 형식을 사용해요: WHERE col = ${var:sqlstring}.
서식 옵션은 Template variables 참고.

기타 일반적인 문제

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

시스템 데이터베이스가 쿼리에 나타남

원인: 쿼리가 실수로 시스템 데이터베이스에 접근함.

해결책:

쿼리 편집기가 데이터베이스 드롭다운에서 tempdb, model, msdb, master를 자동으로 제외해요.
접근을 제한하려면 데이터 소스 구성에서 항상 데이터베이스를 지정해요.
데이터베이스 사용자가 의도한 데이터베이스에만 권한을 갖는지 확인해요.

데이터가 잘못되거나 정렬이 어긋남

원인: 데이터 서식 또는 유형 변환 문제.

해결책:

일관된 이름을 보장하려면 명시적 열 별칭을 사용해요: SELECT value AS metric.
숫자 열이 문자열이 아닌 실제 숫자 유형인지 확인해요.
집계에 영향을 줄 수 있는 NULL 값이 있는지 확인해요.
누락된 데이터 포인트를 처리하려면 $__timeGroup() 매크로의 FILL 옵션을 사용해요.

추가 도움말

이 문제 해결 가이드를 따른 후에도 문제가 계속되면:

Grafana 커뮤니티 포럼에서 유사한 이슈를 확인해요.
알려진 버그는 Grafana GitHub 이슈를 검토해요.
상세 오류 정보를 캡처하려면 Grafana에서 디버그 로깅을 활성화해요.
추가 오류 세부 정보를 위해 SQL Server 로그를 확인해요.
Enterprise 또는 Cloud 고객이라면 Grafana Support에 문의해요.

이슈를 보고할 때 다음을 포함해요:

Grafana 버전
Administration > Plugins 페이지에서 확인한 Microsoft SQL Server 데이터 소스 플러그인 버전. 플러그인은 Grafana 릴리스와 무관하게 업데이트돼요.
SQL Server 버전
오류 메시지(민감 정보 편집)
재현 단계
관련 쿼리 예시(민감 데이터 편집)

더 알아보기 (Learn more)

Configure the Microsoft SQL Server data source - 데이터 소스 구성
MSSQL query editor - 쿼리 편집기
MSSQL alerting - 알림
MSSQL template variables - 템플릿 변수
Troubleshoot Microsoft SQL Server data source issues - 원문 문서

Microsoft SQL Server 데이터 소스 문제 해결