ASP.NET Core 애플리케이션용 Application Insights를 사용하도록 설정

아티클
10/11/2023

이 문서에서는 Azure Web App으로 배포된 ASP.NET Core 애플리케이션에 대해 Application Insights를 사용하도록 설정하는 방법을 설명합니다. 이 구현에서는 SDK 기반 접근 방식을 사용합니다. 자동 계측 방식도 사용할 수 있습니다.

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

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

샘플 애플리케이션의 경우 net6.0을 대상으로 하는 ASP.NET Core MVC 애플리케이션을 사용합니다. 그러나 이 지침은 모든 ASP.NET Core 애플리케이션에 적용할 수 있습니다. Worker Service를 사용하는 경우 여기의 지침을 수행합니다.

참고

OpenTelemetry 기반 .NET 제품을 사용할 수 있습니다. 자세한 정보를 알아보세요.

참고

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

지원되는 시나리오

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

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

사전 요구 사항

이 자습서를 완료하려면 다음이 필요합니다.

Visual Studio 2022
다음 Visual Studio 워크로드:
- ASP.NET 및 웹 개발
- 데이터 스토리지 및 처리
- Azure 개발
.NET 6.0
Azure 구독 및 사용자 계정(리소스를 만들고 삭제하는 기능 포함)

Azure 리소스 배포

GitHub 리포지토리에서 샘플 애플리케이션을 배포하기 위한 참고 자료에 따르세요.

리소스에 전체적으로 고유한 이름을 제공하기 위해 6자 접미사가 일부 리소스에 할당되었습니다. 이 문서의 뒷부분에서 사용할 수 있도록 이 접미사를 적어두세요.

Application Insights 리소스 만들기

Azure Portal에서 application-insights-azure-cafe 리소스 그룹을 선택합니다.
위쪽 도구 모음 메뉴에서 + 만들기를 선택합니다.
리소스 만들기 화면의 마켓플레이스 검색 텍스트 상자에서 Application Insights를 검색하고 선택합니다.

Azure Portal의 리소스 만들기 화면 스크린샷 스크린샷은 강조 표시된 Application Insights에 대한 검색과 검색 결과에 표시되는 Application Insights를 보여 주며 이 역시 강조 표시되어 있습니다.
Application Insights 리소스 개요 화면에서 만들기를 선택합니다.

Application Insights 화면의 기본 사항 탭에서 다음 테이블을 사용하여 양식을 완성한 다음, 검토 + 만들기 단추를 선택합니다. 아래 표에 지정되지 않은 필드는 기본값을 유지할 수 있습니다.

필드	값
속성	`azure-cafe-application-insights-{SUFFIX}`를 입력하고 {SUFFIX}를 이전에 기록된 적절한 접미사 값으로 바꿉니다.
지역	문서 리소스를 배포할 때 선택한 동일한 지역을 선택합니다.
Log Analytics 작업 영역	azure-cafe-log-analytics-workspace를 선택합니다. 또는 새 로그 분석 작업 영역을 만들 수 있습니다.

유효성 검사가 통과되면 만들기를 선택하여 리소스를 배포합니다.
리소스가 배포되면 application-insights-azure-cafe 리소스 그룹으로 돌아가고 배포한 Application Insights 리소스를 선택합니다.
Application Insights 리소스의 개요 화면에서 클립보드에 복사 단추를 선택하여 연결 문자열 값을 복사합니다. 이 문서의 다음 섹션에서 연결 문자열 값을 사용합니다.

Azure Portal의 Application Insights 개요 화면 스크린샷 스크린샷에는 연결 문자열 값이 강조 표시되고 클립보드에 복사 단추가 선택 및 강조 표시되어 있습니다.

Web App Service에서 Application Insights 연결 문자열 애플리케이션 설정 구성

application-insights-azure-cafe 리소스 그룹으로 돌아가고 azure-cafe-web-{SUFFIX} App Service 리소스를 엽니다.
왼쪽 메뉴의 설정 섹션에서 구성을 선택합니다. 그런 다음, 애플리케이션 설정 탭에서 애플리케이션 설정 헤더 아래에 있는 + 새 애플리케이션 설정을 선택합니다.

Azure Portal의 App Service 리소스 화면 스크린샷 스크린샷은 선택되고 강조 표시된 설정 섹션 아래 왼쪽 메뉴의 구성, 선택되고 강조 표시된 애플리케이션 설정 탭, 강조 표시된 + 새 애플리케이션 설정 도구 모음 단추를 보여 줍니다.
애플리케이션 설정 추가/편집 창에서 다음과 같이 양식을 작성하고 확인을 선택합니다.

필드 값

속성 APPLICATIONINSIGHTS_CONNECTION_STRING

값 이전 섹션에서 복사한 Application Insights 연결 문자열 값을 붙여넣습니다.
App Service 구성 화면의 도구 모음 메뉴에서 저장 단추를 선택합니다. 변경 내용을 저장하라는 메시지가 표시되면 계속을 선택합니다.

필드	값
속성	APPLICATIONINSIGHTS_CONNECTION_STRING
값	이전 섹션에서 복사한 Application Insights 연결 문자열 값을 붙여넣습니다.

Application Insights NuGet 패키지 설치

원격 분석을 보내도록 ASP.NET Core MVC 웹 애플리케이션을 구성해야 합니다. 이 작업은 ASP.NET Core 웹 애플리케이션 NuGet 패키지용 Application Insights를 사용하여 수행됩니다.

Visual Studio에서 1 - Starter Application\src\AzureCafe.sln을 엽니다.
Visual Studio 솔루션 탐색기 패널에서 AzureCafe 프로젝트 파일을 마우스 오른쪽 단추로 클릭하고, NuGet 패키지 관리를 선택합니다.
찾아보기 탭을 선택한 다음, Microsoft.ApplicationInsights.AspNetCore를 검색하여 선택합니다. 설치를 선택하고 사용 조건에 동의합니다. 최신 안정 버전을 사용하는 것이 좋습니다. SDK에 대한 전체 릴리스 정보는 오픈 소스 GitHub 리포지토리를 참조하세요.

찾아보기 탭이 선택된 Visual Studio의 NuGet 패키지 관리자 사용자 인터페이스를 보여 주는 스크린샷. Microsoft.ApplicationInsights.AspNetCore가 검색 상자에 입력되고 결과 목록에서 Microsoft.ApplicationInsights.AspNetCore 패키지가 선택됩니다. 오른쪽 창의 드롭다운 목록에서 안정적인 최신 버전의 Microsoft.ApplicationInsights.AspNetCore 패키지가 선택되고 설치 단추가 강조 표시됩니다.

문서의 다음 섹션에 대해 Visual Studio를 열어 둡니다.

Application Insights 서버 쪽 원격 분석 사용

ASP.NET Core 웹 애플리케이션 NuGet 패키지용 Application Insights는 Azure의 Application Insights 리소스에 서버 쪽 원격 분석을 보낼 수 있도록 기능을 캡슐화합니다.

Visual Studio 솔루션 탐색기에서 Program.cs 파일을 엽니다.
builder.Services.AddControllersWithViews() 문 앞에 다음 코드를 삽입합니다. 이 코드는 구성에서 Application Insights 연결 문자열 값을 자동으로 읽습니다. AddApplicationInsightsTelemetry 메서드는 기본 제공 종속성 주입 컨테이너에 ApplicationInsightsLoggerProvider를 등록합니다. 그러면 ILogger 및 ILogger<TCategoryName> 구현 요청을 수행하는 데 사용됩니다.
```
builder.Services.AddApplicationInsightsTelemetry();
```
팁

ASP.NET Core의 구성 옵션에 대해 자세히 알아봅니다.

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

위의 단계는 서버 쪽 원격 분석 수집을 시작하는 데 도움이 됩니다. 샘플 애플리케이션에는 클라이언트 쪽 구성 요소가 있습니다. 다음 단계에 따라 사용량 원격 분석 수집을 시작합니다.

Visual Studio 솔루션 탐색기에서 \Views\_ViewImports.cshtml을 엽니다.

기존 파일의 끝에 다음 코드를 추가합니다.

@inject Microsoft.ApplicationInsights.AspNetCore.JavaScriptSnippet JavaScriptSnippet

애플리케이션에 대해 클라이언트 쪽 모니터링을 올바르게 사용하도록 설정하려면 Visual Studio 솔루션 탐색기에서 닫는 \Views\Shared\_Layout.cshtml을 열고 닫은 <\head> 태그 바로 앞에 다음 코드를 삽입합니다. JavaScript 코드 조각은 모니터링하려는 애플리케이션의 각 페이지에서 <head> 섹션에 삽입해야 합니다.
```
@Html.Raw(JavaScriptSnippet.FullScript)
```
팁

FullScript 대신 ScriptBody를 사용할 수 있습니다. 콘텐츠 보안 정책을 설정하기 위해 <script> 태그를 제어해야 하는 경우 ScriptBody를 사용합니다.
```
<script> // apply custom changes to this script tag.
    @Html.Raw(JavaScriptSnippet.ScriptBody)
</script>
```

참고

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

데이터베이스 쿼리 모니터링 사용

성능 저하의 원인을 조사할 때는 데이터베이스 호출에 대한 인사이트를 포함하는 것이 중요합니다. 종속성 모듈을 구성하여 모니터링을 사용하도록 설정합니다. SQL을 포함한 종속성 모니터링은 기본적으로 사용됩니다.

다음 단계에 따라 전체 SQL 쿼리 텍스트를 캡처합니다.

참고

SQL 텍스트에는 암호 및 PII와 같은 중요한 데이터가 포함될 수 있습니다. 이 기능을 사용하도록 설정할 때는 주의해야 합니다.

Visual Studio 솔루션 탐색기에서 Program.cs 파일을 엽니다.

파일 맨 위에 다음 using 문을 추가합니다.

using Microsoft.ApplicationInsights.DependencyCollector;

SQL 명령 텍스트 계측을 사용하도록 설정하려면 builder.Services.AddApplicationInsightsTelemetry() 코드 바로 뒤에 다음 코드를 삽입합니다.
```
builder.Services.ConfigureTelemetryModule<DependencyTrackingTelemetryModule>((module, o) => { module.EnableSqlCommandTextInstrumentation = true; });
```

Azure Cafe 웹 애플리케이션 실행

웹 애플리케이션 코드를 배포한 후 원격 분석이 Application Insights로 이동합니다. Application Insights SDK는 애플리케이션에 들어오는 웹 요청을 자동으로 수집합니다.

Visual Studio 솔루션 탐색기에서 AzureCafe 프로젝트를 마우스 오른쪽 단추로 클릭하고 바로 가기 메뉴에서 게시를 선택합니다.
게시를 선택하여 새 코드를 Azure App Service로 승격시킵니다.

Azure Cafe 웹 애플리케이션이 성공적으로 게시되면 Azure Cafe 웹 애플리케이션에 대한 새 브라우저 창이 열립니다.
일부 원격 분석을 생성하려면 웹 애플리케이션에서 다음 단계에 따라 검토를 추가합니다.
1. 카페 메뉴와 검토를 보려면 카페 옆에 있는 세부 정보를 선택합니다.
2. 검토를 보고 추가하려면 Cafe 화면에서 검토 탭을 선택합니다. 검토 추가 단추를 선택하여 검토를 추가합니다.
3. 검토 만들기 대화 상자에서 이름, 등급, 댓글을 입력하고, 검토를 위한 사진을 업로드합니다. 완료되면 검토 추가를 선택합니다.
4. 추가 원격 분석을 생성해야 하는 경우 검토를 추가합니다.

라이브 메트릭

Live Metrics를 사용하여 Application Insights 모니터링이 올바르게 구성되었는지 여부를 빠르게 확인할 수 있습니다. Live Metrics는 실행 중인 프로세스의 CPU 사용량을 거의 실시간으로 보여 줍니다. 요청, 종속성, 추적 등의 다른 원격 분석을 표시할 수도 있습니다. 원격 분석이 포털 및 분석에 표시되는 데 몇 분 정도 걸릴 수 있습니다.

애플리케이션 맵 보기

샘플 애플리케이션은 Azure SQL, Azure Blob Storage 및 Azure Language Service를 비롯한 여러 Azure 리소스를 호출합니다(감정 분석 검토용).

Application Insights는 들어오는 원격 분석 데이터를 검사하며 검색하는 시스템 통합의 시각적 맵을 생성할 수 있습니다.

Azure Portal에 로그인합니다.
샘플 애플리케이션의 리소스 그룹(application-insights-azure-cafe)을 엽니다.
리소스 목록에서 azure-cafe-insights-{SUFFIX} Application Insights 리소스를 선택합니다.
왼쪽 메뉴의 조사 제목 바로 아래에서 애플리케이션 맵을 선택합니다. 생성된 애플리케이션 맵을 관찰합니다.

HTTP 호출 및 데이터베이스 SQL 명령 텍스트 보기

Azure Portal에서 Application Insights 리소스를 엽니다.
왼쪽 메뉴의 조사 헤더 바로 아래에서 성능을 선택합니다.
작업 탭에는 애플리케이션에서 수신한 HTTP 호출에 대한 세부 정보가 포함되어 있습니다. 데이터의 서버 및 브라우저(클라이언트 쪽) 뷰 간에 토글하려면 서버/브라우저 토글을 사용합니다.

Azure Portal의 Application Insights 성능 화면 스크린샷. 스크린샷은 서버/브라우저 토글과 강조 표시된 애플리케이션에서 수신한 HTTP 호출을 보여 줍니다.
테이블에서 작업을 선택하고 요청 샘플을 드릴하도록 선택합니다.

Azure Portal의 Application Insights 성능 화면 스크린샷. 스크린샷은 POST 작업과 선택되고 강조 표시된 제안 목록의 샘플 작업을 보여 주며 샘플로 드릴 단추가 강조 표시됩니다.

엔드투엔드 트랜잭션은 선택한 요청에 대해 표시됩니다. 이 경우 리뷰가 이미지를 포함하여 작성되었으므로 Azure Storage 및 언어 서비스(감정 분석용)에 대한 호출이 포함됩니다. 검토를 지속하기 위한 SQL Azure에 대한 데이터베이스 호출도 포함됩니다. 이 예에서 첫 번째로 선택된 이벤트는 HTTP POST 호출과 관련된 정보를 표시합니다.
SQL 항목을 선택하여 데이터베이스에 발급된 SQL 명령 텍스트를 검토합니다.
선택적으로 Azure Storage 또는 언어 서비스에 대한 종속성(발신) 요청을 선택합니다.
성능 화면으로 돌아가서 종속성 탭을 선택하여 외부 리소스에 대한 호출을 조사합니다. 작업 테이블에는 감정 분석, Blob Storage 및 Azure SQL에 대한 호출이 포함되어 있습니다.

Application Insights를 사용한 애플리케이션 로깅

로깅 개요

Application Insights는 ASP.NET Core용 Application Insights NuGet 패키지가 설치되고 서버 쪽 원격 분석 수집을 사용하는 경우 애플리케이션에 사용할 수 있게 된 ASP.NET Core 애플리케이션에서 사용할 수 있는 로그 공급자의 한 유형입니다.

참고로 Program.cs의 다음 코드는 기본 제공 종속성 주입 컨테이너에 ApplicationInsightsLoggerProvider를 등록합니다.

builder.Services.AddApplicationInsightsTelemetry();

ApplicationInsightsLoggerProvider가 로그 공급자로 등록되면 앱은 ILogger를 사용한 생성자 주입 또는 일반 유형 대안 ILogger<TCategoryName>을 사용하여 Application Insights에 로그할 준비가 됩니다.

참고

기본적으로 로그 공급자는 심각도가 LogLevel.Warning 이상인 로그 이벤트를 자동으로 캡처하도록 구성됩니다.

다음 예제 컨트롤러를 고려해 보겠습니다. 이 예제는 종속성 주입 컨테이너에 등록된 ApplicationInsightsLoggerProvider로 해결되는 ILogger 주입을 보여 줍니다. Get 메서드에서 정보, 경고 및 오류 메시지가 기록되는지 확인합니다.

참고

기본적으로 정보 수준 추적은 기록되지 않습니다. 경고 및 위의 수준만 캡처됩니다.

using Microsoft.AspNetCore.Mvc;

[Route("api/[controller]")]
[ApiController]
public class ValuesController : ControllerBase
{
    private readonly ILogger _logger;

    public ValuesController(ILogger<ValuesController> logger)
    {
        _logger = logger;
    }

    [HttpGet]
    public ActionResult<IEnumerable<string>> Get()
    {
        //Info level traces are not captured by default
        _logger.LogInformation("An example of an Info trace..");
        _logger.LogWarning("An example of a Warning trace..");
        _logger.LogError("An example of an Error level message");

        return new string[] { "value1", "value2" };
    }
}

자세한 내용은 ASP.NET Core 로그인(영문)을 참조하세요.

Application Insights에서 로그 보기

위의 ValuesController는 샘플 애플리케이션과 함께 배포되며 프로젝트의 Controllers 폴더에 있습니다.

인터넷 브라우저를 사용하여 샘플 애플리케이션을 엽니다. 주소 표시줄에 /api/Values를 추가하고 Enter를 누릅니다.
Azure Portal에서 잠시 기다린 다음, azure-café-insights-{SUFFIX} Application Insights 리소스를 선택합니다.
Application Insights 리소스의 왼쪽 메뉴에 있는 모니터링 섹션에서 로그를 선택합니다.
테이블 창의 Application Insights 트리 아래에서 traces 테이블을 두 번 클릭합니다.
다음과 같이 쿼리를 수정하여 값 컨트롤러에 대한 추적을 검색한 다음, 실행을 선택하여 결과를 필터링합니다.
```
traces 
| where operation_Name == "GET Values/Get"
```
결과에는 컨트롤러에 있는 로그 메시지가 표시됩니다. 로그 심각도 2는 경고 수준을 나타내고 로그 심각도 3은 오류 수준을 나타냅니다.
또는 로그 범주에 따라 결과를 검색하기 위해 쿼리를 작성할 수도 있습니다. 기본적으로 범주는 ILogger가 삽입되는 클래스의 정규화된 이름입니다. 이 경우 범주 이름은 ValuesController입니다(클래스와 연결된 네임스페이스가 있는 경우 이름에 네임스페이스가 접두사로 추가됨). 범주에 따라 결과를 검색하려면 다음 쿼리를 다시 작성하고 실행합니다.
```
traces 
| where customDimensions.CategoryName == "ValuesController"
```

Application Insights로 전송되는 로그 수준 제어

ILogger 구현에는 로그 필터링을 적용하는 기본 제공 메커니즘이 있습니다. 이 필터링을 통해 Application Insights 공급자를 포함하여 등록된 각 공급자로 전송되는 로그를 제어할 수 있습니다. 구성(예를 들어 appsettings.json 파일 사용)에서 또는 코드에서 필터링을 사용할 수 있습니다. 로그 수준에 관한 자세한 내용과 적절한 사용 방법에 관한 참고 자료는 로그 수준 설명서를 참조하세요.

다음 예는 ApplicationInsightsLoggerProvider에 필터 규칙을 적용하여 Application Insights로 전송되는 로그 수준을 제어하는 방법을 보여줍니다.

구성으로 필터 규칙 만들기

구성에서 ApplicationInsightsLoggerProvider의 별칭은 ApplicationInsights입니다. appsettings.json 파일의 다음 섹션에서는 모든 제공자의 기본 로그 수준을 LogLevel.Warning로 설정합니다. 특히 “ValuesController”로 시작하는 범주의 ApplicationInsights 공급자에 대한 구성은 이 기본값을 LogLevel.Error 이상으로 재정의합니다.

{
  //... additional code removed for brevity
  "Logging": {
    "LogLevel": { // No provider, LogLevel applies to all the enabled providers.
      "Default": "Warning"
    },
    "ApplicationInsights": { // Specific to the provider, LogLevel applies to the Application Insights provider.
      "LogLevel": {
        "ValuesController": "Error" //Log Level for the "ValuesController" category
      }
    }
  }
}

appsettings.json의 이전 코드를 사용하여 샘플 애플리케이션을 배포하면 ValuesController와 상호 작용할 때 Application Insights로 전송되는 오류 추적만 생성됩니다. 이는 ValuesController 범주의 LogLevel이 Error로 설정되기 때문입니다. 따라서 Warning 추적이 표시되지 않습니다.

Application Insights에 대한 로깅 끄기

구성을 사용하여 로깅을 사용하지 않도록 설정하려면 모든 LogLevel 값을 “None”으로 설정합니다.

{
  //... additional code removed for brevity
  "Logging": {
    "LogLevel": { // No provider, LogLevel applies to all the enabled providers.
      "Default": "None"
    },
    "ApplicationInsights": { // Specific to the provider, LogLevel applies to the Application Insights provider.
      "LogLevel": {
        "ValuesController": "None" //Log Level for the "ValuesController" category
      }
    }
  }
}

마찬가지로, 코드 내에서 ApplicationInsightsLoggerProvider의 기본 수준과 모든 후속 로그 수준을 None으로 설정합니다.

var builder = WebApplication.CreateBuilder(args);
builder.Logging.AddFilter<ApplicationInsightsLoggerProvider>("", LogLevel.None);
builder.Logging.AddFilter<Microsoft.Extensions.Logging.ApplicationInsights.ApplicationInsightsLoggerProvider>("ValuesController", LogLevel.None);

오픈 소스 SDK

코드를 읽고 기여합니다.

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

다음 단계

사용자 흐름을 검색하여 사용자가 앱을 탐색하는 방법을 이해합니다.
예외가 throw되는 시점의 소스 코드 및 변수 상태를 확인할 수 있도록 스냅샷 컬렉션을 구성합니다.
앱의 성능 및 사용량을 자세히 확인할 수 있도록 API를 사용하여 사용자 고유의 이벤트 및 메트릭을 보냅니다.
가용성 개요
ASP.NET Core의 종속성 주입
ASP.NET Core에 로그인
Application Insights의 .NET 추적 로그
Application Insights를 위한 자동 계측

다음을 통해 공유