데이터베이스 모니터링과 트레이스 상호 연결

데이터베이스 모니터링과 트레이스 상호 연결 (Correlate Database Monitoring and Traces)

출처: 문서

본문

이 가이드는 데이터베이스 모니터링을 구성했고 APM을 사용하고 있다고 가정해요. APM과 DBM을 연결하면 APM 트레이스 식별자가 DBM 데이터 수집에 주입되어 두 데이터 소스를 연결(correlate)할 수 있어요. 이를 통해 APM 제품에서 데이터베이스 정보를 보여주고, DBM 제품에서 APM 데이터를 보여주는 제품 기능을 사용할 수 있어요.

시작하기 전에 (Before you begin)

• 지원되는 데이터베이스: Postgres, MySQL, SQL Server, Oracle, MongoDB
• 지원되는 에이전트 버전: 7.46+
• 데이터 프라이버시: SQL 주석 전파(SQL comment propagation)를 활성화하면 잠재적으로 기밀인 데이터(서비스 이름)가 데이터베이스에 저장되며, 데이터베이스에 대한 액세스 권한이 부여된 다른 제3자가 접근할 수 있게 돼요.

Datadog SDK 통합은 애플리케이션에서 데이터베이스로 전달되는 정보의 양을 제어하는 전파 모드(Propagation Mode) 를 지원해요.

전파 모드	설명
full	전체 트레이스 정보를 데이터베이스로 전송해서 DBM 내에서 개별 트레이스를 조사할 수 있어요. 대부분의 통합에 권장되는 솔루션이에요.
service	서비스 이름을 전송해서 어떤 서비스가 데이터베이스 부하에 기여하는지 이해할 수 있어요.
disabled	전파를 비활성화하고 애플리케이션에서 어떤 정보도 보내지 않아요.

지원되는 데이터베이스

Postgres

언어	최소 트레이서 버전	라이브러리/프레임워크	모드
Go	dd-trace-go v2	database/sqlsqlx	full``service
Java	dd-trace-java >= 1.11.0	jdbc	full``service
.NET	dd-trace-dotnet >= 2.35.0	Npgsql	full``service
Node.js	dd-trace-js >= 3.17.0	postgres	full``service
PHP	dd-trace-php >= 0.86.0	pdo	full``service
Python	dd-trace-py >= 1.9.0	psycopg2psycopg	full``service
Python	dd-trace-py >= 2.9.0	asyncpg	full``service
Ruby	dd-trace-rb >= 1.8.0	pg	full``service

참고: .NET 드라이버는 CommandType.StoredProcedure를 지원하지 않아요.

MySQL

언어	최소 트레이서 버전	라이브러리/프레임워크	모드
Go	dd-trace-go v2	database/sqlsqlx	full``service
Java	dd-trace-java >= 1.11.0	jdbc	full``service
.NET	dd-trace-dotnet >= 2.35.0	MySql.DataMySqlConnector	full``service
Node.js	dd-trace-js >= 3.17.0	mysqlmysql2	full``service
PHP	dd-trace-php >= 0.86.0	pdoMySQLi	full``service
Python	dd-trace-py >= 2.9.0	aiomysqlmysql-connector-pythonmysqlclientpymysql	full``service
Ruby	dd-trace-rb >= 1.8.0	mysql2	full``service

참고: .NET 드라이버는 CommandType.StoredProcedure를 지원하지 않아요.

참고: Aurora MySQL의 전체(full) 전파 모드에는 버전 3이 필요해요.

SQL Server

언어	최소 트레이서 버전	라이브러리/프레임워크	모드
Go	dd-trace-go v2	database/sqlsqlx	service
Java	dd-trace-java >= 1.11.0	jdbc	full``service
.NET	dd-trace-dotnet >= 2.35.0	System.Data.SqlClientMicrosoft.Data.SqlClient	full``service

참고: .NET 드라이버는 CommandType.StoredProcedure를 지원하지 않아요.

Java 및 .NET의 full 모드의 경우:

참고(위험): 애플리케이션이 계측(instrumentation)에 context_info를 사용하면 Datadog SDK가 이를 덮어써요.

• 계측은 클라이언트가 쿼리를 실행할 때 SET context_info 명령을 실행하며, 이는 데이터베이스에 대한 추가 왕복(round-trip)을 발생시켜요.
• 사전 요구 사항:
  • 에이전트 버전 7.55.0 이상
  • Java 트레이서 버전 1.39.0 이상
  • .NET 트레이서 버전 3.3 이상

Oracle

언어	최소 트레이서 버전	라이브러리/프레임워크	모드
Go	dd-trace-go v2	database/sqlsqlx	service
Java	dd-trace-java >= 1.11.0	jdbc	full``service

Java의 full 모드의 경우:

• 계측은 V$SESSION.ACTION을 덮어써요.
• 사전 요구 사항: Java 트레이서 1.45 이상

MongoDB

언어	최소 트레이서 버전	라이브러리/프레임워크	모드
Java	dd-trace-java >= 1.58.0	mongo-java-driver v3.8+	full``service
Node.js	dd-trace-js >= 5.80.0	mongodb	full``service
Python	dd-trace-py >= 3.5.0	pymongo	full``service

설정 (Setup)

애플리케이션에서 다음 환경 변수를 설정해요.

DD_SERVICE=(application name)
DD_ENV=(application environment)
DD_VERSION=(application version)

이 태그들은 APM 상관 관계 뷰와 DBM 활성 연결 분석(active connections breakdown)에서 서비스를 식별해요.

Datadog은 에이전트 버전 7.63 이상에서 난독화 모드를 obfuscate_and_normalize로 설정할 것을 권장해요. APM 에이전트 구성 파일의 apm_config 섹션에 다음 파라미터를 추가하세요.

  sql_obfuscation_mode: "obfuscate_and_normalize"

경고: 난독화 모드를 변경하면 정규화된 SQL 텍스트가 바뀔 수 있어요. APM 트레이스에서 SQL 텍스트를 기반으로 하는 모니터가 있다면 업데이트해야 할 수 있어요.

Go

d-trace-go v2를 포함하도록 앱 의존성을 업데이트하세요. 참고: 이 문서는 Datadog이 모든 사용자에게 권장하는 Go 트레이서 v2를 사용해요. v1을 사용 중이라면 마이그레이션 가이드를 참고해서 v2로 업그레이드하세요.

go get github.com/DataDog/dd-trace-go/v2 # 2.x

코드를 업데이트해서 contrib/database/sql 패키지를 가져와요.

import (
   "database/sql"
   "github.com/DataDog/dd-trace-go/v2/ddtrace/tracer"
   sqltrace "github.com/DataDog/dd-trace-go/contrib/database/sql/v2"
)

다음 방법 중 하나로 데이터베이스 모니터링 전파 기능을 활성화해요.

• 환경 변수: DD_DBM_PROPAGATION_MODE=full

• 드라이버 등록 중 코드 사용:

  sqltrace.Register("postgres", &pq.Driver{}, sqltrace.WithDBMPropagation(tracer.DBMPropagationModeFull), sqltrace.WithService("my-db-service"))
  

• sqltrace.Open에서 코드 사용:

  sqltrace.Register("postgres", &pq.Driver{}, sqltrace.WithService("my-db-service"))
  
  db, err := sqltrace.Open("postgres", "postgres://pqgotest:***@localhost/pqgotest?sslmode=disable", sqltrace.WithDBMPropagation(tracer.DBMPropagationModeFull))
  if err != nil {
      log.Fatal(err)
  }
  

전체 예시:

import (
	"database/sql"
	"github.com/DataDog/dd-trace-go/v2/ddtrace/tracer"
   sqltrace "github.com/DataDog/dd-trace-go/contrib/database/sql/v2"
)

func main() {
	// The first step is to set the dbm propagation mode when registering the driver. Note that this can also
	// be done on sqltrace.Open for more granular control over the feature.
	sqltrace.Register("postgres", &pq.Driver{}, sqltrace.WithDBMPropagation(tracer.DBMPropagationModeFull))

	// Followed by a call to Open.
	db, err := sqltrace.Open("postgres", "postgres://pqgotest:***@localhost/pqgotest?sslmode=disable")
	if err != nil {
		log.Fatal(err)
	}

	// Then, we continue using the database/sql package as we normally would, with tracing.
	rows, err := db.Query("SELECT name FROM users WHERE age=?", 27)
	if err != nil {
		log.Fatal(err)
	}
	defer rows.Close()
}

Java

Java 트레이싱 계측 지침을 따르고 에이전트의 1.11.0 버전 이상을 설치하세요.

또한 jdbc-datasource 계측을 활성화해야 해요.

다음 방법 중 하나로 데이터베이스 모니터링 전파 기능을 활성화해요.

• 시스템 속성 설정: dd.dbm.propagation.mode=full
• 환경 변수 설정: DD_DBM_PROPAGATION_MODE=full

전체 예시:

# Start the Java Agent with the required system properties
java -javaagent:/path/to/dd-java-agent.jar -Ddd.dbm.propagation.mode=full -Ddd.integration.jdbc-datasource.enabled=true -Ddd.service=my-app -Ddd.env=staging -Ddd.version=1.0 -jar path/to/your/app.jar

애플리케이션에서 기능을 테스트해요.

public class Application {
    public static void main(String[] args) {
        try {
            Connection connection = DriverManager
                    .getConnection("jdbc:postgresql://127.0.0.1/foobar?preferQueryMode=simple", "user", "password");
            Statement stmt = connection.createStatement();
            String sql = "SELECT * FROM foo";
            stmt.execute(sql);
            stmt.close();
            connection.close();
        } catch (SQLException exception) {
            //  exception logic
        }
    }
}

트레이서 버전 1.44 이상: 다음 방법 중 하나로 Postgres용 prepared statements 트레이싱을 활성화해요.

• 시스템 속성 설정: dd.dbm.trace_prepared_statements=true
• 환경 변수 설정: export DD_DBM_TRACE_PREPARED_STATEMENTS=true

참고: prepared statements 계측은 Application 속성을 _DD_overwritten_by_tracer 텍스트로 덮어쓰고 데이터베이스에 대한 추가 왕복을 발생시켜요. 이 추가 왕복은 SQL 문 실행 시간에 미미한 영향을 미쳐요.

위험(참고): prepared statements 트레이싱을 활성화하면 Amazon RDS Proxy를 사용할 때 연결 핀닝이 증가해 연결 풀링 효율이 떨어질 수 있어요. 자세한 내용은 RDS Proxy의 연결 핀닝을 참고하세요.

트레이서 버전 1.44 미만: Postgres 및 MySQL에서 prepared statements는 full 모드로 지원되지 않으며, prepared statements를 사용하는 모든 JDBC API 호출은 자동으로 service 모드로 다운그레이드돼요. 대부분의 Java SQL 라이브러리는 기본적으로 prepared statements를 사용하므로, 대부분의 Java 애플리케이션은 service 모드만 사용할 수 있다는 뜻이에요.

Ruby

Gemfile에서 dd-trace-rb을 1.8.0 이상 버전으로 설치하거나 업데이트해요.

source 'https://rubygems.org'
gem 'datadog' # Use `'ddtrace', '>= 1.8.0'` if you're using v1.x

# Depends on your usage
gem 'mysql2'
gem 'pg'

다음 방법 중 하나로 데이터베이스 모니터링 전파 기능을 활성화해요.

1. 환경 변수: DD_DBM_PROPAGATION_MODE=full

2. mysql2 또는 pg용 옵션 comment_propagation (기본값: ENV['DD_DBM_PROPAGATION_MODE']):

    Datadog.configure do |c|
    	c.tracing.instrument :mysql2, comment_propagation: 'full'
    	c.tracing.instrument :pg, comment_propagation: 'full'
    end
   

전체 예시:

require 'mysql2'
require 'ddtrace'

Datadog.configure do |c|
	c.service = 'billing-api'
	c.env = 'production'
	c.version = '1.3-alpha'

	c.tracing.instrument :mysql2, comment_propagation: ENV['DD_DBM_PROPAGATION_MODE']
end

client = Mysql2::Client.new(:host => "localhost", :username => "root")
client.query("SELECT 1;")

Python

dd-trace-py>=1.9.0을 포함하도록 앱 의존성을 업데이트하세요.

pip install "ddtrace>=1.9.0"

Postgres의 경우 psycopg2를 설치해요.

pip install psycopg2

MongoDB의 경우 pymongo를 설치해요.

pip install pymongo

참고: MongoDB 지원에는 dd-trace-py >= 3.5.0이 필요해요. 업그레이드가 필요하다면: pip install "ddtrace>=3.5.0".

다음 환경 변수를 설정해서 데이터베이스 모니터링 전파 기능을 활성화해요.

• DD_DBM_PROPAGATION_MODE=full

Postgres 예시:

import psycopg2

POSTGRES_CONFIG = {
    "host": "127.0.0.1",
    "port": 5432,
    "user": "postgres_user",
    "password": "postgres_password",
    "dbname": "postgres_db_name",
}

# connect to postgres db
conn = psycopg2.connect(**POSTGRES_CONFIG)
cursor = conn.cursor()
# execute sql queries
cursor.execute("select 'blah'")
cursor.executemany("select %s", (("foo",), ("bar",)))

MongoDB 예시:

from pymongo import MongoClient

# Connect to MongoDB
client = MongoClient('mongodb://localhost:27017/')
db = client['test_database']
collection = db['test_collection']

# Insert a document
collection.insert_one({"name": "test", "value": 1})

# Query documents
results = collection.find({"name": "test"})
for doc in results:
    print(doc)

.NET

위험: 이 기능을 사용하려면 .NET 서비스에 자동 계측이 활성화되어 있어야 해요.

.NET Framework 트레이싱 지침 또는 .NET Core 트레이싱 지침을 따라 자동 계측 패키지를 설치하고 서비스에 대한 트레이싱을 활성화해요.

지원되는 클라이언트 라이브러리를 사용하고 있는지 확인하세요. 예를 들어 Npgsql.

다음 환경 변수를 설정해서 데이터베이스 모니터링 전파 기능을 활성화해요.

• Postgres 및 MySQL의 경우: DD_DBM_PROPAGATION_MODE=full
• SQL Server의 경우: DD_DBM_PROPAGATION_MODE=service 또는 Java/.NET 트레이서에서 DD_DBM_PROPAGATION_MODE=full
• Oracle의 경우: DD_DBM_PROPAGATION_MODE=service

PHP

위험: 이 기능을 사용하려면 PHP 서비스에 트레이서 확장이 활성화되어 있어야 해요.

PHP 트레이싱 지침을 따라 자동 계측 패키지를 설치하고 서비스에 대한 트레이싱을 활성화해요.

지원되는 클라이언트 라이브러리를 사용하고 있는지 확인하세요. 예를 들어 PDO.

다음 환경 변수를 설정해서 데이터베이스 모니터링 전파 기능을 활성화해요.

• DD_DBM_PROPAGATION_MODE=full

Node.js

dd-trace-js을 3.17.0보다 높은 버전(또는 수명 종료된 Node.js 버전 12를 사용한다면 2.30.0)으로 설치하거나 업데이트해요.

npm install dd-trace@^3.17.0

트레이서를 가져오고 초기화하도록 코드를 업데이트해요.

// This line must come before importing any instrumented module.
const tracer = require('dd-trace').init();

다음 방법 중 하나로 데이터베이스 모니터링 전파 기능을 활성화해요.

• 다음 환경 변수를 설정해요.

  DD_DBM_PROPAGATION_MODE=full
  

• SDK가 dbmPropagationMode 옵션을 사용하도록 설정해요 (기본값: ENV['DD_DBM_PROPAGATION_MODE']).

  const tracer = require('dd-trace').init({ dbmPropagationMode: 'full' })
  

• 통합 수준에서만 활성화해요.

  const tracer = require('dd-trace').init();
  tracer.use('pg', {
     dbmPropagationMode: 'full'
  })
  

전체 예시:

const pg = require('pg')
const tracer = require('dd-trace').init({ dbmPropagationMode: 'full' })

const client = new pg.Client({
	user: 'postgres',
	password: 'postgres',
	database: 'postgres'
})

client.connect(err => {
	console.error(err);
	process.exit(1);
});

client.query('SELECT $1::text as message', ['Hello world!'], (err, result) => {
	// handle result
})

전파를 활성화한 후 비활성화하려면 DD_DBM_PROPAGATION_MODE=disabled로 설정하세요.

통합 검증 (Verify the integration)

통합이 작동하는지 확인하려면:

1. 계측된 애플리케이션을 실행하고 데이터베이스 쿼리를 실행해요.
2. Datadog에서 데이터베이스 모니터링 > 쿼리 샘플(Query Samples)로 이동해요.
3. 쿼리 샘플에 APM 상관 관계 배지가 나타나는지 확인해요.

DBM에서 APM 연결 탐색 (Explore the APM Connection in DBM)

활성 데이터베이스 연결을 호출한 APM 서비스에 귀속 (Attribute active database connections to the calling APM services)

특정 호스트의 활성 연결을 요청을 하는 업스트림 APM 서비스별로 분석해요. 데이터베이스의 부하를 개별 서비스에 귀속시켜 어떤 서비스가 데이터베이스에서 가장 활발한지 이해할 수 있어요. 가장 활발한 업스트림 서비스의 서비스 페이지로 피벗해서 조사를 계속해요.

호출하는 APM 서비스로 데이터베이스 호스트 필터링 (Filter your database hosts by the APM services that call them)

데이터베이스 목록(Database List)을 필터링해서 특정 APM 서비스가 의존하는 데이터베이스 호스트만 표시해요. 다운스트림 의존성에 서비스 성능에 영향을 줄 수 있는 블로킹 활동이 있는지 식별해요.

쿼리 샘플에 대한 연관 트레이스 보기 (View the associated trace for a query sample)

데이터베이스 모니터링에서 쿼리 샘플(Query Sample)을 볼 때 연관된 트레이스가 APM에 의해 샘플링된 경우, APM 트레이스의 맥락에서 DBM 샘플을 볼 수 있어요. 이렇게 하면 실행 계획과 쿼리의 과거 성능을 포함한 DBM 텔레메트리를 인프라스트럭처 내 스팬의 계보와 함께 결합해서, 데이터베이스의 변경이 애플리케이션 성능 저하의 원인인지 이해할 수 있어요.

APM에서 DBM 연결 탐색 (Explore the DBM Connection in APM)

APM 서비스의 다운스트림 데이터베이스 호스트 시각화 (Visualize the downstream database hosts of APM services)

특정 서비스의 APM 페이지에서 데이터베이스 모니터링이 식별한 서비스의 직접 다운스트림 데이터베이스 의존성을 보고, 노이즈 이웃(noisy neighbor)으로 인해 불균형한 부하가 있는 호스트가 있는지 확인할 수 있어요. 서비스의 데이터베이스 의존성을 보려면:

1. 카탈로그(Catalog)에서 서비스를 선택해서 세부 정보 패널을 열어요.
2. 패널에서 서비스 페이지(Service Page)를 선택해요.
3. 서비스 페이지에서 데이터베이스(Databases) 섹션을 선택해요.
4. 데이터베이스 섹션 내에서 Databases 탭을 선택해요.

스팬 기간 시각화 및 쿼리 세부 정보 보기 (Visualize span durations and view query details)

APM 서비스 페이지의 데이터베이스 섹션에서 Queries 탭을 선택하면 선택한 시간 간격의 지연 이상값과 쿼리 전체 목록을 볼 수 있어요. 표에서 쿼리를 선택하면 쿼리 패널이 열리고 진단, 오류 세부 정보, 트레이스 정보에 접근할 수 있어요.

트레이스의 데이터베이스 쿼리에 실행 계획을 사용해 잠재적 최적화 식별 (Identify potential optimizations using explain plans for database queries in traces)

트레이스에서 실행한 쿼리와 유사한 쿼리의 과거 성능(샘플링된 대기 이벤트, 평균 지연, 최근 캡처된 실행 계획 포함)을 확인해서 쿼리가 어떻게 수행될 것으로 예상되는지 맥락을 파악해요. 동작이 비정상인지 판단하고, 데이터베이스 모니터링으로 피벗해서 기본 데이터베이스 호스트에 대한 추가 맥락을 얻으며 조사를 계속해요.

더 알아보기 (Learn more)

• DBM과 APM 텔레메트리를 연결해서 종단 간 쿼리 성능 이해하기