ApplicationInsights.config 또는 .xml로 Application Insights SDK 구성

아티클
10/15/2024

Application Insights .NET SDK는 다양한 NuGet 패키지로 구성됩니다. 코어 패키지 Application Insights에 원격 분석을 보내는 경우에 API를 제공합니다. 추가 패키지는 원격 분석 모듈 및 이니셜라이저를 제공하여 애플리케이션과 해당 컨텍스트에서 원격 분석을 자동으로 추적합니다. 구성 파일을 조정하면 원격 분석 모듈과 이니셜라이저를 사용하거나 사용하지 않도록 설정할 수 있습니다. 일부 매개 변수에 대한 매개 변수를 설정할 수도 있습니다.

참고 항목

다음 설명서는 Application Insights 클래식 API를 사용합니다. Application Insights에 대한 장기 플랜은 OpenTelemetry를 사용하여 데이터를 수집하는 것입니다. 자세한 내용은 .NET, Node.js, Python 및 Java 애플리케이션용 Azure Monitor OpenTelemetry 사용 및 OpenTelemetry 로드맵을 참조하세요. .NET, Node.js 및 Python에 대한 마이그레이션 지침이 제공됩니다.

구성 파일의 이름은 ApplicationInsights.config 또는 ApplicationInsights.xml입니다. 이름은 애플리케이션의 유형에 따라 달라집니다. 대부분의 SDK 버전은 설치할 때 프로젝트에 자동으로 추가됩니다. 기본적으로 추가>Application Insights 원격 분석을 지원하는 Visual Studio 템플릿 프로젝트에서 자동화된 환경을 사용하는 경우 ApplicationInsights.config 파일이 프로젝트 루트 폴더에 만들어집니다. 컴파일되면 bin 폴더에 복사됩니다. 또한 IIS 서버의 Application Insights 에이전트에 의해 웹앱에 추가됩니다. Azure 웹 사이트의 확장 또는 Azure VM 및 가상 머신 확장 집합의 확장이 사용되는 경우 구성 파일은 무시됩니다.

웹 페이지에서 SDK를 제어할 동급의 파일은 없습니다.

이 문서는 구성 파일에서 참조하는 섹션, SDK의 구성 요소를 제어하는 방법 및 해당 구성 요소를 로드하는 NuGet 패키지를 설명합니다.

참고 항목

ApplicationInsights.config 및 .xml 지침은 .NET Core SDK에 적용되지 않습니다. .NET Core 애플리케이션을 구성하려면 ASP.NET Core 애플리케이션에 대한 Application Insights의 지침을 따릅니다.

원격 분석 모듈(ASP.NET)

각 원격 분석 모듈은 특정 형식의 데이터를 수집하고 코어 API를 사용하여 데이터를 전송합니다. 모듈은 다른 NuGet 패키지에 의해 설치되며 이는 .config 파일에 필요한 줄을 추가합니다.

각 모듈에 대해 구성 파일에 노드가 있습니다. 모듈을 사용하지 않으려면 노드를 삭제하거나 주석으로 처리합니다.

종속성 추적

종속성 추적 은 앱이 데이터베이스 및 외부 서비스와 데이터베이스에 수행하는 호출에 대한 원격 분석을 수집합니다. 이 모듈이 IIS 서버에서 작동하도록 하려면 Application Insights 에이전트를 설치해야 합니다.

TrackDependency API를 사용하여 종속성 추적 코드를 작성할 수도 있습니다.

Microsoft.ApplicationInsights.DependencyCollector.DependencyTrackingTelemetryModule
Microsoft.ApplicationInsights.DependencyCollector NuGet 패키지

에이전트 기반(코드리스) 연결을 사용하여 코드를 수정하지 않고 종속성을 자동으로 수집할 수 있습니다. Azure 웹앱에서 사용하려면 Application Insights 확장을 사용하도록 설정합니다. Azure VM 또는 Azure 가상 머신 확장 집합에서 사용하려면 VM 및 가상 머신 확장 집합의 애플리케이션 모니터링 확장을 사용하도록 설정합니다.

성능 수집기

성능 수집기는 IIS 설치에서 CPU, 메모리 및 네트워크 부하와 같은 시스템 성능 카운터를 수집합니다. 사용자가 직접 설정한 성능 카운터를 포함하여 어떤 카운터를 수집할지 지정할 수 있습니다.

Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.PerformanceCollectorModule
Microsoft.ApplicationInsights.PerfCounterCollector NuGet 패키지

Application Insights 진단 원격 분석

DiagnosticsTelemetryModule 클래스는 Application Insights instrumenation 코드 자체에 오류를 보고합니다. 코드가 성능 카운터에 액세스할 수 없는 경우 또는 ITelemetryInitializer에서 예외를 throw하는 경우를 예로 들 수 있습니다. 이 모듈에서 추적된 원격 분석 추적은 진단 검색에 표시됩니다.

Microsoft.ApplicationInsights.Extensibility.Implementation.Tracing.DiagnosticsTelemetryModule
Microsoft.ApplicationInsights NuGet 패키지. 이 패키지를 설치하는 경우 ApplicationInsights.config 파일은 자동으로 만들어지지 않습니다.

개발자 모드

DeveloperModeWithDebuggerAttachedTelemetryModule 클래스는 디버거가 애플리케이션 프로세스에 연결될 때 강제로 Application Insights TelemetryChannel에서 한번에 원격 분석 항목 하나씩 데이터를 즉시 전송하도록 합니다. 이 디자인은 애플리케이션에서 원격 분석을 추적하는 시점과 Application insights 포털에 나타나는 시점 간의 시간을 줄입니다. CPU 및 네트워크 대역폭에 상당한 오버 헤드가 발생합니다.

Microsoft.ApplicationInsights.WindowsServer.DeveloperModeWithDebuggerAttachedTelemetryModule
Application Insights Windows Server NuGet 패키지

웹 요청 추적

웹 요청 추적은 HTTP 요청의 응답 시간 및 결과 코드를 보고합니다.

Microsoft.ApplicationInsights.Web.RequestTrackingTelemetryModule
Microsoft.ApplicationInsights.Web NuGet 패키지

예외 추적

ExceptionTrackingTelemetryModule 클래스는 웹앱에서 처리되지 않은 예외를 추적합니다. 자세한 내용은 오류 및 예외를 참조하세요.

Microsoft.ApplicationInsights.Web.ExceptionTrackingTelemetryModule입니다.
Microsoft.ApplicationInsights.Web NuGet 패키지
Microsoft.ApplicationInsights.WindowsServer.UnobservedExceptionTelemetryModule: 관찰되지 않은 작업을 추적합니다. 예외.
Microsoft.ApplicationInsights.WindowsServer.UnhandledExceptionTelemetryModule: 작업자 역할, Windows 서비스 및 콘솔 애플리케이션에 대한 처리되지 않은 예외를 추적합니다.
Application Insights Windows Server NuGet 패키지.

EventSource 추적

EventSourceTelemetryModule 클래스를 사용하여 Application Insights에 전송될 EventSource 이벤트를 구성할 수 있습니다. EventSource 이벤트 추적에 대한 자세한 내용은 EventSource 이벤트 사용을 참조하세요.

Microsoft.ApplicationInsights.EventSourceListener.EventSourceTelemetryModule
Microsoft.ApplicationInsights.EventSourceListener

ETW 이벤트 추적

EtwCollectorTelemetryModule 클래스를 사용하여 Application Insights에 추적으로 전송할 ETW 공급자의 이벤트를 구성할 수 있습니다. ETW 이벤트 추적에 대한 자세한 내용은 ETW 이벤트 사용을 참조하세요.

Microsoft.ApplicationInsights.EtwCollector.EtwCollectorTelemetryModule
Microsoft.ApplicationInsights.EtwCollector

Microsoft.ApplicationInsights

Microsoft.ApplicationInsights 패키지는 SDK의 코어 API를 제공합니다. 다른 원격 분석 모듈은 이 API를 사용합니다. 자체 원격 분석을 정의하는 데 사용할 수도 있습니다.

ApplicationInsights.config에 항목이 없습니다.
Microsoft.ApplicationInsights NuGet 패키지. 이 NuGet을 설치하면 .config 파일이 생성되지 않습니다.

원격 분석 채널

원격 분석 채널은 Application Insights 서비스에 대한 원격 분석의 버퍼링과 전송을 관리합니다.

Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.ServerTelemetryChannel은 웹 애플리케이션의 기본 채널입니다. 메모리에서 데이터를 버퍼링하며 더 안정적인 원격 분석 제공을 위해 다시 시도 메커니즘과 로컬 디스크 스토리지를 사용합니다.
Microsoft.ApplicationInsights.InMemoryChannel은 간단한 원격 분석 채널입니다. 다른 채널이 구성되지 않은 경우 사용됩니다.

원격 분석 이니셜라이저(ASP.NET)

원격 분석 이니셜라이저는 원격 분석의 모든 항목과 함께 전송되는 컨텍스트 속성을 설정합니다.

고유한 이니셜라이저를 작성 하여 컨텍스트 속성을 설정할 수 있습니다.

표준 이니셜라이저는 웹 또는 Windows Server NuGet 패키지에서 모두 설정합니다.

AccountIdTelemetryInitializer는 AccountId 속성을 설정합니다.
AuthenticatedUserIdTelemetryInitializer는 JavaScript SDK에서 설정한 AuthenticatedUserId 속성을 설정합니다.
AzureRoleEnvironmentTelemetryInitializer은 RoleName 및 Azure 런타임 환경에서 추출된 정보를 사용하여 모든 원격 분석 항목에 대해 Device 컨텍스트에 대한 RoleInstance 속성을 업데이트합니다.
BuildInfoConfigComponentVersionTelemetryInitializer은 MS 빌드에 의해 생성된 BuildInfo.config 파일로부터 추출된 값을 사용하여 모든 원격 분석 항목에 대한 Component 컨텍스트의 Version 속성을 업데이트합니다.
ClientIpHeaderTelemetryInitializer은 X-Forwarded-For HTTP 헤더 기반의 모든 원격 분석 항목의 Location 컨텍스트의 Ip 속성을 업데이트합니다.
DeviceTelemetryInitializer은 모든 원격 분석 항목에 대한 Device 컨텍스트의 다음 속성을 업데이트합니다.
- Type이 PC로 설정됩니다.
- Id은 웹 애플리케이션이 실행되고 있는 컴퓨터의 도메인 이름으로 설정됩니다.
- OemName은 WMI를 사용하여 Win32_ComputerSystem.Manufacturer 필드에서 추출된 값으로 설정됩니다.
- Model은 WMI를 사용하여 Win32_ComputerSystem.Model 필드에서 추출된 값으로 설정됩니다.
- NetworkType은 NetworkInterface 속성에서 추출된 값으로 설정됩니다.
- Language는 CurrentCulture 속성의 이름으로 설정됩니다.
DomainNameRoleInstanceTelemetryInitializer은 웹 애플리케이션이 실행되는 컴퓨터의 도메인 이름을 사용하여 모든 원격 분석 항목에 대해 Device 컨텍스트의 RoleInstance 속성을 업데이트합니다.
OperationNameTelemetryInitializer는 RequestTelemetry의 Name 속성과 HTTP 메서드를 기준으로 한 모든 원격 분석 항목 Operation 컨텍스트의 Name 속성, ASP.NET MVC 컨트롤러의 이름 및 요청을 처리하기 위해 호출된 작업을 업데이트합니다.
OperationIdTelemetryInitializer 또는 OperationCorrelationTelemetryInitializer는 자동으로 생성된 RequestTelemetry.Id를 사용하여 요청을 처리하는 동안 추적된 모든 원격 분석 항목의 Operation.Id 컨텍스트 속성을 업데이트합니다.
SessionTelemetryInitializer은 사용자의 브라우저에서 실행되는 ApplicationInsights JavaScript 계측 코드에 의해 제공된 ai_session 쿠키의 추출된 값을 사용하여 모든 원격 분석 항목에 대한 Session 컨텍스트의 Id 속성을 업데이트합니다.
SyntheticTelemetryInitializer 또는 SyntheticUserAgentTelemetryInitializer는 가용성 테스트 또는 검색 엔진 봇과 같은 가상 원본에서 요청을 처리하는 경우, 모든 원격 분석 항목의 User, Session 및 Operation 컨텍스트 속성을 업데이트합니다. 기본적으로 메트릭 탐색기는 가상 원격 분석을 표시하지 않습니다.

<Filters> 는 요청의 식별 속성을 설정합니다.
UserTelemetryInitializer은 사용자의 브라우저에서 실행되는 Application insights JavaScript 계측 코드에 의해 제공된 ai_user 쿠키의 추출된 값을 사용하여 모든 원격 분석 항목에 대한 User 컨텍스트의 Id 및 AcquisitionDate속성을 업데이트합니다.
WebTestTelemetryInitializer는 가용성 테스트에서 생성되는 HTTP 요청의 사용자 ID, 세션 ID, 가상 원본 속성을 설정합니다. <Filters> 는 요청의 식별 속성을 설정합니다.

Azure Service Fabric에서 실행되는 .NET 애플리케이션에 대해 Microsoft.ApplicationInsights.ServiceFabric NuGet 패키지를 포함할 수 있습니다. 이 패키지에는 Service Fabric 속성을 원격 분석 항목에 추가하는 FabricTelemetryInitializer 속성이 포함되어 있습니다. 자세한 내용은 이 NuGet 패키지에 의해 추가된 속성에 대한 GitHub 페이지를 참조하세요.

원격 분석 프로세서(ASP.NET)

원격 분석 프로세서는 각 원격 분석 항목을 SDK에서 포털에 보내기 직전에 필터링하고 수정할 수 있습니다.

고유한 원격 분석 프로세서를 작성할 수 있습니다.

적응 샘플링 원격 분석 프로세서(2.0.0-beta3부터)

이 기능은 기본적으로 사용하도록 설정됩니다. 앱에서 상당한 원격 분석을 보내는 경우 이 프로세서는 그 중 일부를 제거합니다.


    <TelemetryProcessors>
      <Add Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.AdaptiveSamplingTelemetryProcessor, Microsoft.AI.ServerTelemetryChannel">
        <MaxTelemetryItemsPerSecond>5</MaxTelemetryItemsPerSecond>
      </Add>
    </TelemetryProcessors>

매개 변수는 알고리즘을 달성하려고 하는 대상을 제공합니다. SDK의 각 인스턴스는 독립적으로 작동합니다. 따라서 서버가 여러 컴퓨터의 클러스터인 경우 원격 분석의 실제 볼륨을 적절하게 곱합니다.

샘플링에 대해 자세히 알아봅니다.

고정 비율 샘플링 원격 분석 프로세서(2.0.0-beta1부터)

표준 샘플링 원격 분석 프로세서도 있습니다(2.0.1부터).


    <TelemetryProcessors>
     <Add Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.SamplingTelemetryProcessor, Microsoft.AI.ServerTelemetryChannel">

     <!-- Set a percentage close to 100/N where N is an integer. -->
     <!-- E.g. 50 (=100/2), 33.33 (=100/3), 25 (=100/4), 20, 1 (=100/100), 0.1 (=100/1000) -->
     <SamplingPercentage>10</SamplingPercentage>
     </Add>
   </TelemetryProcessors>

ConnectionString

연결 문자열 코드 샘플을 참조하세요.

InstrumentationKey

참고 항목

2025년 3월 31일에 계측 키 수집에 대한 지원이 종료됩니다. 계측 키 수집은 계속 작동하지만 더 이상 기능에 대한 업데이트 또는 지원을 제공하지 않습니다. 연결 문자열로 전환하여 새로운 기능을 활용합니다.

이 설정은 데이터가 표시되는 Application Insights 리소스를 결정합니다. 일반적으로 각 애플리케이션에 대해 별도 키를 사용하여 별도 리소스를 만듭니다.

키를 동적으로 설정하려는 경우, 예를 들어 애플리케이션의 결과를 다른 리소스로 보내려는 경우 구성 파일에서 키를 생략하고 대신 코드에 설정할 수 있습니다.

표준 원격 분석 모듈을 포함하여 TelemetryClient의 모든 인스턴스에 대한 키를 설정하려면 ASP.NET 서비스의 global.aspx.cs와 같은 초기화 메서드에서 이 단계를 수행합니다.

using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights;

    protected void Application_Start()
    {
        TelemetryConfiguration configuration = TelemetryConfiguration.CreateDefault();
        configuration.InstrumentationKey = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
        var telemetryClient = new TelemetryClient(configuration);

특정 이벤트 집합을 다른 리소스로 보내려는 경우 특정 원격 분석 클라이언트에 대한 키를 설정할 수 있습니다.


    var tc = new TelemetryClient();
    tc.Context.InstrumentationKey = "----- my key ----";
    tc.TrackEvent("myEvent");
    // ...

새 키를 얻으려면 Application Insights 포털에서 새 리소스를 만듭니다.

애플리케이션 ID 공급자

이 공급자는 v2.6.0부터 사용할 수 있습니다.

이 공급자의 목적은 계측 키에 따라 애플리케이션 ID를 조회하는 것입니다. 애플리케이션 ID는 RequestTelemetry 및 DependencyTelemetry에 포함되며 포털에서 상관 관계를 확인하는 데 사용됩니다.

이 기능은 코드 또는 구성 파일에서 TelemetryConfiguration.ApplicationIdProvider를 설정하여 사용할 수 있습니다.

인터페이스: IApplicationIdProvider

public interface IApplicationIdProvider
{
    bool TryGetApplicationId(string instrumentationKey, out string applicationId);
}

Microsoft.ApplicationInsights SDK에서 ApplicationInsightsApplicationIdProvider 및 DictionaryApplicationIdProvider라는 두 가지 구현을 제공합니다.

ApplicationInsightsApplicationIdProvider

이 래퍼는 프로필 API용입니다. 요청을 스로틀하고 결과를 캐시합니다.

이 공급자는 Microsoft.ApplicationInsights.DependencyCollector 또는 Microsoft.ApplicationInsights.Web 중 하나를 설치할 때 사용자 구성 파일에 추가됩니다.

이 클래스에는 선택적 속성 ProfileQueryEndpoint가 있습니다. 기본적으로 https://dc.services.visualstudio.com/api/profiles/{0}/appId로 설정됩니다. 이 구성에 대한 프록시를 구성해야 하는 경우 기준 주소를 프록시하고 "/api/profiles/{0}/appId"를 포함하는 것이 좋습니다. {0}은 요청에 따라 런타임에 계측 키로 대체됩니다.

ApplicationInsights.config를 통한 구성 예제

<ApplicationInsights>
    ...
    <ApplicationIdProvider Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.ApplicationInsightsApplicationIdProvider, Microsoft.ApplicationInsights">
        <ProfileQueryEndpoint>https://dc.services.visualstudio.com/api/profiles/{0}/appId</ProfileQueryEndpoint>
    </ApplicationIdProvider>
    ...
</ApplicationInsights>

코드를 통한 구성 예제

TelemetryConfiguration.Active.ApplicationIdProvider = new ApplicationInsightsApplicationIdProvider();

DictionaryApplicationIdProvider

이 정적 공급자는 구성된 계측 키/애플리케이션 ID 쌍을 사용합니다.

이 클래스에는 계측 키/애플리케이션 ID 쌍의 Dictionary<string,string>에 해당하는 Defined 속성이 있습니다.

이 클래스는 선택적 Next 속성을 포함하고 있으며, 구성에 없는 계측 키가 요청되는 경우 다른 공급자에서 이 속성을 사용하도록 구성하는 데 사용할 수 있습니다.

ApplicationInsights.config를 통한 구성 예제

<ApplicationInsights>
    ...
    <ApplicationIdProvider Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.DictionaryApplicationIdProvider, Microsoft.ApplicationInsights">
        <Defined>
            <Type key="InstrumentationKey_1" value="ApplicationId_1"/>
            <Type key="InstrumentationKey_2" value="ApplicationId_2"/>
        </Defined>
        <Next Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.ApplicationInsightsApplicationIdProvider, Microsoft.ApplicationInsights" />
    </ApplicationIdProvider>
    ...
</ApplicationInsights>

코드를 통한 구성 예제

TelemetryConfiguration.Active.ApplicationIdProvider = new DictionaryApplicationIdProvider{
 Defined = new Dictionary<string, string>
    {
        {"InstrumentationKey_1", "ApplicationId_1"},
        {"InstrumentationKey_2", "ApplicationId_2"}
    }
};

ASP.NET 애플리케이션에 대한 스냅샷 컬렉션 구성

ASP.NET 애플리케이션에 대한 스냅샷 컬렉션을 구성합니다.

다음 단계

API에 대해 자세히 알아보세요.

다음을 통해 공유

ApplicationInsights.config 또는 .xml로 Application Insights SDK 구성

원격 분석 모듈(ASP.NET)

종속성 추적

성능 수집기

Application Insights 진단 원격 분석

개발자 모드

웹 요청 추적

예외 추적

EventSource 추적

ETW 이벤트 추적

Microsoft.ApplicationInsights

원격 분석 채널

원격 분석 이니셜라이저(ASP.NET)

원격 분석 프로세서(ASP.NET)

적응 샘플링 원격 분석 프로세서(2.0.0-beta3부터)

고정 비율 샘플링 원격 분석 프로세서(2.0.0-beta1부터)

ConnectionString

InstrumentationKey

애플리케이션 ID 공급자

인터페이스: IApplicationIdProvider

ApplicationInsightsApplicationIdProvider

ApplicationInsights.config를 통한 구성 예제

코드를 통한 구성 예제

DictionaryApplicationIdProvider

ApplicationInsights.config를 통한 구성 예제

코드를 통한 구성 예제

ASP.NET 애플리케이션에 대한 스냅샷 컬렉션 구성

다음 단계

피드백

추가 리소스