기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

# .NET용 X-Ray SDK로 SQL 쿼리 추적하기
<a name="xray-sdk-dotnet-sqlqueries"></a>

**참고**  
X-Ray SDK/데몬 유지 관리 공지 - 2026년 2월 25일에 AWS X-Ray SDKs/데몬은 유지 관리 모드로 전환되며, 여기서 AWS 는 보안 문제만 해결하도록 X-Ray SDK 및 데몬 릴리스를 제한합니다. 지원 일정에 대한 자세한 내용은 [X-Ray SDK 및 데몬 지원 타임라인](xray-sdk-daemon-timeline.md) 섹션을 참조하세요. OpenTelemetry로 마이그레이션하는 것이 좋습니다. OpenTelemetry로 마이그레이션하는 방법에 대한 자세한 내용은 [X-Ray 계측에서 OpenTelemetry 계측으로 마이그레이션](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)을 참조하세요.

.NET용 X-Ray SDK는 `SqlCommand` 대신 사용할 수 있는 `System.Data.SqlClient.SqlCommand`용 래퍼 클래스 `TraceableSqlCommand`를 제공합니다. `TraceableSqlCommand` 클래스를 사용하여 SQL 명령을 초기화할 수 있습니다.

## 동기 및 비동기 메서드를 사용하여 SQL 쿼리 추적
<a name="xray-sdk-dotnot-sqlqueries-trace"></a>

다음 예제에서는 `TraceableSqlCommand`를 사용하여 동기식 및 비동기식으로 SQL Server 쿼리를 자동으로 추적하는 방법을 보여 줍니다.

**Example `Controller.cs` - SQL 클라이언트 구성(동기)**  

```
using Amazon;
using Amazon.Util;
using [Amazon.XRay.Recorder.Core](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Core.htm);
using [Amazon.XRay.Recorder.Handlers.SqlServer](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Handlers_SqlServer.htm);

private void QuerySql(int id)
{
  var connectionString = ConfigurationManager.AppSettings["RDS_CONNECTION_STRING"];
  using (var sqlConnection = new SqlConnection(connectionString))
  using (var sqlCommand = new TraceableSqlCommand("SELECT " + id, sqlConnection))
  {
    sqlCommand.Connection.Open();
    sqlCommand.ExecuteNonQuery();
  }
}
```

`ExecuteReaderAsync` 메서드를 사용하여 비동기식으로 쿼리를 실행할 수 있습니다.

**Example `Controller.cs` - SQL 클라이언트 구성(비동기)**  

```
using Amazon;
using Amazon.Util;
using [Amazon.XRay.Recorder.Core](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Core.htm);
using [Amazon.XRay.Recorder.Handlers.SqlServer](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Handlers_SqlServer.htm);
private void QuerySql(int id)
{
  var connectionString = ConfigurationManager.AppSettings["RDS_CONNECTION_STRING"];
  using (var sqlConnection = new SqlConnection(connectionString))
  using (var sqlCommand = new TraceableSqlCommand("SELECT " + id, sqlConnection))
  {
    await sqlCommand.ExecuteReaderAsync();
  }
}
```

## SQL Server에 수행된 SQL 쿼리 수집
<a name="xray-sdk-dotnot-sqlqueries-collect"></a>

`SqlCommand.CommandText` 캡처를 SQL 쿼리에서 생성된 하위 세그먼트의 일부로 사용할 수 있습니다. `SqlCommand.CommandText`는 하위 세그먼트 JSON에서 `sanitized_query` 필드로 나타납니다. 보안을 위해 이 기능은 기본적으로 비활성화 상태입니다.

**참고**  
중요한 정보를 일반 텍스트로 SQL 쿼리에 포함시키는 경우 수집 기능을 활성화하지 마십시오.

다음 두 가지 방법으로 SQL 쿼리 수집을 활성화할 수 있습니다.
+ 애플리케이션에 대한 글로벌 구성에서 `CollectSqlQueries` 속성을 `true`로 설정합니다.
+ `TraceableSqlCommand` 인스턴스를 `collectSqlQueries` 파라미터를 `true`로 설정하여 인스턴스 내의 호출을 수집합니다.

### 글로벌 CollectSqlQueries 속성 활성화
<a name="xray-sdk-dotnot-sqlqueries-collect-global"></a>

다음 예제에서는 .NET 및 .NET Core에 대해 `CollectSqlQueries` 속성을 활성화하는 방법을 보여 줍니다.

------
#### [ .NET ]

.NET의 애플리케이션에 대한 글로벌 구성에서 `CollectSqlQueries` 속성을 `true`로 설정하려면 다음과 같이 `App.config` 또는 `Web.config` 파일의 `appsettings`을 수정합니다.

**Example `App.config` 또는 `Web.config` – 글로벌로 SQL 쿼리 수집 활성화**  

```
<configuration>
<appSettings>
    <add key="CollectSqlQueries" value="true">
</appSettings>
</configuration>
```

------
#### [ .NET Core ]

.NET Core의 애플리케이션에 대한 글로벌 구성에서 `CollectSqlQueries` 속성을 `true`로 설정하려면 다음과 같이 X-Ray 키에 따라 `appsettings.json` 파일을 수정합니다.

**Example `appsettings.json` – 글로벌로 SQL 쿼리 수집 활성화**  

```
{
  "XRay": {
    "CollectSqlQueries":"true"
  }
}
```

------

### collectSqlQueries 파라미터 활성화
<a name="xray-sdk-dotnot-sqlqueries-collect-instance"></a>

`TraceableSqlCommand` 인스턴스의 `collectSqlQueries` 파라미터를 `true`로 설정하여 해당 인스턴스에서 수행된 SQL Server 쿼리에 대한 SQL 쿼리 텍스트를 수집할 수 있습니다. 파라미터를 `false`로 설정하면 `TraceableSqlCommand` 인스턴스에 대한 `CollectSqlQuery` 기능이 비활성화됩니다.

**참고**  
 `TraceableSqlCommand` 인스턴스의 `collectSqlQueries` 값은 `CollectSqlQueries` 속성의 글로벌 구성에서 설정된 값을 재정의합니다.

**Example 예제 `Controller.cs` – 인스턴스에 대한 SQL 쿼리 수집 활성화**  

```
using Amazon;
using Amazon.Util;
using [Amazon.XRay.Recorder.Core](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Core.htm);
using [Amazon.XRay.Recorder.Handlers.SqlServer](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Handlers_SqlServer.htm);

private void QuerySql(int id)
{
  var connectionString = ConfigurationManager.AppSettings["RDS_CONNECTION_STRING"];
  using (var sqlConnection = new SqlConnection(connectionString))
  using (var command = new TraceableSqlCommand("SELECT " + id, sqlConnection, collectSqlQueries: true))
  {
    command.ExecuteNonQuery();
  }
}
```