다음을 통해 공유

ASP.NET Core 애플리케이션용 Application Insights

  • 아티클

이 문서에서는 Application Insights를 ASP.NET Core 애플리케이션에 사용하도록 설정하고 구성하는 방법에 대해 설명합니다.

참고 항목

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

Application Insights에서 ASP.NET Core 애플리케이션에서 다음 원격 분석을 수집할 수 있습니다.

  • 요청
  • 종속성
  • 예외
  • 성능 카운터
  • 하트비트
  • 로그

MVC 애플리케이션 예를 사용합니다. 작업자 서비스를 사용하는 경우 작업자 서비스 애플리케이션에 대한 Application Insights의 지침을 따릅니다.

OpenTelemetry 기반 .NET 제품을 사용할 수 있습니다. 자세한 내용은 OpenTelemetry 개요를 참조하세요.

참고 항목

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

참고 항목

독립 실행형 ILogger 공급자를 사용하려면 Microsoft.Extensions.Logging.ApplicationInsight를 사용합니다.

지원되는 시나리오

ASP.NET Core용 Application Insights SDK는 실행되는 위치 또는 방법에 관계없이 애플리케이션을 모니터링할 수 있습니다. 애플리케이션이 실행 중이고 Azure에 네트워크로 연결되어 있는 경우 원격 분석을 수집할 수 있습니다. Application Insights 모니터링은 .NET Core가 지원되는 모든 곳에서 지원되며 다음 시나리오를 다룹니다.

  • 운영 체제: Windows, Linux 또는 Mac
  • 호스팅 메서드: In process 또는 out of process
  • 배포 방법: 프레임워크 종속 또는 자체 포함
  • 웹 서버: IIS(Internet Information Server) 또는 Kestrel
  • 호스팅 플랫폼: Azure App Service, Azure Virtual Machines, Docker 및 AKS(Azure Kubernetes Service)의 Web Apps 기능
  • .NET 버전: 미리 보기에는 없지만 공식적으로 지원되는 모든 .NET 버전
  • IDE: Visual Studio, Visual Studio Code 또는 명령줄

필수 조건

다음 작업을 수행해야 합니다.

  • 작동하는 ASP.NET Core 애플리케이션. ASP.NET Core 애플리케이션을 만들어야 하는 경우 이 ASP.NET Core 자습서를 따르세요.
  • Application Insights NuGet 패키지의 지원되는 버전에 대한 참조입니다.
  • 유효한 Application Insights 연결 문자열. 이 키는 원격 분석을 Application Insights로 보내는 데 필요합니다. 연결 문자열을 가져오기 위해 새 Application Insights 리소스를 만들어야 하는 경우 Application Insights 리소스 만들기를 참조하세요.

Application Insights 서버 쪽 원격 분석 사용(Visual Studio 사용)

Mac용 Visual Studio의 경우 수동 지침을 사용합니다. 이 절차는 Windows 버전의 Visual Studio에서만 지원됩니다.

  1. Visual Studio에서 새 프로젝트를 엽니다.

  2. 프로젝트>Application Insights 원격 분석 추가로 이동합니다.

  3. Azure Application Insights>다음을 선택합니다.

  4. 구독 및 Application Insights 인스턴스를 선택합니다. 또는 새로 만들기를 사용하여 새 인스턴스를 만들 수 있습니다. 다음을 선택합니다.

  5. Application Insights 연결 문자열을 추가하거나 확인합니다. 이전 단계에서 선택한 항목에 따라 미리 채워져야 합니다. 마침을 선택합니다.

  6. Application Insights가 프로젝트에 추가되면 안정적인 최신 릴리스의 SDK를 사용하고 있는지 확인합니다. 프로젝트>NuGet 패키지 관리>Microsoft.ApplicationInsights.AspNetCore로 차례로 이동합니다. 필요한 경우 업데이트를 선택합니다.

    업데이트할 Application Insights 패키지를 선택할 위치를 보여 주는 스크린샷.

Application Insights 서버 쪽 원격 분석 사용(Visual Studio 사용 안 함)

  1. ASP.NET Core용 Application Insights SDK NuGet 패키지를 설치합니다.

    항상 안정적인 최신 버전을 사용하는 것이 좋습니다. 오픈 소스 GitHub 리포지토리에서 SDK에 대한 전체 릴리스 정보를 확인합니다.

    다음 코드 샘플은 프로젝트의 .csproj 파일에 추가할 변경 내용을 보여 줍니다.

    <ItemGroup>
    <PackageReference Include="Microsoft.ApplicationInsights.AspNetCore" Version="2.21.0" />
</ItemGroup>

  2. startup.cs 또는 program.cs 클래스에 AddApplicationInsightsTelemetry()를 추가합니다. 선택은 .NET Core 버전에 따라 다릅니다.

    다음 예제와 같이 builder.Services.AddApplicationInsightsTelemetry();를 Program 클래스의 WebApplication.CreateBuilder() 메서드 다음에 추가합니다.

    // This method gets called by the runtime. Use this method to add services to the container.
var builder = WebApplication.CreateBuilder(args);

// The following line enables Application Insights telemetry collection.
builder.Services.AddApplicationInsightsTelemetry();

// This code adds other services for your application.
builder.Services.AddMvc();

var app = builder.Build();

  3. 연결 문자열을 설정합니다.

    AddApplicationInsightsTelemetry에 대한 ApplicationInsightsServiceOptions 인수의 일부로 연결 문자열을 제공할 수 있지만 구성에서 연결 문자열을 지정하는 것이 좋습니다. 다음 코드 샘플에서는 appsettings.json에서 연결 문자열을 지정하는 방법을 보여줍니다. 게시하는 동안 appsettings.json이 애플리케이션 루트 폴더에 복사되었는지 확인합니다.

    {
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "ApplicationInsights": {
    "ConnectionString": "Copy connection string from Application Insights Resource Overview"
  }
}

    또는 APPLICATIONINSIGHTS_CONNECTION_STRING 환경 변수에서 연결 문자열을 지정하거나 JSON 구성 파일에서 ApplicationInsights:ConnectionString을 지정합니다.

    예시:

    • SET ApplicationInsights:ConnectionString = <Copy connection string from Application Insights Resource Overview>
    • SET APPLICATIONINSIGHTS_CONNECTION_STRING = <Copy connection string from Application Insights Resource Overview>
    • 일반적으로 APPLICATIONINSIGHTS_CONNECTION_STRING은 Web Apps에서 사용됩니다. 또한 이 SDK가 지원되는 모든 곳에서 사용할 수 있습니다.

    참고 항목

    코드에 지정된 연결 문자열은 다른 옵션보다 우선 적용되는 APPLICATIONINSIGHTS_CONNECTION_STRING 환경 변수보다 우선 적용됩니다.

사용자 비밀 및 기타 구성 공급자

연결 문자열을 ASP.NET Core 사용자 비밀에 저장하거나 다른 구성 공급자에서 검색하려면 Microsoft.Extensions.Configuration.IConfiguration 매개 변수를 사용하여 오버로드를 사용하면 됩니다. 예 매개 변수는 services.AddApplicationInsightsTelemetry(Configuration);입니다.

Microsoft.ApplicationInsights.AspNetCore 버전 2.15.0 이상에서 services.AddApplicationInsightsTelemetry()를 호출하면 애플리케이션의 Microsoft.Extensions.Configuration.IConfiguration에서 자동으로 연결 문자열을 읽습니다. IConfiguration을 명시적으로 제공할 필요는 없습니다.

IConfiguration이 여러 공급자에서 구성을 로드한 경우 공급자가 추가되는 순서에 관계없이 services.AddApplicationInsightsTelemetry는 appsettings.json에서 구성의 우선 순위를 지정합니다. services.AddApplicationInsightsTelemetry(IConfiguration) 메서드를 사용하여 appsettings.json에 대한 이 우선 처리 없이 IConfiguration에서 구성을 읽으세요.

애플리케이션 실행

애플리케이션을 실행하고 이에 대한 요청을 수행합니다. 이제 원격 분석이 Application Insights로 이동합니다. Application Insights SDK는 다음 원격 분석과 함께 애플리케이션에 대한 들어오는 웹 요청을 자동으로 수집합니다.

라이브 메트릭

라이브 메트릭을 사용하면 Application Insights를 통한 애플리케이션 모니터링이 올바르게 구성되었는지 신속하게 확인할 수 있습니다. 원격 분석이 Azure Portal에 표시되는 데 몇 분 정도 걸릴 수 있지만 라이브 메트릭 창에는 실행 중인 프로세스의 CPU 사용량이 거의 실시간으로 표시됩니다. 또한 요청, 종속성, 추적 등의 다른 원격 분석 데이터도 표시할 수 있습니다.

모든 .NET 애플리케이션에 대해 코드를 사용하여 라이브 메트릭 사용

참고 항목

라이브 메트릭은 .NET 애플리케이션에 권장되는 지침을 사용하여 온보딩할 때 기본적으로 사용하도록 설정됩니다.

수동으로 라이브 메트릭을 구성하려면 다음을 수행합니다.

  1. NuGet 패키지 Microsoft.ApplicationInsights.PerfCounterCollector를 설치합니다.
  2. 다음 샘플 콘솔 앱 코드는 라이브 메트릭을 설정하는 방법을 보여 줍니다.
using Microsoft.ApplicationInsights;
using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.QuickPulse;

// Create a TelemetryConfiguration instance.
TelemetryConfiguration config = TelemetryConfiguration.CreateDefault();
config.InstrumentationKey = "INSTRUMENTATION-KEY-HERE";
QuickPulseTelemetryProcessor quickPulseProcessor = null;
config.DefaultTelemetrySink.TelemetryProcessorChainBuilder
    .Use((next) =>
    {
        quickPulseProcessor = new QuickPulseTelemetryProcessor(next);
        return quickPulseProcessor;
    })
    .Build();

var quickPulseModule = new QuickPulseTelemetryModule();

// Secure the control channel.
// This is optional, but recommended.
quickPulseModule.AuthenticationApiKey = "YOUR-API-KEY-HERE";
quickPulseModule.Initialize(config);
quickPulseModule.RegisterTelemetryProcessor(quickPulseProcessor);

// Create a TelemetryClient instance. It is important
// to use the same TelemetryConfiguration here as the one
// used to set up live metrics.
TelemetryClient client = new TelemetryClient(config);

// This sample runs indefinitely. Replace with actual application logic.
while (true)
{
    // Send dependency and request telemetry.
    // These will be shown in live metrics.
    // CPU/Memory Performance counter is also shown
    // automatically without any additional steps.
    client.TrackDependency("My dependency", "target", "http://sample",
        DateTimeOffset.Now, TimeSpan.FromMilliseconds(300), true);
    client.TrackRequest("My Request", DateTimeOffset.Now,
        TimeSpan.FromMilliseconds(230), "200", true);
    Task.Delay(1000).Wait();
}

위의 샘플은 콘솔 앱에 대한 것이지만 모든 .NET 애플리케이션에서 동일한 코드를 사용할 수 있습니다. 원격 분석 모듈을 자동으로 수집하기 위해 다른 원격 분석 모듈을 사용하도록 설정한 경우 해당 모듈을 초기화하는 데 사용되는 것과 동일한 구성이 라이브 메트릭 모듈에도 사용되는지 확인하는 것이 중요합니다.

ILogger 로그

기본 구성은 ILogger Warning 로그 및 더 심각한 로그를 수집합니다. 자세한 내용은 ILogger 로그 컬렉션을 사용자 지정하려면 어떻게 해야 하나요?를 참조하세요.

종속성

종속성 수집은 기본적으로 사용하도록 설정됩니다. Application Insights의 종속성 추적에서는 자동으로 수집되는 종속성에 대해 설명하고 수동 추적을 수행하는 단계도 포함되어 있습니다.

성능 카운터

ASP.NET Core의 성능 카운터는 제한적으로 지원됩니다.

  • SDK 버전 2.4.1 이상에서는 애플리케이션이 Web Apps(Windows)에서 실행되는 경우 성능 카운터를 수집합니다.
  • SDK 버전 2.7.1 이상에서는 애플리케이션이 Windows에서 실행되고 netstandard2.0 이상을 대상으로 하는 경우 성능 카운터를 수집합니다.
  • .NET Framework를 대상으로 하는 애플리케이션의 경우 모든 버전의 SDK에서 성능 카운터를 지원합니다.
  • SDK 버전 2.8.0 이상에서는 Linux의 CPU/메모리 카운터를 지원합니다. 다른 카운터는 Linux에서 지원되지 않습니다. Linux 및 기타 비 Windows 환경에서 시스템 카운터를 가져오려면 EventCounters를 사용합니다.

EventCounter

기본적으로 EventCounterCollectionModule는 활성화됩니다. 수집할 카운터 목록을 구성하는 방법을 알아보려면 EventCounters 소개를 참조하세요.

HTTP를 통해 데이터 보강

HttpContext.Features.Get<RequestTelemetry>().Properties["myProp"] = someData

웹 애플리케이션에 대한 클라이언트 쪽 원격 분석 사용

위의 단계는 서버 쪽 원격 분석 수집을 시작하는 데 도움이 됩니다. 애플리케이션에 클라이언트 쪽 구성 요소가 있는 경우 다음 단계에 따라 구성별 JavaScript(웹) SDK 로더 스크립트 삽입을 사용하여 사용 원격 분석 수집을 시작합니다.

  1. _ViewImports.cshtml에서 다음 injection을 추가합니다.

    @inject Microsoft.ApplicationInsights.AspNetCore.JavaScriptSnippet JavaScriptSnippet

  2. _Layout.cshtml에서 HtmlHelper를 <head> 섹션 끝이지만 다른 스크립트 앞에 삽입합니다. 페이지에서 사용자 지정 JavaScript 원격 분석을 보고하려는 경우 다음 코드 조각 뒤에 삽입합니다.

    @Html.Raw(JavaScriptSnippet.FullScript)
</head>

FullScript를 사용하는 대신 ScriptBody는 ASP.NET Core용 Application Insights SDK 버전 2.14부터 사용할 수 있습니다. 콘텐츠 보안 정책을 설정하기 위해 <script> 태그를 제어해야 하는 경우 ScriptBody를 사용합니다.

<script> // apply custom changes to this script tag.
 @Html.Raw(JavaScriptSnippet.ScriptBody)
</script>

앞에서 참조한 .cshtml 파일 이름은 기본 MVC 애플리케이션 템플릿에서 가져온 것입니다. 궁극적으로 애플리케이션에 대한 클라이언트 쪽 모니터링을 올바르게 사용하도록 설정하려면 모니터링하려는 애플리케이션의 각 페이지에 있는 <head> 섹션에 JavaScript JavaScript(웹) SDK 로더 스크립트가 나타나야 합니다. 클라이언트 쪽 모니터링을 사용하도록 설정하려면 애플리케이션 템플릿의 _Layout.cshtml에 JavaScript JavaScript(웹) SDK 로더 스크립트를 추가합니다.

프로젝트에 _Layout.cshtml이 포함되지 않은 경우 앱 내의 모든 페이지의 <head>를 하는 동일한 파일에 JavaScript JavaScript(웹) SDK 로더 스크립트를 추가하여 클라이언트 쪽 모니터링을 계속 추가할 수 있습니다. 또는 JavaScript(웹) SDK 로더 스크립트를 여러 페이지에 추가할 수 있지만 권장되지 않습니다.

참고 항목

JavaScript 삽입은 기본 구성 환경을 제공합니다. 연결 문자열 설정 이외의 구성이 필요한 경우 설명대로 자동 삽입을 제거하고 수동으로 JavaScript SDK를 추가해야 합니다.

Application Insights SDK 구성

ASP.NET Core용 Application Insights SDK를 사용자 지정하여 기본값 구성을 변경할 수 있습니다. Application Insights ASP.NET SDK 사용자는 ApplicationInsights.config를 사용하거나 TelemetryConfiguration.Active를 수정하여 구성을 변경하는 데 익숙할 수 있습니다. ASP.NET Core에서는 달리 지시하는 경우를 제외하고 Startup.cs 클래스의 ConfigureServices() 메서드에서 거의 모든 구성 변경을 수행합니다. 자세한 내용은 다음 섹션에서 설명합니다.

참고 항목

ASP.NET Core 애플리케이션에서 TelemetryConfiguration.Active를 수정하여 구성을 변경하는 것은 지원되지 않습니다.

ApplicationInsightsServiceOptions 사용

몇 가지 일반적인 설정은 다음 예제와 같이 ApplicationInsightsServiceOptions를 AddApplicationInsightsTelemetry에 전달하여 수정할 수 있습니다.

var builder = WebApplication.CreateBuilder(args);

var aiOptions = new Microsoft.ApplicationInsights.AspNetCore.Extensions.ApplicationInsightsServiceOptions();

// Disables adaptive sampling.
aiOptions.EnableAdaptiveSampling = false;

// Disables live metrics (also known as QuickPulse).
aiOptions.EnableQuickPulseMetricStream = false;

builder.Services.AddApplicationInsightsTelemetry(aiOptions);
var app = builder.Build();

다음 표에는 ApplicationInsightsServiceOptions 설정의 전체 목록이 있습니다.

설정 설명 기본값
EnablePerformanceCounterCollectionModule PerformanceCounterCollectionModule 사용/사용 안 함. True
EnableRequestTrackingTelemetryModule RequestTrackingTelemetryModule 사용/사용 안 함. True
EnableEventCounterCollectionModule EventCounterCollectionModule 사용/사용 안 함. True
EnableDependencyTrackingTelemetryModule DependencyTrackingTelemetryModule 사용/사용 안 함. True
EnableAppServicesHeartbeatTelemetryModule AppServicesHeartbeatTelemetryModule 사용/사용 안 함. True
EnableAzureInstanceMetadataTelemetryModule AzureInstanceMetadataTelemetryModule 사용/사용 안 함. True
EnableQuickPulseMetricStream LiveMetrics 기능 사용/사용 안 함. True
EnableAdaptiveSampling 적응 샘플링 사용/사용 안 함. True
EnableHeartbeat 하트비트 기능을 사용/사용하지 않도록 설정합니다. 해당하는 경우 .NET 버전 및 Azure 환경 정보와 같은 런타임에 대한 정보와 함께 HeartbeatState라는 사용자 지정 메트릭을 주기적으로(기본값 15분) 보냅니다. True
AddAutoCollectedMetricExtractor AutoCollectedMetrics extractor를 사용/사용하지 않도록 설정합니다. 이 원격 분석 프로세서는 샘플링이 수행되기 전에 요청/종속성에 대한 사전 집계된 메트릭을 보냅니다. True
RequestCollectionOptions.TrackExceptions 요청 수집 모듈에서 처리되지 않은 예외 추적에 대한 보고 사용/사용 안 함. netstandard2.0에서는 False입니다(예외는 ApplicationInsightsLoggerProvider로 추적되기 때문입니다). 그렇지 않으면 True입니다.
EnableDiagnosticsTelemetryModule DiagnosticsTelemetryModule 사용/사용 안 함. 사용하지 않도록 설정하면 EnableHeartbeat, EnableAzureInstanceMetadataTelemetryModule 및 EnableAppServicesHeartbeatTelemetryModule 설정이 무시됩니다. True

최신 목록은 ApplicationInsightsServiceOptions의 구성 가능한 설정을 참조하세요.

Microsoft.ApplicationInsights.AspNetCore SDK 2.15.0 이상에 대한 구성 권장 사항

Microsoft.ApplicationInsights.AspNetCore SDK 버전 2.15.0 이상에서 ConnectionString을 포함하여 ApplicationInsightsServiceOptions에서 사용 가능한 모든 설정을 구성합니다. 애플리케이션의 IConfiguration 인스턴스를 사용합니다. 설정은 다음 예와 같이 섹션 ApplicationInsights 아래에 있어야 합니다. appsettings.json의 다음 섹션에서는 연결 문자열을 구성하고 적응 샘플링과 성능 카운터 수집을 사용하지 않습니다.

{
    "ApplicationInsights": {
    "ConnectionString": "Copy connection string from Application Insights Resource Overview",
    "EnableAdaptiveSampling": false,
    "EnablePerformanceCounterCollectionModule": false
    }
}

builder.Services.AddApplicationInsightsTelemetry(aiOptions)(ASP.NET Core 6.0의 경우) 또는 services.AddApplicationInsightsTelemetry(aiOptions)(ASP.NET Core 3.1 이하의 경우)인 경우 Microsoft.Extensions.Configuration.IConfiguration의 설정을 재정의합니다.

샘플링

ASP.NET Core용 Application Insights SDK는 고정 비율 및 적응 샘플링을 모두 지원합니다. 기본적으로 적응 샘플링이 사용됩니다.

자세한 내용은 ASP.NET Core 애플리케이션에 대한 적응 샘플링 구성을 참조하세요.

TelemetryInitializer 추가

더 많은 정보로 원격 분석을 보강하려면 원격 분석 이니셜라이저를 사용합니다.

다음 코드와 같이 새 TelemetryInitializer를 DependencyInjection 컨테이너에 추가합니다. SDK에서 DependencyInjection 컨테이너에 추가된 모든 TelemetryInitializer를 자동으로 선택합니다.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>();

var app = builder.Build();

참고 항목

builder.Services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>();는 간단한 이니셜라이저에서 작동합니다. 그 외의 경우 builder.Services.AddSingleton(new MyCustomTelemetryInitializer() { fieldName = "myfieldName" });이 필요합니다.

TelemetryInitializer 제거

원격 분석 이니셜라이저는 기본적으로 제공됩니다. 모든 또는 특정 원격 분석 이니셜라이저를 제거하려면 AddApplicationInsightsTelemetry()를 호출한 후에 다음 샘플 코드를 사용합니다.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// Remove a specific built-in telemetry initializer
var tiToRemove = builder.Services.FirstOrDefault<ServiceDescriptor>
                    (t => t.ImplementationType == typeof(AspNetCoreEnvironmentTelemetryInitializer));
if (tiToRemove != null)
{
    builder.Services.Remove(tiToRemove);
}

// Remove all initializers
// This requires importing namespace by using Microsoft.Extensions.DependencyInjection.Extensions;
builder.Services.RemoveAll(typeof(ITelemetryInitializer));

var app = builder.Build();

원격 분석 프로세서 추가

IServiceCollection에서 확장 메서드 AddApplicationInsightsTelemetryProcessor를 사용하여 사용자 지정 원격 분석 프로세서를 TelemetryConfiguration에 추가할 수 있습니다. 원격 분석 프로세서는 고급 필터링 시나리오에서 사용합니다. 다음 예제를 사용합니다.

var builder = WebApplication.CreateBuilder(args);

// ...
builder.Services.AddApplicationInsightsTelemetry();
builder.Services.AddApplicationInsightsTelemetryProcessor<MyFirstCustomTelemetryProcessor>();

// If you have more processors:
builder.Services.AddApplicationInsightsTelemetryProcessor<MySecondCustomTelemetryProcessor>();

var app = builder.Build();

기본 TelemetryModules 구성 또는 제거

Application Insights는 사용자가 수동으로 추적할 필요 없이 특정 워크로드에 대한 원격 분석 데이터를 자동으로 수집합니다.

다음 자동 수집 모듈은 기본적으로 사용하도록 설정되어 있습니다. 이러한 자동 수집 모듈은 원격 분석을 자동으로 수집해야 합니다. 자동 수집 모듈을 사용하지 않도록 설정하거나 해당 기본 동작을 변경하도록 구성할 수 있습니다.

  • RequestTrackingTelemetryModule: 들어오는 웹 요청에서 RequestTelemetry를 수집합니다.
  • DependencyTrackingTelemetryModule: 나가는 http 호출 및 sql 호출에서 DependencyTelemetry를 수집합니다.
  • PerformanceCollectorModule: Windows PerformanceCounters를 수집합니다.
  • QuickPulseTelemetryModule: 라이브 메트릭 창에 표시할 원격 분석을 수집합니다.
  • AppServicesHeartbeatTelemetryModule: 애플리케이션이 호스트되는 App Service 환경에 대한 하트비트(사용자 지정 메트릭으로 전송됨)를 수집합니다.
  • AzureInstanceMetadataTelemetryModule: 애플리케이션이 호스트되는 Azure VM 환경에 대한 하트비트(사용자 지정 메트릭으로 전송됨)를 수집합니다.
  • EventCounterCollectionModule: EventCounters를 수집합니다. 이 모듈은 새로운 기능이며, SDK 버전 2.8.0 이상에서 사용할 수 있습니다.

기본 TelemetryModule을 구성하려면 다음 예제와 같이 IServiceCollection에서 ConfigureTelemetryModule<T> 확장 메서드를 사용합니다.

using Microsoft.ApplicationInsights.DependencyCollector;
using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// The following configures DependencyTrackingTelemetryModule.
// Similarly, any other default modules can be configured.
builder.Services.ConfigureTelemetryModule<DependencyTrackingTelemetryModule>((module, o) =>
        {
            module.EnableW3CHeadersInjection = true;
        });

// The following removes all default counters from EventCounterCollectionModule, and adds a single one.
builder.Services.ConfigureTelemetryModule<EventCounterCollectionModule>((module, o) =>
        {
            module.Counters.Add(new EventCounterCollectionRequest("System.Runtime", "gen-0-size"));
        });

// The following removes PerformanceCollectorModule to disable perf-counter collection.
// Similarly, any other default modules can be removed.
var performanceCounterService = builder.Services.FirstOrDefault<ServiceDescriptor>(t => t.ImplementationType == typeof(PerformanceCollectorModule));
if (performanceCounterService != null)
{
    builder.Services.Remove(performanceCounterService);
}

var app = builder.Build();

버전 2.12.2 이상에서 ApplicationInsightsServiceOptions에는 기본 모듈을 비활성화하는 손쉬운 옵션이 포함되어 있습니다.

원격 분석 채널 구성

기본 원격 분석 채널은 ServerTelemetryChannel입니다. 다음 예제에서는 이를 재정의하는 방법을 설명합니다.

using Microsoft.ApplicationInsights.Channel;

var builder = WebApplication.CreateBuilder(args);

// Use the following to replace the default channel with InMemoryChannel.
// This can also be applied to ServerTelemetryChannel.
builder.Services.AddSingleton(typeof(ITelemetryChannel), new InMemoryChannel() {MaxTelemetryBufferCapacity = 19898 });

builder.Services.AddApplicationInsightsTelemetry();

var app = builder.Build();

참고 항목

버퍼를 플러시하려면 데이터 플러시를 참조하세요. 예를 들어, 종료되는 애플리케이션에서 SDK를 사용하는 경우 버퍼를 플러시해야 할 수 있습니다.

동적으로 원격 분석 사용 안 함

원격 분석을 조건부로, 동적으로 사용하지 않도록 설정하려는 경우 코드의 어느 위치에서나 ASP.NET Core 종속성 삽입 컨테이너를 사용하여 TelemetryConfiguration 인스턴스를 확인하고 이 인스턴스에 DisableTelemetry 플래그를 설정할 수 있습니다.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// any custom configuration can be done here:
builder.Services.Configure<TelemetryConfiguration>(x => x.DisableTelemetry = true);

var app = builder.Build();

앞의 코드 샘플은 Application Insights에 원격 분석을 보내는 것을 방지합니다. 자동 수집 모듈이 원격 분석을 수집하는 것을 방지하지는 않습니다. 특정 자동 수집 모듈을 제거하려는 경우 원격 분석 모듈 제거를 참조하세요.

자주 묻는 질문

이 섹션에서는 일반적인 질문에 대한 답변을 제공합니다.

Application Insights에서 ASP.NET Core 3.1을 지원하나요?

ASP.NET Core 3.1은 Microsoft에서 더 이상 지원되지 않습니다.

ASP.NET Core용 Application Insights SDK 버전 2.8.0 및 Visual Studio 2019 이상은 ASP.NET Core 3.1 애플리케이션과 함께 사용할 수 있습니다.

자동으로 수집되지 않는 원격 분석을 추적하려면 어떻게 해야 하나요?

생성자 삽입을 사용하여 TelemetryClient의 인스턴스를 가져오고, 이 인스턴스에 필요한 TrackXXX() 메서드를 호출합니다. ASP.NET Core 애플리케이션에서 새 TelemetryClient 또는 TelemetryConfiguration 인스턴스를 만들지 않는 것이 좋습니다. TelemetryClient의 싱글톤 인스턴스는 나머지 원격 분석과 TelemetryConfiguration을 공유하는 DependencyInjection 컨테이너에 이미 등록되어 있습니다. 나머지 원격 분석과 별도의 구성이 필요한 경우에만 새 TelemetryClient 인스턴스를 만듭니다.

다음 예에서는 컨트롤러에서 더 많은 원격 분석을 추적하는 방법을 보여줍니다.

using Microsoft.ApplicationInsights;

public class HomeController : Controller
{
    private TelemetryClient telemetry;

    // Use constructor injection to get a TelemetryClient instance.
    public HomeController(TelemetryClient telemetry)
    {
        this.telemetry = telemetry;
    }

    public IActionResult Index()
    {
        // Call the required TrackXXX method.
        this.telemetry.TrackEvent("HomePageRequested");
        return View();
    }

Application Insights의 사용자 지정 데이터 보고에 대한 자세한 내용은 Application Insights 사용자 지정 메트릭 API 참조를 참조하세요. GetMetric API를 사용하여 사용자 지정 메트릭을 Application Insights에 보내는 데 비슷한 방법을 사용할 수 있습니다.

원격 분석에서 요청 및 응답 본문을 캡처하려면 어떻게 해야 하나요?

ASP.NET Core는 ILogger을(를) 통해 HTTP 요청/응답 정보(본문 포함)를 로깅하는 기본 제공 지원을 제공합니다. 이를 활용하는 것이 좋습니다. 이로 인해 잠재적으로 원격 분석에서 PII(개인 식별 정보)가 노출될 수 있으며 비용(성능 비용 및 Application Insights 청구)이 크게 증가할 수 있으므로 이를 사용하기 전에 위험을 신중하게 평가합니다.

ILogger 로그 수집을 사용자 지정하려면 어떻게 할까요?

Application Insights의 기본 설정은 경고 및 더 심각한 로그만 캡처하는 것입니다.

다음과 같이 Application Insights 공급자의 로깅 구성을 변경하여 정보 및 덜 심각한 로그를 캡처합니다.

{
  "Logging": {
    "LogLevel": {
      "Default": "Information"
    },
    "ApplicationInsights": {
      "LogLevel": {
        "Default": "Information"
      }
    }
  },
  "ApplicationInsights": {
    "ConnectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000"
  }
}

다음 예로 인해 Application Insights 공급자가 Information 로그를 캡처하지는 않는다는 점에 주의해야 합니다. 캡처하지 않는 이유는 SDK가 ApplicationInsights에 Warning 로그 및 더 심각한 로그만 캡처하도록 지시하는 기본 로깅 필터를 추가하기 때문입니다. Application Insights에는 명시적 재정의가 필요합니다.

{
  "Logging": {
    "LogLevel": {
      "Default": "Information"
    }
  }
}

자세한 내용은 ILogger 구성을 참조하세요.

일부 Visual Studio 템플릿은 IWebHostBuilder에서 UseApplicationInsights() 확장 메서드를 사용하여 Application Insights를 사용하도록 설정했습니다. 이 사용법이 여전히 유효한가요?

UseApplicationInsights() 확장 메서드는 계속 지원되지만 Application Insights SDK 버전 2.8.0 이상에서는 더 이상 사용되지 않는 것으로 표시됩니다. SDK의 다음 주 버전에서는 제거되었습니다. Application Insights 원격 분석을 사용하도록 설정하려면 일부 구성을 제어하는 오버로드를 제공하는 AddApplicationInsightsTelemetry()를 사용합니다. 또한 ASP.NET Core 3.X 앱에서 services.AddApplicationInsightsTelemetry()는 Application Insights를 사용하도록 설정하는 유일한 방법입니다.

내 ASP.NET Core 애플리케이션을 Web Apps에 배포하고 있습니다. Web Apps에서 Application Insights 확장을 계속 사용하도록 설정해야 하나요?

이 문서에서 보여 주듯이 SDK가 빌드 시간에 설치되는 경우 App Service 포털에서 Application Insights 확장을 사용하도록 설정할 필요가 없습니다. 확장이 설치된 경우 SDK가 이미 추가되었음을 검색하면 백오프됩니다. 확장에서 Application Insights를 사용하도록 설정하는 경우 SDK를 설치하고 업데이트할 필요가 없습니다. 그러나 이 문서의 지침에 따라 Application Insights를 사용하도록 설정하면 다음과 같은 이유로 유연성이 향상됩니다.

  • Application Insights 원격 분석은 다음에서 계속 작동합니다.
    • Windows, Linux 및 Mac을 포함한 모든 운영 체제
    • 자체 포함 또는 프레임워크 종속성을 포함한 모든 게시 모드
    • 전체 .NET Framework를 포함한 모든 대상 프레임워크
    • Web Apps, VM, Linux, 컨테이너, AKS 및 비 Azure 호스팅을 포함한 모든 호스팅 옵션.
    • 미리 보기 버전을 포함한 모든 .NET Core 버전.
  • Visual Studio에서 디버그할 때 원격 분석이 로컬로 표시됩니다.
  • TrackXXX() API를 사용하여 더 많은 사용자 지정 원격 분석을 추적할 수 있습니다.
  • 구성을 완전히 제어할 수 있습니다.

Azure Monitor Application Insights Agent(이전의 상태 모니터 v2)와 같은 도구를 사용하여 Application Insights 모니터링을 사용하도록 설정할 수 있나요?

예. Application Insights Agent 2.0.0-beta1 이상에서 IIS에 호스트되는 ASP.NET Core 애플리케이션이 지원됩니다.

애플리케이션을 Linux에서 실행하는 경우 모든 기능이 지원되나요?

예. SDK에 대한 기능 지원은 다음과 같은 경우를 제외하고 모든 플랫폼에서 동일합니다.

이 SDK는 작업자 서비스에 지원되는가요?

아니요. 작업자 서비스에는 Application Insights for Worker Service 애플리케이션(HTTP가 아닌 애플리케이션)을 사용하세요.

SDK를 어떻게 제거할 수 있나요?

Application Insights를 제거하려면 애플리케이션의 API에서 NuGet 패키지 및 참조를 제거해야 합니다. Visual Studio에서 NuGet 패키지 관리자를 사용하여 NuGet 패키지를 제거할 수 있습니다.

참고 항목

이러한 지침은 ASP.NET Core SDK를 제거하기 위한 것입니다. ASP.NET SDK를 제거해야 하는 경우 ASP.NET SDK를 제거하려면 어떻게 해야 하나요?를 참조하세요.

  1. NuGet 패키지 관리자를 사용하여 Microsoft.ApplicationInsights.AspNetCore 패키지를 제거합니다.
  2. Application Insights를 완전히 제거하려면 프로젝트에 추가한 모든 API 호출과 함께 추가된 코드나 파일을 확인하고 수동으로 삭제합니다. 자세한 내용은 Application Insights SDK를 추가할 때 생성되는 항목을 참조하세요.

Application Insights SDK를 추가할 때 생성되는 항목

프로젝트에 Application Insights를 추가하면 파일이 만들어지며 일부 파일에는 코드가 추가됩니다. NuGet 패키지를 제거한다고 해서 파일 및 코드가 항상 삭제되는 것은 아닙니다. Application Insights를 완전히 제거하려면 프로젝트에 추가한 모든 API 호출과 함께 추가된 코드나 파일을 확인하고 수동으로 삭제해야 합니다.

Visual Studio ASP.NET Core 템플릿 프로젝트에 Application Insights 원격 분석을 추가하면 다음 코드가 추가됩니다.

  • [프로젝트 이름].csproj

      <PropertyGroup>
    <TargetFramework>netcoreapp3.1</TargetFramework>
    <ApplicationInsightsResourceId>/subscriptions/00000000-0000-0000-0000-000000000000/resourcegroups/Default-ApplicationInsights-EastUS/providers/microsoft.insights/components/WebApplication4core</ApplicationInsightsResourceId>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.ApplicationInsights.AspNetCore" Version="2.12.0" />
  </ItemGroup>

  <ItemGroup>
    <WCFMetadata Include="Connected Services" />
  </ItemGroup>

  • Appsettings.json:

    "ApplicationInsights": {
    "InstrumentationKey": "00000000-0000-0000-0000-000000000000"

  • ConnectedService.json

    {
  "ProviderId": "Microsoft.ApplicationInsights.ConnectedService.ConnectedServiceProvider",
  "Version": "16.0.0.0",
  "GettingStartedDocument": {
    "Uri": "https://go.microsoft.com/fwlink/?LinkID=798432"
  }
}

  • Startup.cs

       public void ConfigureServices(IServiceCollection services)
        {
            services.AddRazorPages();
            services.AddApplicationInsightsTelemetry(); // This is added
        }

원격 분석 상관관계를 사용하지 않도록 설정하려면 어떻게 해야 하나요?

코드에서 원격 분석 상관관계를 사용하지 않도록 설정하려면 콘솔 애플리케이션용 Application Insights에서 <ExcludeComponentCorrelationHttpHeadersOnDomains>를 참조하세요.

문제 해결

전용 문제 해결 문서를 참조하세요.

애플리케이션 호스트와 수집 서비스 간의 연결 테스트

Application Insights SDK 및 에이전트는 수집 엔드포인트에 대한 REST 호출로 수집하기 위해 원격 분석을 보냅니다. PowerShell 또는 curl 명령의 원시 REST 클라이언트를 사용하여 웹 서버 또는 애플리케이션 호스트 컴퓨터에서 수집 서비스 엔드포인트로의 연결을 테스트할 수 있습니다. Azure Monitor Application Insights에서 누락된 애플리케이션 원격 분석 문제 해결을 참조하세요.

오픈 소스 SDK

코드를 읽고 기여합니다.

최신 업데이트 및 버그 수정에 대해서는 릴리스 정보를 참조하세요.

릴리스 정보

버전 2.12 이상: .NET SDK(ASP.NET, ASP.NET Core 및 로깅 어댑터 포함)

서비스 업데이트에는 주요 Application Insights 개선 사항도 요약되어 있습니다.

다음 단계