SQL Server용 DBM 설정 문제 해결

원문 보기 위키 갱신 2026.10.05

이 페이지는 SQL Server로 Database Monitoring을 설정하고 사용할 때 흔히 겪는 문제와 해결 방법을 다뤄요. Datadog는 최신 안정 Agent 버전을 유지하고 최신 설정 문서를 따를 것을 권장해요. Agent 버전 출시에 따라 문서가 바뀔 수 있기 때문이에요.

출처: 문서

본문

흔한 연결 문제 진단

Agent가 SQL Server 인스턴스에 연결하는 방법은 두 가지예요:

Windows 인증 (Windows 호스트에서만 사용 가능)
SQL Server 인증

Windows 인증은 기본 인증 모드이고 SQL Server 인증보다 더 안전해요. Windows 인증을 사용하면 도메인 수준에서 Windows 그룹을 만들고 그룹 전체에 대해 SQL Server에 로그인을 만들 수 있어요. Windows 인증을 사용하려면:

Agent 설치 시 생성된 서비스 계정을 사용하고, 이 계정이 SQL Server에 적절한 접근 권한이 있는지 확인하세요.
connection_string: "Trusted_Connection=yes"를 설정하고 username과 password 필드는 생략하세요. Trusted_Connection=yes 연결 속성은 OLE DB Driver for SQL Server가 로그인 검증에 Windows 인증을 사용하도록 지시해요.

SQL Server 인증은 Windows 사용자 계정에 기반하지 않고 인스턴스에서 생성되어 SQL Server 자체에 저장돼요. SQL 인증은 연결하려면 SQL Server 인스턴스 설정에 username과 password를 설정해야 해요.

연결 시 로그인 오류가 발생한다면 먼저 datadog Agent 사용자로 인스턴스에 로그인할 수 있는지 확인하는 게 중요해요. 이를 확인하는 쉬운 방법은 sqlcmd 같은 명령줄 유틸리티를 사용하는 거예요.

예:

# this example uses SQL Authentication
sqlcmd -S <INSTANCE_ENDPOINT> -U datadog -P <DATADOG_PASSWORD> -d master

# this example uses Windows Authentication
# Run this command in powershell via selecting the `run as user...` option to run as the ddagentuser
sqlcmd -S <INSTANCE_ENDPOINT> -d master -E

datadog 사용자가 SQL Server 인스턴스에 로그인할 수 없다면 설정 문서에 따라 사용자가 생성되고 적절한 권한이 부여되었는지 확인하세요. Windows 인증은 Agent가 Agent와 같은 호스트에서 실행 중인 SQL Server 인스턴스에 연결할 때 지원돼요.

Microsoft는 이런 유형의 오류 문제 해결에 도움이 되는 문서도 제공하며 여기에서 확인할 수 있어요.

SQL Server TCP 연결 오류

TCP 연결 문제는 Agent 설정이 잘못 구성되었을 때 흔히 발생해요. 드라이버가 제공하는 오류 메시지가 항상 명확한 것은 아니에요.

예를 들어 다음 오류는 TCP 연결이 실패했기 때문이에요:

TCP-connection(ERROR: getaddrinfo failed). Exception: unable to connect: could not open database requested by login

흔한 오류 몇 가지는:

"login failed for user": Agent가 호스트에 연결을 성공적으로 수립했지만 어떤 이유로 로그인이 거부되었음을 의미해요.

문제 해결:

Agent의 로그인 자격 증명을 확인하세요.
sqlcmd로 해당 자격 증명을 사용해 수동으로 로그인해보세요. 예: sqlcmd -S localhost -U datadog -P ${SQL_PASSWORD} -d master

"could not open database requested for login": 이 오류는 네트워크 문제로 인해 나타나거나 알 수 없는 데이터베이스 때문에 나타나요.

문제 해결:

telnet {host} {port}를 실행해서 Agent에서 호스트로의 TCP 연결을 확인하고 Agent에서 데이터베이스로 네트워크 연결이 있는지 확인하세요.
sqlcmd로 수동 로그인을 시도하고 설정된 데이터베이스에 문제가 있는지 확인하세요. 예: sqlcmd -S localhost -U datadog -P ${SQL_PASSWORD} -d master

"Invalid connection string attribute" 때문인 경우

Windows에서 지원되는 ADO Provider는 SQLOLEDB, MSOLEDBSQL, MSOLEDBSQL19, SQLNCLI11이에요.

SQLOLEDB와 SQLNCLI11 프로바이더는 여러 문제로 인해 Invalid connection string attribute 오류 메시지를 표시할 수 있어요. 예를 들어:

datadog_checks.sqlserver.connection.SQLConnectionError:
Unable to connect to SQL Server for instance foo.com,1433 - master:
OperationalError(com_error(-2147352567, 'Exception occurred.',
(0, 'Microsoft OLE DB Provider for SQL Server',
'Invalid connection string attribute', None, 0, -2147467259), None),
'Error opening connection to "ConnectRetryCount=2;Provider=SQLOLEDB;Data Source=foo.com,1433;Initial Catalog=master;User ID=datadog;Password=******;"')

이 동일한 오류는 실패 이유와 무관하게 표시돼요(예: 알 수 없는 호스트네임, TCP 연결 미수립, 잘못된 로그인 자격 증명, 알 수 없는 데이터베이스 등).

오류 메시지에서 HResult 오류 코드를 찾아보세요. 알려진 코드의 예시는 다음과 같아요:

-2147217843 "login failed for user": Agent가 호스트에 연결 성공했지만 어떤 이유로 로그인이 거부되었음을 의미해요.

-2147467259 "could not open database requested for login": 이 오류는 네트워크 문제나 알 수 없는 데이터베이스 때문에 나타나요.

두 단계 모두 문제를 해결하지 못하거나 목록에 없는 오류 코드가 보이면 Datadog는 MSOLEDBSQL 드라이버나 Microsoft ODBC Driver for SQL Server 사용을 권장해요. 이 드라이버들은 더 자세한 오류 메시지를 제공해서 연결 실패 원인을 진단하는 데 도움이 돼요.

SQL Server 'Unable to connect: Adaptive Server is unavailable or does not exist'

이 오류는 가끔 host 필드를 제대로 설정하지 않은 결과일 수 있어요. 통합에서는 host 필드를 host:server,port 구문으로 설정하세요.

예를 들어 host를 이렇게 설정했다면:

host: sqlserver-foo.cfxxae8cilce.us-east-1.rds.amazonaws.com

포트를 추가해서 다음과 같이 설정해야 해요:

host: sqlserver-foo.cfxxae8cilce.us-east-1.rds.amazonaws.com,1433

SSL Provider: The certificate chain was issued by an authority that is not trusted

Microsoft OLE DB Driver 2019

이 오류는 도입된 호환성 변경으로 인해 MSOLEDBSQL 2019 드라이버로 업그레이드한 후 흔히 발생해요. 최신 버전의 드라이버에서는 SQL 인스턴스에 대한 모든 연결이 기본적으로 암호화됩니다.

Microsoft OLE DB Driver for SQL Server 최신 버전을 사용하면서 암호화된 연결을 요구하는 SQL Server 인스턴스에 연결하려면 다음 해결 방법 중 하나를 사용할 수 있어요:

자체 서명 인증서를 사용하고 서버에서 Force Encryption 설정(AWS의 rds.force_ssl=1)을 사용해서 클라이언트가 암호화로 연결하도록 보장하는 경우:
- 클라이언트의 트러스트 체인 일부로 신뢰되는 인증서로 변경하세요.
- 자체 서명 인증서를 클라이언트의 신뢰할 수 있는 인증서로 추가하세요.
- 연결 문자열에 Trust Server Certificate=True;를 추가하세요.

이 내용은 Microsoft 문서에 더 자세히 설명되어 있어요. SQL Server 인스턴스가 연결 시 암호화를 요구하지 않는다면(AWS의 rds.force_ssl=0) 연결 문자열에 Use Encryption for Data=False;를 포함하도록 업데이트하세요. 예:

instances:
  - host: <INSTANCE_ENDPOINT>,<PORT>
    connection_string: "Trust Server Certificate=True;Use Encryption for Data=False;"
    connector: adodbapi
    adoprovider: MSOLEDBSQL19

기본적으로 암호화를 사용하지 않는 2018 버전의 MSOLEDBSQL 드라이버를 설치하세요. 드라이버를 설치한 후 adoprovider를 MSOLEDBSQL로 업데이트하세요. 예:

instances:
  - host: <INSTANCE_ENDPOINT>,<PORT>
    connection_string: "Trusted_Connection=yes;"
    connector: adodbapi
    adoprovider: MSOLEDBSQL

기타 Microsoft OLE DB 및 ODBC 드라이버 버전

MSOLEDBSQL 2019가 아닌 다른 OLE DB 드라이버나 ODBC 드라이버를 사용한다면 연결 문자열에 TrustServerCertificate=yes를 설정해서 이 오류를 해결할 수 있어요. 예를 들어 ODBC 드라이버의 경우:

# this example uses SQL Server authentication
instances:
  - host: <INSTANCE_ENDPOINT>,<PORT>
    username: datadog
    password: <DD_AGENT_PASSWORD>
    connection_string: "TrustServerCertificate=yes;"
    connector: odbc
    driver: '{ODBC Driver 18 for SQL Server}'

SQL Server가 연결되지 않아요 'SSL Security error (18)'

이것은 구형 SQL Server ODBC 드라이버의 알려진 문제예요. 오류 메시지의 연결 문자열을 보면 Agent가 사용 중인 드라이버 버전을 확인할 수 있어요.

예를 들어 오류 메시지의 연결 문자열에 Provider=SQL Server가 보이면 ODBC 드라이버를 최신 버전으로 업그레이드하면 오류가 해결돼요.

이 문제는 이 Microsoft 블로그 게시물에 더 자세히 설명되어 있어요.

빈 연결 문자열

Datadog의 SQL Server 체크는 adodbapi Python 라이브러리에 의존하는데, SQL Server에 연결 문자열을 만드는 데 사용할 수 있는 문자에 몇 가지 제한이 있어요. Agent가 SQL Server 연결에 문제를 겪고 Agent의 collector.logs에서 다음과 비슷한 오류를 발견한다면, sqlserver.yaml에 adodbapi에 문제를 일으키는 문자가 포함되어 있을 수 있어요.

OperationalError: (KeyError('Python string format error in connection string->',), 'Error opening connection to ""')

현재 이 특정 연결 문제를 일으키는 것으로 알려진 유일한 문자는 % 문자예요. sqlserver.yaml 파일에서 % 문자를 사용해야 한다면(예: Datadog SQL Server 사용자 비밀번호에 %가 포함된 경우) 각각의 단일 % 대신 이중 %%를 넣어 이스케이프해야 해요.

흔한 SQL Server 드라이버 문제 진단

데이터 원본 이름을 찾을 수 없고 기본 드라이버가 지정되지 않음

이것은 Linux에서 ODBC 드라이버 기본 설정을 사용할 때 흔히 보이는 오류예요. /etc/odbcinst.ini 파일에서 드라이버에 설정된 DSN이 Agent 설정에 설정된 드라이버 이름과 일치하지 않을 때 발생할 수 있어요.

예를 들어 Agent의 기본 ODBC 드라이버({ODBC Driver 18 for SQL Server})를 사용하려면 인스턴스 설정에 다음이 포함되어야 해요:

  connector: odbc

Agent가 시작해서 SQL Server 인스턴스에 연결을 시도하면 /etc/odbcinst.ini 파일에서 드라이버 바이너리 경로를 찾아요.

예를 들어 이 /etc/odbcinst.ini 파일은 드라이버를 설정해요:

$ cat /etc/odbcinst.ini
[ODBC Driver 18 for SQL Server]
Description=Microsoft ODBC Driver 18 for SQL Server
Driver=/opt/microsoft/msodbcsql/lib64/libmsodbcsql-13.1.so.7.0
UsageCount=1

위 예의 DSN은 [ODBC Driver 18 for SQL Server]이고, 이는 Agent가 사용하는 기본 드라이버 이름과 일치해요. 드라이버의 DSN이 Agent가 사용하는 드라이버 이름과 일치하지 않으면 Data source not found 오류가 발생해요.

인스턴스 설정에서 dsn을 /etc/odbcinst.ini 파일에 설정된 값과 일치시키는 것이 가능해요. 예:

$ cat /etc/odbcinst.ini
[Custom]
Description=Microsoft ODBC Driver 18 for SQL Server
Driver=/opt/microsoft/msodbcsql/lib64/libmsodbcsql-13.1.so.7.0
UsageCount=1

그러면 인스턴스 설정에서 dsn 필드를 설정하게 돼요:

  connector: odbc
  dsn: "Custom"

Provider 또는 드라이버를 찾을 수 없음

이 오류 메시지는 드라이버마다 표현이 다를 수 있지만, 보통 ODBC에서는 다음과 같이 보여요:

Can't open lib .* file not found
Data source name not found.* and no default driver specified

그리고 MSOLEDBSQL 프로바이더의 오류 메시지는 다음과 같아요:

Provider cannot be found. It may not be properly installed.

이것은 드라이버나 프로바이더가 Agent가 실행 중인 호스트에 제대로 설치되지 않았음을 의미해요. 선택한 드라이버의 모든 설치 안내를 따랐는지 확인하세요.

Agent가 드라이버를 찾지 못하는 것일 수도 있어요. 이는 Linux의 ODBC 드라이버에서 더 흔해요. Linux 호스트에서 SQL Server에 연결하는 섹션을 참고해서 Linux에 ODBC 드라이버를 설치하는 자세한 안내를 확인하세요.

드라이버 선택에 도움이 필요하다면 SQL Server 드라이버 선택 섹션에서 Agent로 드라이버를 올바르게 구성하는 방법을 참고해요.

Linux 호스트에서 SQL Server에 연결

SQL Server(Linux 또는 Windows 호스팅)를 Linux 호스트에 연결하려면:

Linux 배포판에 Microsoft ODBC Driver를 설치하세요. 사용할 드라이버 이름이 확실하지 않다면 /etc/odbcinst.ini 상단 괄호 안에서 찾을 수 있어요.

$ cat /etc/odbcinst.ini
[ODBC Driver 13 for SQL Server]
Description=Microsoft ODBC Driver 13 for SQL Server
Driver=/opt/microsoft/msodbcsql/lib64/libmsodbcsql-13.1.so.7.0
UsageCount=1

odbc.ini와 odbcinst.ini 파일을 /opt/datadog-agent/embedded/etc 폴더로 복사하세요.
필요한 경우 pyodbc 모듈을 설치하세요. Agent의 Python 환경 내에서 pip install pyodbc를 실행하면 됩니다. 예를 들어:
```
$ sudo /opt/datadog-agent/embedded/bin/pip install pyodbc
```

odbcinst.ini 파일에 표시된 대로 conf.yaml이 odbc 커넥터를 사용하고 적절한 드라이버를 지정하도록 SQL Server를 설정하세요.

init_config:

instances:
  - host: <HOST>,<PORT>
    # enable the odbc connector
    connector: odbc
    # enable the ODBC driver
    driver: '{ODBC Driver 13 for SQL Server}'
    username: <USERNAME>
    password: <PASSWORD>

SQL Server 드라이버 선택

Agent가 SQL Server 인스턴스에 연결하려면 Microsoft ODBC driver 또는 OLE DB driver를 설치해야 해요.

선택한 드라이버에 따라 인스턴스 설정의 connector 필드에 설정할 값이 결정돼요.

예를 들어 Microsoft ODBC driver의 경우:

connector: odbc
driver: '{ODBC Driver 18 for SQL Server}'

OLE DB driver의 경우:

connector: adodbapi
adoprovider: MSOLEDBSQL

이 값들은 연결 문자열의 Provider 부분에 매핑하는 데 사용돼요.

예를 들어 adoprovider: MSOLEDBSQL을 설정하면 연결 문자열에 Provider=MSOLEDBSQL이 포함돼요. 이는 설치한 드라이버 버전의 이름과 일치해야 해요.

최신 버전의 Microsoft OLE DB driver에서는 드라이버 이름이 MSOLEDBSQL에서 MSOLEDBSQL19로 변경되었으므로 인스턴스 설정에 다음과 같이 나타나야 해요:

connector: adodbapi
adoprovider: MSOLEDBSQL19

선택한 드라이버의 최신 버전으로 최신 상태를 유지할 것을 권장해요.

기타 흔한 문제

Query Metrics와 Plan Samples에서 SQL Server user 태그가 없음

user 태그는 SQL Server의 기술적 제한으로 쿼리를 실행하는 정확한 사용자 수집을 할 수 없어서 Query Metrics와 Plan Samples에서 더 이상 지원되지 않아요.

user 태그는 Query Activity 이벤트와 Database Load 메트릭에서 사용할 수 있어요.

왜 "CREATE PROCEDURE" 쿼리가 이렇게 많나요?

7.40.0보다 낮은 Agent 버전에는 PROCEDURE 통계가 과도하게 집계되는 버그가 있어요. 이로 인해 database-monitoring Query Metrics UI에서 CREATE PROCEDURE... 실행이 많이 보여요. 이 문제를 해결하려면 최신 버전의 Datadog Agent로 업그레이드하세요.

SQL Server Agent 작업이 수집되지 않음 "The SELECT permission was denied on the object 'sysjobs'" 오류

SQL Server Agent 작업 체크는 msdb 데이터베이스에 대한 SELECT 권한이 필요해요. The SELECT permission was denied on the object 'sysjobs' 오류가 보이면 Agent가 SQL Server 인스턴스에 연결할 때 사용하는 사용자에게 SELECT 권한을 부여해야 해요.

USE msdb;
CREATE USER datadog FOR LOGIN datadog;
GRANT SELECT to datadog;

알려진 제한 사항

SQL Server 2012

다음 메트릭은 SQL Server 2012에서 사용할 수 없어요:

sqlserver.files.read_io_stall_queued
sqlserver.files.write_io_stall_queued
sqlserver.ao.quorum_type
sqlserver.ao.quorum_state
sqlserver.ao.member.type
sqlserver.ao.member.state
sqlserver.ao.member.number_of_quorum_votes
sqlserver.ao.log_send_queue_size
sqlserver.ao.log_send_rate
sqlserver.ao.redo_queue_size
sqlserver.ao.redo_rate
sqlserver.ao.low_water_mark_for_ghosts
sqlserver.ao.filestream_send_rate
sqlserver.ao.replica_status
sqlserver.ao.secondary_lag_seconds
sqlserver.fci.status
sqlserver.fci.is_current_owner
sqlserver.latches.latch_wait_time

교착 상태(Deadlock) 수집(collect_deadlocks: enabled: true)은 SQL Server 2012에서 지원되지 않아요. 수집 쿼리가 SQL Server 2016에서 도입된 T-SQL 연산자 AT TIME ZONE을 사용하기 때문이에요. SQL Server 2012에서 이 기능을 활성화하면 매 체크 실행마다 쿼리 구문 오류(Incorrect syntax near 'AT')가 발생해요. 이 오류를 피하려면 인스턴스 설정에서 collect_deadlocks: enabled: false로 설정하세요.

SQL Server 2014

다음 메트릭은 SQL Server 2014에서 사용할 수 없어요:

sqlserver.ao.secondary_lag_seconds
sqlserver.latches.latch_wait_time

교착 상태(Deadlock) 수집(collect_deadlocks: enabled: true)은 SQL Server 2014에서 지원되지 않아요. 수집 쿼리가 SQL Server 2016에서 도입된 T-SQL 연산자 AT TIME ZONE을 사용하기 때문이에요. SQL Server 2014에서 이 기능을 활성화하면 매 체크 실행마다 쿼리 구문 오류(Incorrect syntax near 'AT')가 발생해요. 이 오류를 피하려면 인스턴스 설정에서 collect_deadlocks: enabled: false로 설정하세요.