.NET 및 .NET Core 기반 애플리케이션 모니터링

개요

Instana 다음과 같은 기능을 통해 .NET 애플리케이션에 대한 포괄적인 모니터링을 제공합니다:

자동 코드 생성 : AutoTrace 를 사용하면 코드 변경이 전혀 필요하지 않습니다
분산 추적 : 서비스 전반에 걸친 종단 간 가시성
성능 지표 : CPU, 메모리, 스레드 잠금 등
AutoProfile : 성능 최적화를 위한 지속적인 프로파일링
OpenTelemetry 지원 : 기존 OTel 구현과 통합

.NET 모니터링의 작동 원리

.NET5.0 이상 버전을 사용하여 원하는 애플리케이션을 직접 만들거나 기존 애플리케이션을 사용하세요. 사용 중인 환경에 Instana 에이전트를 설치하십시오. 에이전트가 ‘.NET ’ 프로세스를 감지하고 ‘.NET ’ 센서를 로드합니다. .NET Core 애플리케이션의 성능 지표와 상태 데이터를 자동으로 수집합니다.

애플리케이션과 연결된 서비스를 통과하는 요청에 대한 상세한 추적 데이터를 수집하려면 `.NET ` 추적을 명시적으로 설정해야 합니다. Tracing은 애플리케이션 내 각 요청의 이동 경로를 추적하여, 각 단계가 소요되는 시간과 문제가 발생하는 위치를 보여줍니다.

다음과 같은 방법으로 추적을 설정할 수 있습니다:

AutoTrace : 에이전트 구성을 통한 자동 설정
수동 추적 : ` NuGet ` 패키지 명시적 설치

자세한 내용은 ‘계측 기법’을 참조하십시오.

추적 기능이 활성화되면 Instana 는 .NET Tracer를 실행하며, 이 도구는 다음 계측 방법 중 하나 또는 둘 모두를 사용하여 추적을 캡처합니다:

IL 재작성 : Instana 는 .NET 프로세스에 연결되어, 실행 시점에 선택된 중간 언어(IL) 코드를 재작성하여 추적 로직을 삽입합니다.
이벤트 기반 계측 : Instana 는 지원되는 라이브러리에서 발생되는 이벤트와 ActivitySource 데이터를 수신하여, IL 코드를 재작성하지 않고도 해당 이벤트를 분산 추적 정보로 변환합니다. 자세한 내용은 ‘이벤트 기반 계측 구성’을 참조하십시오.

센서와 추적기는 서로 연동되어 완벽한 가시성을 제공합니다. 최신 센서 및 트레이서 릴리스에 대해서는 .NET Core (센서) 및 .NET, .NET Core (트레이서)를 참조하십시오.

전제조건

다음 전제조건이 충족되어야 합니다.

시스템 하드웨어 사양:
- RAM: 8GB 이상의 사용 가능한 메모리
- CPU: 최적의 성능을 위해 4개 이상의 CPU 코어
- 디스크 공간: 추적 로그 및 임시 파일용 100 MB
Instana 에이전트가 설치되었습니다 : 호스트 에이전트가 인프라에서 실행 중이어야 합니다.
네트워크 연결 : .NET 애플리케이션이 Instana 에이전트에 연결되어야 합니다. 자세한 내용은 ‘네트워크 요구 사항’을 참조하십시오.
.NET 런타임 지원
- .NET 5.0 또는 그 이후
- .NET Core 2.x 그리고 3.x (사용 중단됨)
자세한 내용은 지원 정보를 참조하십시오.

지원 정보

Instana 가 현재 환경과 호환되는지 확인하려면 ‘지원되는 .NET 런타임, 라이브러리 및 프레임워크’를 참조하십시오.

.NET 모니터링 설정

.NET 모니터링을 설정하려면 다음 작업을 순서대로 수행하십시오

1단계: 계측 기법 이해하기

환경에 따라 .NET 애플리케이션의 추적 기능을 자동 또는 수동으로 구성할 수 있습니다.

사용 중인 환경에서 ` AutoTrace, `를 지원하는 경우, ` Instana `는 `.NET ` 애플리케이션에 자동으로 계측 코드를 삽입합니다. 단, AutoTrace 가 지원되지 않는 경우 수동 추적을 사용해야 합니다.

AutoTrace

Instana AutoTrace 코드 변경 없이 자동 계측 기능을 제공합니다. 이 방식을 사용하면 수동으로 설정하거나 구성할 필요가 없습니다. Instana 사용자를 대신해 애플리케이션 구성 요소를 자동으로 감지하고, 계측하며, 추적합니다.

중요:

기본적으로 .NET Core 의 자동 추적 기능은 비활성화되어 있습니다. 이 기능을 명시적으로 활성화해야 합니다.

.NET 추적을 자동으로 설정하려면 에이전트 구성 파일에서 추적 기능을 활성화하십시오. 에이전트는 `.NET ` 프로세스를 감지하고, `.NET ` 프로세스에 추적 코드를 자동으로 삽입합니다. NuGet 패키지를 설치하거나 코드를 수정할 필요가 없습니다.

에이전트는.NET 추적에 필요한 환경 변수가 포함된 전역 환경 파일을 instana_dotnet_global_env.sh 생성합니다.

Instana 들어오는 요청에 대한 스팬 생성이 즉시 시작되며, 이후 Instana UI에서 트레이스를 확인할 수 있습니다.

수동 추적

수동 추적은 ` NuGet ` 패키지를 활용한 계측을 포함합니다. 이 방식을 사용하면 추적 대상을 더 세밀하게 제어할 수 있지만, 추가적인 구성과 설정이 필요합니다.

참고:

환경 변수 COMPlus_EnableDiagnostics 와 를 로 DOTNET_EnableDiagnostics 설정하여 .NET 에 대한 진단 기능이 활성화되어 있는지 확인하십시오 1. 이 기능이 비활성화된 경우, IL 리라이터는 해당 프로세스에 연결할 수 없으므로 호출을 재작성하거나 추적을 생성할 수 없습니다.

.NET 추적을 수동으로 설정하려면 다음 단계를 따르십시오:

프로젝트에 다음 패키지( Instana, NuGet )를 추가하세요. 이 패키지들은 추적 로직을 추가하고 런타임 계측을 가능하게 합니다.
- Instana.Tracing.Core
- Instana.Tracing.Core.Rewriter
참고:
대상 플랫폼( Windows, Linux 또는 Alpine Linux )에 적합한 Rewriter 패키지 버전을 선택하십시오.
다음 환경 변수를 설정하십시오.
- CORECLR_ENABLE_PROFILING
- CORECLR_PROFILER_PATH
- CORECLR_PROFILER
- DOTNET_STARTUP_HOOKS
추적 라이브러리를 포함하여 애플리케이션을 배포하십시오.

다음과 같은 경우에는 수동 추적 방식이 가장 적합합니다:

독립형 애플리케이션
AutoTrace 를 사용할 수 없는 환경

2단계: 플랫폼별 설치 가이드 선택

사용 중인 배포 환경에 맞는 가이드를 선택하세요:

표 1. 플랫폼별 설정 가이드
배치 환경	안내서
AWS 람다 기능	AWS Lambda 에서 .NET 추적 설정하기
Azure App Services	Azure App Services 에서 .NET 추적 설정하기
Azure 컨테이너 앱	Azure 컨테이너 앱에서 .NET 추적 설정하기
Azure Functions	Azure Functions 에서 .NET 추적 설정하기
Cloud Foundry 플랫폼	Cloud Foundry 에서 .NET 추적 설정하기
Docker 컨테이너	Docker 에서 .NET 추적 설정하기
IIS에서 호스팅되는 웹 애플리케이션	IIS에서 .NET 추적 설정하기
Kubernetes 클러스터	Kubernetes 에서 .NET 추적 설정하기
일반 이메일: Linux 또는 Alpine Linux	Linux 또는 Alpine Linux 에서 .NET 추적 설정하기
Windows 서비스 또는 독립 실행형 프로세스	Windows 에서 .NET 추적 설정하기
z/OS	z/OS 에서 .NET 추적 설정하기

3단계: 추가 기능 설정 (선택 사항)

기본 모니터링 설정을 완료한 후에는 다음의 추가 선택 기능을 구성하여 ‘.NET ’의 모니터링 기능을 강화할 수 있습니다:

Kafka 추적 상관 관계 헤더 : Kafka 추적용 헤더 형식을 구성합니다.
프로세스 제외 : 화이트리스트 또는 블랙리스트를 사용하여 모니터링 대상 프로세스를 제어합니다.
화이트리스트 처리 : 특정 프로세스만 추적합니다.
스팬 필터링 : 특정 스팬을 필터링하여 데이터 양을 줄입니다.
스택 트레이스 : 스택 트레이스 수집 수준 및 깊이를 제어합니다.
AutoProfile : 성능 최적화를 위해 지속적인 프로파일링을 활성화합니다.
사용자 지정 추적 : .NET SDK를 사용하여 사용자 지정 스팬을 추가하세요.
이벤트 기반 계측 : ` ActivitySource ` 이벤트를 통해 텔레메트리 데이터를 수집합니다.
HTTP 4xx 상태 코드 오류 보고 : 종료 스팬에서 HTTP 4xx 응답을 오류로 분류하는 옵트인 기능을 지원합니다.

자세한 구성 방법은 ‘추가 기능 구성’을 참조하십시오.

OpenTelemetry 와의 연동

Instana OpenTelemetry 와 연동하기 위한 추가적인 .NET 구성 요소를 제공합니다.

메트릭 및 트레이스 확인

참고:

Windows 에서는 메트릭 수집이 자동으로 이루어집니다. Linux 에서는 추가 설정이 필요합니다. Linux 에서 ‘지표 활성화’를 참조하십시오.

모니터링을 설정하면 Instana UI에서 ‘.NET ’ 애플리케이션과 관련된 메트릭 및 트레이스를 확인할 수 있습니다.

지표를 확인하려면 다음 단계를 따르세요:

Instana UI의 탐색 메뉴에서 ‘인프라’를 선택합니다.
모니터링 대상 호스트 중 하나를 클릭하세요.

수집된 모든 메트릭과 모니터링 중인 프로세스가 표시된 호스트 대시보드를 확인할 수 있습니다.

추적 기록을 보려면 다음 단계를 따르십시오:

Instana UI의 탐색 메뉴에서 ‘애플리케이션’을 클릭합니다.
‘애플리케이션’ 대시보드에서 ‘.NET ’ 애플리케이션 또는 서비스를 선택합니다.
애플리케이션 또는 서비스 대시보드에서 ‘통화 분석’을 클릭합니다.
분석 대시보드에서 ‘애플리케이션’ 메뉴에서 ‘호출’ 또는 ‘추적’을 선택합니다.

다음 가이드에서는 애플리케이션 데이터를 확인하는 방법에 대한 자세한 안내를 제공합니다:

Linux 에서 메트릭 활성화

Linux 에서는 1.1.34 이상의 Instana.Tracing.CoreNuGet 패키지를 사용하여 애플리케이션을 배포하십시오. 다음 환경 변수를 설정하십시오.

DOTNET_STARTUP_HOOKS=[path-to-your-app]/Instana.Tracing.Core.dll

패키지가 성공적으로 로드되었는지 확인하려면 애플리케이션 출력에서 다음 줄을 찾아보세요:

INSTANA Agent for .NET Core applications installed. Running on

추적에 동일한 패키지를 사용할 수 있습니다.

구성 데이터

표 2. 구성 데이터
추적된 구성	설명
이름	애플리케이션의 이름입니다.
버전	CLR 런타임 버전
인수	애플리케이션의 인수

성능 매트릭

표 3. 성과 지표
메트릭	설명
GC 활동	.NET 가비지 컬렉터가 얼마나 자주, 얼마나 오래 실행되는지 보여줍니다
메모리 사용량	애플리케이션이 사용 중인 메모리 양을 표시합니다
스레드 잠금	스레드가 잠금을 기다리며 차단된 상태를 나타냅니다
경합	공유 리소스에 대한 스레드 간 경쟁을 측정합니다
예외	런타임 예외의 개수와 유형을 표시합니다

건강 지표

Instana 수신되는 메트릭을 바탕으로 건강 지표를 지속적으로 분석하고, 사용자에게 미치는 영향에 따라 문제나 인시던트를 제기합니다.

내장 이벤트는 엔티티의 상태 지표가 정상 범위를 벗어날 경우 이슈나 인시던트를 발생시키며, 사용자 정의 이벤트는 특정 엔티티의 개별 메트릭에 대한 임계값을 기준으로 이슈나 인시던트를 발생시킵니다.

.NET 의 기본 제공 이벤트에 대한 자세한 내용은 ‘기본 제공 이벤트 참조’를 참조하십시오.

추적 사용 안함

.NET 애플리케이션의 추적 기능을 비활성화하려면 다음 단계를 따르십시오:

enabled: false구성 파일을 업데이트합니다: 에이전트 configuration.yaml 파일(*instanaAgentDir*/etc/instana/configuration.yaml)을 열고 ‘.NET ’ 추적 플래그를 로 설정합니다.

다음 예제는 `.NET ` 추적을 비활성화한 ` configuration.yaml ` 파일을 보여줍니다:
```
# netcore Tracing
com.instana.plugin.netcore:
tracing:
   enabled: false
 
```
업데이트된 구성이 적용되도록 Instana 에이전트를 다시 시작하십시오.
호스트 프로세스를 다시 시작하십시오.

알려진 문제점 및 제한사항

.NET 추적 기능의 알려진 문제 및 제한 사항을 확인하십시오:

ASP.NET Core 및 Instana 용 Application Insights.NET Core 모니터링

ASP.NET Core 용 Application Insights의 일부 제한 사항으로 인해, Instana .NET Core 모니터링이 Application Insights와 동시에 실행될 경우 Application Insights에서 데이터가 불완전하거나 누락된 것으로 표시될 수 있습니다.

Application Insights와 Instana 을 동시에 사용하려면, Instana 을 통해 W3C 헤더가 삽입되지 않도록 설정하여 W3C 트레이스 컨텍스트 전파를 비활성화해야 합니다.

Instana 가 W3C 헤더를 삽입하지 못하도록 하려면 다음 환경 변수를 설정하십시오:

INSTANA_W3C_DISABLE_INJECT_HEADERS=1

라이브러리 버전의 계측 기능 제한 사항

Instana .NET Core 센서( 1.0.90 ) 및 .NET Tracer( 1.315.1 )와 함께, 2026년 3월 13일 출시된 버전은 ‘추적용 지원 라이브러리 및 프레임워크’ 섹션에 명시적으로 나열된 라이브러리 버전으로만 계측을 제한합니다. 지원되지 않는 버전은 모니터링되지 않습니다.

지속적인 지원을 받으시려면 지원되는 버전으로 업그레이드해 주십시오. 자세한 내용과 해결 방법은 기술 문서를 참조하십시오.

애플리케이션 풀에서 `No Managed Code` 실행되는 ‘.NET ’ 5 이상용 애플리케이션에 대한 제한된 IIS 수준 메트릭

IIS에서 .NET 5 이상 애플리케이션( .NET 6, 7, 8 이상 포함)을 호스팅하는 경우 애플리케이션 풀은 다음 환경에서 실행되도록 구성해야 합니다. No Managed Code. 이 모드에서는 Instana 가 IIS 수준 메트릭을 수집할 수 없습니다.

IIS 애플리케이션 풀이 로 설정된 No Managed Code 경우, Instana 은 다음 IIS 수준 메트릭을 수집할 수 없습니다:

애플리케이션 풀 이름
w3wp.exe 프로세스 지표
작업자 프로세스 수준 모니터링 데이터

이러한 제한 사항은 IIS가 .NET 5 이상 버전의 애플리케이션을 호스팅하는 방식에 내재된 것입니다. 애플리케이션 수준 계측 및 추적 기능은 정상적으로 작동하지만, IIS 수준 메트릭은 사용할 수 없습니다.

IIS 수준 메트릭이 필요한 경우, 관리되는 코드 애플리케이션 풀을 지원하는..NET Framework 4 또는 그 이전 버전의 애플리케이션을 사용하는 것을 고려해 보십시오.

.NET 모니터링 문제 해결

.NET 의 모니터링 또는 추적 기능에 문제가 발생하면 다음과 같이 문제를 해결하십시오

일반적인 문제 해결 단계

Instana UI에 트레이스나 메트릭이 표시되지 않는 경우, 다음의 일반적인 문제 해결 단계를 수행하십시오:

필수 조건 확인:
- .NET 런타임 버전이 지원되는지 확인하십시오(.NET 5.0 이상)
- Instana 에이전트가 실행 중이고 접근 가능한지 확인하십시오
- 애플리케이션과 에이전트 간의 네트워크 연결 상태를 확인하십시오
환경 변수 확인:
- 필요한 모든 환경 변수가 올바르게 설정되었는지 확인하십시오
- 경로가 유효하고 접근 가능한지 확인하십시오
- 변수 이름이 올바르게 표기되었는지 확인하십시오
IL-Rewriter 초기화 확인:
- 응용 프로그램 로그에서 IL-Rewriter 초기화 메시지를 확인하십시오
- CORECLR_ENABLE_PROFILING, CORECLR_PROFILER_PATH, 및 CORECLR_PROFILER 가 올바르게 설정되었는지 확인하십시오
진단 기능 활성화:
- Instana IL 리라이터를 사용하는 트레이싱을 활용하는 경우, 와 DOTNET_EnableDiagnostics 를 COMPlus_EnableDiagnostics 1
- 진단 기능이 활성화되지 않은 상태에서는 IL-Rewriter가 해당 프로세스에 연결할 수 없습니다
추적 구성 확인:
- 에이전트 configuration.yaml 파일에서 추적 기능이 활성화되어 있는지 확인하십시오
- 설정을 변경한 후 에이전트와 애플리케이션을 다시 시작하십시오

플랫폼별 자세한 문제 해결 시나리오 및 로그 수집 절차에 대해서는 다음 섹션의 해당 문제 해결 가이드를 참조하십시오.

플랫폼별 문제 해결 가이드

표 4. 플랫폼별 문제 해결 가이드
배치 환경	문제점 해결 안내서
AWS 람다 기능	AWS Lambda 에서 .NET 추적 관련 문제 해결
Azure	Azure 에서 .NET 추적 관련 문제 해결
Docker 컨테이너	Docker 에서 .NET 추적 관련 문제 해결
IIS에서 호스팅되는 웹 애플리케이션	IIS에서 ‘.NET ’ 추적 관련 문제 해결
Kubernetes 클러스터	Kubernetes 에서 .NET 추적 관련 문제 해결
일반 이메일: Linux 또는 Alpine Linux	Linux 또는 Alpine Linux 에서 .NET 추적 관련 문제 해결
Windows 서비스 또는 독립 실행형 프로세스	Windows 에서 .NET 추적 관련 문제 해결
z/OS	z/OS 에서 .NET 추적 관련 문제 해결