.NET 에이전트 8.x에서 9.x로 마이그레이션 가이드

이 가이드에서는 .NET 에이전트의 8.x와 9.x 버전 간의 주요 변경 사항, 업그레이드하는 동안 발생할 수 있는 문제, 버전 9.x로 성공적으로 마이그레이션하는 방법에 대해 간략히 설명합니다.

주요 변경 사항은 다음과 같습니다.

분산 추적은 기본적으로 활성화되어 있습니다.
더 이상 사용되지 않는 공용 에이전트 API 제거
더 이상 사용되지 않는 구성 가능한 에이전트 설정 제거

기본적으로 활성화된 분산 추적

분산 추적 은 2018년 7월부터 .NET 에이전트에 존재한 기능입니다. 분산 애플리케이션 아키텍처에서 요청이 다양한 서비스를 통해 이동할 때 요청에 발생하는 상황을 신속하게 이해하는 가장 좋은 방법으로 CAT(교차 애플리케이션 추적)을 대체합니다. CAT는 버전 9.0부터 .NET 에이전트에서 더 이상 사용되지 않으며 향후 주요 릴리스에서 제거됩니다.

8.x 버전의 .NET 에이전트에서 .NET 에이전트 설치 프로그램이 호스트에 설치한 기본 newrelic.config 파일에는 crossApplicationTracer 요소가 있고 enabled="true" 를 설정합니다. distributedTracing 요소는 기본적으로 존재하지 않습니다.

9.x에서는 이것이 반대입니다. crossApplicationTracer 은 기본적으로 표시되지 않으며 distributedTracing 은 기본값 enabled="true" 와 함께 표시됩니다. 그러나 에이전트 설치 프로그램은 한 버전에서 다른 버전으로 업그레이드할 때 기존 newrelic.config 파일을 덮어쓰지 않습니다. 따라서 지정된 호스트에서 에이전트를 8.x에서 9.x로 업그레이드하는 경우 해당 호스트에서 에이전트의 동작은 변경되지 않습니다.

팁

8.x에서 9.x로 업그레이드할 때 새로운 기본 추적 동작을 채택하려면 분산 추적을 사용하도록 에이전트 구성을 수정해야 합니다. 호스트에 9.x 에이전트를 새로 설치하면 기본적으로 분산 추적이 활성화됩니다.

더 이상 사용되지 않는 공개 에이전트 API 메서드 제거

사용되지 않는 모든 API 메소드에는 기능이 동등한 대체 API 메소드가 있습니다.

팁

애플리케이션 코드에서 .NET 에이전트 API를 사용하는 경우 .NET 에이전트를 9.x로 업그레이드하기 전에 프로젝트의 패키지 참조를 에이전트 API 어셈블리의 최신 9.x 버전으로 업데이트하는 것이 좋습니다. 그렇게 하면 코드가 9.x에서 제거된 API 메서드를 사용하는 경우 컴파일 시간 오류가 발생합니다.

중요

API 어셈블리의 8.x 또는 이전 버전을 계속 사용하고 코드에서 아래 나열된 더 이상 사용되지 않는 API를 사용하는 경우 컴파일 시간 오류가 발생하지 않습니다. 그러나 그런 다음 9.x 버전의 에이전트로 앱을 계측하는 경우 API 메서드는 효과가 없으며 에이전트 로그 파일에 런타임 경고 메시지가 표시됩니다.

제거된 API	대체 API
`CreateDistributedTracePayload`	`InsertDistributedTraceHeaders` W3C 추적 컨텍스트 헤더와 New Relic 분산 추적 헤더를 만듭니다.
`AcceptDistributedTracePayload`	`AcceptDistributedTraceHeaders` W3C 추적 컨텍스트 헤더와 New Relic 분산 추적 헤더를 허용합니다.
`AddCustomParameter`	`AddCustomAttribute` `AddCustomAttribute` ITransaction 인터페이스의 메소드이므로 이 API를 사용하려면 현재 트랜잭션에 대한 참조가 필요합니다.
`GetBrowserTimingFooter`	`GetBrowserTimingHeader` `GetBrowserTimingFooter` 에이전트 버전 3.x부터 Obsolete 으로 표시되었습니다.

예

CreateDistributedTracePayload

이전에 다음과 같은 코드가 있는 경우:

// Create an external web request to another instrumented service
HttpWebRequest requestMessage = (HttpWebRequest)WebRequest.Create("https://remote-address");

// Create the trace payload 
IAgent agent = NewRelic.Api.Agent.NewRelic.GetAgent();
ITransaction transaction = agent.CurrentTransaction;
IDistributedTracePayload payload = transaction.CreateDistributedTracePayload();

// Add the trace payload to the headers of the outgoing request
requestMessage.Headers.Set(NewRelic.Api.Agent.Constants.DistributedTracePayloadKey, payload.HttpSafe());

이것을 다음으로 교체하십시오.

// Create an external web request to another instrumented service
HttpWebRequest requestMessage = (HttpWebRequest)WebRequest.Create("https://remote-address");

// Insert the distributed trace headers to the message. The "setter"
// action tells the API how to add headers to the "carrier", which
// is the HttpWebRequest message in this example
IAgent agent = NewRelic.Api.Agent.NewRelic.GetAgent();
ITransaction currentTransaction = agent.CurrentTransaction;
var setter = new Action<HttpWebRequest, string, string>((carrier, key, value) =>
{
    carrier.Headers?.Set(key, value);
});
currentTransaction.InsertDistributedTraceHeaders(requestMessage, setter);

AcceptDistributedTracePayload

이전에 다음과 같은 코드가 있는 경우:

// Obtain the payload from the upstream request object
HttpContext httpContext = HttpContext.Current;
string payload = httpContext.Request.Headers[NewRelic.Api.Agent.Constants.DistributedTracePayloadKey];

// Accept the payload
IAgent agent = NewRelic.Api.Agent.NewRelic.GetAgent();
ITransaction transaction = agent.CurrentTransaction;
transaction.AcceptDistributedTracePayload(payload, TransportType.HTTP);

이것을 다음으로 교체하십시오.

HttpContext httpContext = HttpContext.Current;
IAgent agent = NewRelic.Api.Agent.NewRelic.GetAgent();
ITransaction currentTransaction = agent.CurrentTransaction;

// The "Getter" method defines how to get headers from the carrier, 
// which is the HttpContext in this example 
IEnumerable<string> Getter(HttpContext carrier, string key)
{
    string value = carrier.Request.Headers[key];
    return value == null ? null : new string[] { value };
}

// Call the API
currentTransaction.AcceptDistributedTraceHeaders(httpContext, Getter, TransportType.HTTP);

사용자 정의 매개변수 추가

이전에 다음과 같은 코드가 있는 경우:

// Called in code that runs inside a transaction created by the
// agent, for example an ASP.NET WebApi endpoint
NewRelic.Api.Agent.NewRelic.AddCustomParameter("myCustomParameter", "myValue");

이것을 다음으로 교체하십시오.

// Get the current transaction
IAgent agent = NewRelic.Api.Agent.NewRelic.GetAgent();
ITransaction currentTransaction = agent.CurrentTransaction;

// Add the custom attribute to the current transaction
currentTransaction.AddCustomAttribute("myCustomParameter", "myValue");

더 이상 사용되지 않는 에이전트 구성 설정 제거

다음 에이전트 구성 설정이 에이전트에서 제거되고 있습니다. 8.x에서 9.x로의 업그레이드 경로를 최대한 원활하게 하기 위해 newrelic.config 파일 XML 스키마에서 설정을 제거하지 않습니다. 그러나 에이전트의 내부 구성 논리는 이러한 설정을 무시하도록 업데이트되고 이러한 구성 값이 더 이상 영향을 미치지 않는다는 경고 메시지를 에이전트 로그 파일에 기록합니다.

표기법에 대한 약간의 설명: 설명의 편의를 위해 이 섹션의 나머지 부분에서는 전체 XML이 아닌 "점 표기법" 약어로 구성 요소를 설명합니다.

예를 들어, newrelic.config 파일에 나타나는 구성 요소는 다음과 같습니다.

<configuration>
  <parameterGroups>
    <identityParameters>
      …
    </identityParameters>
  </parameterGroups>
  …
</configuration>

이 예에서는 parameterGroups.IdentityParameters 으로 작성됩니다. 이러한 모든 구성 요소는 최상위 <configuration> 요소의 자식이므로 간결함을 위해 생략합니다.

제거되는 대부분의 구성 옵션은 속성 데이터의 캡처 또는 제외와 관련됩니다. 다음 문서는 에이전트 속성 데이터 수집의 큰 그림과 구성 방법을 이해하는 데 도움이 됩니다.

제거된 구성 옵션	교체 구성 옵션
`parameterGroups.identityParameters.*`	`attributes.include` `<parameterGroups> <identityParameter enabled="true"/> </parameterGroups>` 와 동등하다 `<attributes enabled="true"> <include>identity.*</include> </attributes>`
`parameterGroups.customParameters.enabled`	`attributes.include`
`parameterGroups.customParameters.ignore`	`attributes.exclude`
`parameterGroups.requestHeaderParameters.enabled`	`attributes.include` `<attributes> <include>request.parameters.*</include> </attributes>` 모든 요청 매개변수를 포함합니다.
`parameterGroups.requestHeaderParameters.ignore`	`attributes.exclude` `<attributes> <exclude>request.parameters.specificRequestParameter</exclude> </attributes>`
`parameterGroups.responseHeaderParameters.*`	없음
`requestParameters.enabled`	`attributes.include` `<attributes> <include>request.parameters.*</include> </attributes>` 모든 요청 매개변수를 포함합니다.
`requestParameters.ignore`	`attributes.exclude` `<attributes> <exclude>request.parameters.specificRequestParamter</exclude> </attributes>`
`analyticsEvents.*`	`transactionEvents.` `analyticsEvents.` 의 모든 하위 구성 요소와 속성도 `transactionEvents.` 에 존재하며 더 이상 사용되지 않는 `transactionEvents.maximumSamplesPerMinute` 옵션을 제외하고 동일한 의미를 갖습니다. 또한 `transactionEvents.attributes` 은 트랜잭션 이벤트에서 사용자 정의 속성의 포함 및 제외를 더 세밀하게 제어합니다.
`transactionTracer.captureAttributes`	`transactionTracer.attributes.enabled` `transactionTracer.attributes.include`/ `exclude` 는 트랜잭션 추적에 포함할 사용자 정의 속성을 더 세밀하게 제어합니다.
`errorCollector.captureAttributes`	`errorCollector.attributes.enabled` `errorCollector.attributes.include`/ `exclude` 는 오류 이벤트에 포함할 맞춤 속성을 더 세밀하게 제어합니다.
`browserMonitoring.captureAttributes`	`browserMonitoring.attributes.enabled` `browserMonitoring.attributes.include`/`exclude` 데이터에 포함할 사용자 정의 속성을 더 세밀하게 제어합니다.
`errorCollector.ignoreErrors`	`errorCollector.ignoreClasses` 자세한 내용은 오류 수집 구성 설명서를 참조하세요.
`transactionEvents.maximumSamplesPerMinute`	없음 이 구성 요소는 에이전트에서 사용되지 않았습니다.

사용자의 편의를 위해 제공되는 기계 번역입니다.

.NET 에이전트 8.x에서 9.x로 마이그레이션 가이드

기본적으로 활성화된 분산 추적.css-21sua1{background:none;border:none;width:0;padding:0;}

팁

더 이상 사용되지 않는 공개 에이전트 API 메서드 제거

팁

중요

예

CreateDistributedTracePayload

AcceptDistributedTracePayload

사용자 정의 매개변수 추가

더 이상 사용되지 않는 에이전트 구성 설정 제거

기본적으로 활성화된 분산 추적