사용자 지정 이벤트 및 메트릭용 Application Insights API

애플리케이션에 몇 줄의 코드를 삽입하여 사용자가 해당 애플리케이션으로 어떤 작업을 하는지 살펴보거나 진단 문제를 지원할 수 있습니다. 디바이스 및 데스크톱 앱, 웹 클라이언트, 웹 서버에서 원격 분석을 보낼 수 있습니다. Application Insights 핵심 원격 분석 API를 사용하여 사용자 지정 이벤트 및 메트릭과 고유한 버전의 표준 원격 분석을 보냅니다. 이 API는 표준 Application Insights 데이터 수집기에서 사용하는 동일한 API입니다.

참고 항목

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

API 요약

핵심 API는 GetMetric(.NET만 해당)과 같은 몇 가지 변형을 제외하고 모든 플랫폼에서 동일합니다.

메서드	사용 대상
TrackPageView	페이지, 화면, 창 또는 양식
TrackEvent	사용자 작업 및 기타 이벤트. 사용자 동작을 추적하거나 성능을 모니터링하는 데 사용됩니다.
GetMetric	0 및 다차원 메트릭, 중앙 집중식으로 구성된 집계, C#만 해당.
TrackMetric	특정 이벤트와 관련이 없는 큐 길이와 같은 성능 측정.
TrackException	진단 예외를 기록합니다. 다른 이벤트와 관련하여 발생 위치를 추적하고 스택 추적을 검사합니다.
TrackRequest	성능 분석에 대한 서버 요청 빈도 및 기간을 기록합니다.
TrackTrace	리소스 진단 로그 메시지입니다. 타사 로그를 캡처할 수도 있습니다.
TrackDependency	기간 및 빈도 앱이 종속된 외부 구성 요소에 대한 호출을 기록합니다.

이러한 대부분의 원격 분석 호출에 속성 및 메트릭을 연결 할 수 있습니다.

시작하기 전에

Application Insights SDK에 대한 참조가 아직 없는 경우:

• 프로젝트에 Application Insights SDK 추가:

  • ASP.NET 프로젝트
  • ASP.NET Core 프로젝트
  • Java 프로젝트
  • Node.js 프로젝트
  • 각 웹 페이지의 JavaScript

• 디바이스 또는 웹 서버 코드에 다음을 포함합니다.

  C#: using Microsoft.ApplicationInsights;

  Visual Basic Imports Microsoft.ApplicationInsights

  Java: import com.microsoft.applicationinsights.TelemetryClient;

  Node.js: var applicationInsights = require("applicationinsights");

TelemetryClient 인스턴스 가져오기

TelemetryClient의 인스턴스 가져오기(웹 페이지의 JavaScript는 제외):

ASP.NET Core 앱 및 .NET/.NET Core에 대한 비 HTTP/Worker 앱의 경우 각각의 해당 설명서에서 설명한 대로 종속성 주입 컨테이너에서 TelemetryClient의 인스턴스를 가져옵니다.

Azure Functions v2 이상 또는 Azure WebJobs v3 이상을 사용하는 경우 Azure Functions 모니터링을 참조하세요.

C#

private TelemetryClient telemetry = new TelemetryClient();

이 메서드가 더 이상 사용되지 않는다는 메시지가 표시되는 경우 자세한 내용은 microsoft/ApplicationInsights-dotnet#1152를 참조하세요.

Visual Basic

Private Dim telemetry As New TelemetryClient

Java

private TelemetryClient telemetry = new TelemetryClient();

Node.JS

var telemetry = applicationInsights.defaultClient;

TelemetryClient는 스레드로부터 안전합니다.

ASP.NET 및 Java 프로젝트의 경우 들어오는 HTTP 요청이 자동으로 캡처됩니다. 앱의 다른 모듈에 대해 더 많은 TelemetryClient 인스턴스를 만들어야 할 수도 있습니다. 예를 들어 비즈니스 논리 이벤트를 보고하는 하나의 TelemetryClient 인스턴스가 미들웨어 클래스에 있을 수 있습니다. 컴퓨터를 식별하기 위해 UserId 및 DeviceId와 같은 속성을 설정할 수 있습니다. 이 정보는 인스턴스에서 보내는 모든 이벤트에 연결됩니다.

C#

TelemetryClient.Context.User.Id = "...";
TelemetryClient.Context.Device.Id = "...";

Java

telemetry.getContext().getUser().setId("...");
telemetry.getContext().getDevice().setId("...");

Node.js 프로젝트에서 new applicationInsights.TelemetryClient(instrumentationKey?)를 사용하여 새 인스턴스를 만들 수 있습니다. defaultClient 싱글톤에서 격리된 구성이 필요한 시나리오에만 이 방법을 사용하는 것이 좋습니다.

TrackEvent

Application Insights에서 사용자 지정 이벤트는 메트릭 탐색기에서 집계된 개수로 표시하고 진단 검색에서 개별 발생 항목으로 표시할 수 있는 데이터 요소입니다. MVC 또는 다른 프레임워크 "이벤트"와 관련이 없습니다.

다양한 이벤트를 계산하기 위해 코드에 TrackEvent를 삽입합니다. 예를 들어 사용자가 특정 기능을 선택하는 빈도를 추적해야 할 수도 있습니다. 또는 특정 목표를 달성하거나 특정 유형의 실수를 하는 빈도를 알아야 할 수도 있습니다.

예를 들어 게임 앱은 사용자가 이길 때마다 이벤트를 보냅니다.

JavaScript

appInsights.trackEvent({name:"WinGame"});

C#

telemetry.TrackEvent("WinGame");

Visual Basic

telemetry.TrackEvent("WinGame")

Java

telemetry.trackEvent("WinGame");

Node.JS

telemetry.trackEvent({name: "WinGame"});

Log Analytics의 사용자 지정 이벤트

원격 분석은 Application Insights 로그 탭 또는 사용 환경의 customEvents 테이블에서 이용할 수 있습니다. 이벤트는 trackEvent(..) 또는 클릭 분석 자동 수집 플러그 인에서 발생할 수 있습니다.

샘플링이 작동 중인 경우 itemCount 속성에서 1보다 큰 값을 표시합니다. 예를 들어 itemCount==10은 샘플링 프로세스에서 trackEvent()에 대한 10개 호출 중 하나만 전송했음을 의미합니다. 사용자 지정 이벤트의 정확한 개수를 가져오려면 customEvents | summarize sum(itemCount)와 같은 코드를 사용합니다.

참고 항목

itemCount의 최솟값은 1입니다. 레코드 자체는 항목을 나타냅니다.

GetMetric

GetMetric() 호출을 효과적으로 사용하여 .NET 및 .NET Core 애플리케이션에 대해 로컬로 사전 집계된 메트릭을 캡처하는 방법을 알아보려면 .NET 및 .NET Core의 사용자 지정 메트릭 수집을 참조하세요.

TrackMetric

참고 항목

Microsoft.ApplicationInsights.TelemetryClient.TrackMetric은 메트릭을 보내는 기본 설정 방법이 아닙니다. 메트릭은 전송되기 전에 항상 일정 기간 미리 집계되어야 합니다. GetMetric(..) 오버로드 중 하나를 사용하여 SDK 사전 집계 기능에 액세스하는 메트릭 개체를 가져옵니다.

사용자 고유의 사전 집계 논리를 구현하는 경우 TrackMetric() 메서드를 사용하여 결과 집계를 보낼 수 있습니다. 애플리케이션에서 시간이 지남에 따라 집계를 수행하지 않고 모든 경우에서 개별 원격 분석 항목을 보내야 하는 경우 이벤트 원격 분석에 대한 사용 사례가 적용될 가능성이 높습니다. TelemetryClient.TrackEvent (Microsoft.ApplicationInsights.DataContracts.EventTelemetry)을(를) 참조하세요.

Application Insights는 특정 이벤트에 연결되지 않은 메트릭을 차트로 작성할 수 있습니다. 예를 들어 정기적으로 큐 길이를 모니터링할 수 있습니다. 메트릭을 사용할 경우 개별 측정값보다 변형 및 추세에 좀 더 관심을 갖게 되며 통계 차트가 유용합니다.

메트릭을 Application Insights에 보내려면 TrackMetric(..) API를 사용할 수 있습니다. 메트릭을 전송하는 방법에는 다음 두 가지가 있습니다.

• 단일 값. 애플리케이션에서 측정을 수행할 때마다 Application Insights에 해당 값을 보냅니다.

  예를 들어 컨테이너의 항목 수를 설명하는 메트릭이 있다고 가정합니다. 특정 기간 동안 먼저 컨테이너에 3개 항목을 추가한 다음 2개 항목을 제거합니다. 따라서 TrackMetric을 두 번 호출합니다. 먼저 3 값을 전달한 다음, -2 값을 전달합니다. Application Insights는 두 값을 모두 저장합니다.

• 집계. 메트릭을 사용하여 작업하는 경우 모든 단일 측정값에는 거의 관심이 없습니다. 대신 특정 기간 동안 발생한 상황에 대한 요약이 중요합니다. 이러한 요약을 집계라고 합니다.

  이전의 예제에서 해당 기간에 대한 집계 메트릭 합계는 1이고 메트릭 값의 개수는 2입니다. 집계 방법을 사용하는 경우 TrackMetric을 기간당 한 번만 호출하고 집계 값을 보냅니다. 모든 관련 정보를 계속 수집하면서 더 적은 수의 데이터 요소를 Application Insights에 보냄으로써 비용 및 성능 오버헤드를 상당히 줄일 수 있으므로 이 방법을 사용하는 것이 좋습니다.

단일 값 예제

단일 메트릭 값을 전송하려면

JavaScript

appInsights.trackMetric({name: "queueLength", average: 42});

C#

var sample = new MetricTelemetry();
sample.Name = "queueLength";
sample.Sum = 42.3;
telemetryClient.TrackMetric(sample);

Java

telemetry.trackMetric("queueLength", 42.0);

Node.JS

telemetry.trackMetric({name: "queueLength", value: 42.0});

Log Analytics의 사용자 지정 메트릭

Application Insights 분석의 customMetrics 테이블에서 원격 분석을 사용할 수 있습니다. 각 행은 앱의 trackMetric(..) 호출을 나타냅니다.

• valueSum: 측정값의 합계입니다. 평균 값을 가져오려면 valueCount로 나눕니다.
• valueCount: 이 trackMetric(..) 호출로 집계된 측정값의 수입니다.

참고 항목

valueCount의 최솟값은 1입니다. 레코드 자체는 항목을 나타냅니다.

페이지 보기

디바이스 또는 웹 페이지 앱에서 각 화면 또는 페이지가 로드되면 기본적으로 페이지 보기 원격 분석이 전송됩니다. 그러나 페이지 보기를 더 많거나 다른 시간에 추적하도록 기본값을 변경할 수 있습니다. 예를 들어 탭 또는 창을 표시하는 앱에서 사용자가 새 창을 열 때마다 페이지를 추적할 수 있습니다.

사용자 및 세션 데이터는 페이지 보기와 함께 속성으로 보내므로 페이지 보기 원격 분석이 있으면 사용자 및 세션 차트가 활성화됩니다.

사용자 지정 페이지 보기

JavaScript

appInsights.trackPageView("tab1");

C#

telemetry.TrackPageView("GameReviewPage");

Visual Basic

telemetry.TrackPageView("GameReviewPage")

Java

telemetry.trackPageView("GameReviewPage");

여러 다른 HTML 페이지 내에 여러 탭이 있으면 URL도 지정할 수 있습니다.

appInsights.trackPageView("tab1", "http://fabrikam.com/page1.htm");

페이지 보기 시간

기본적으로 페이지 보기 로드 시간으로 보고되는 시간은 브라우저에서 요청을 보낼 때부터 브라우저의 페이지 로드 이벤트를 호출할 때까지 측정됩니다.

대신, 다음을 수행할 수 있습니다.

• trackPageView 호출에서 명시적 기간을 설정합니다. appInsights.trackPageView("tab1", null, null, null, durationInMilliseconds);
• 페이지 보기 시간 호출 startTrackPage 및 stopTrackPage를 사용합니다.

JavaScript

// To start timing a page:
appInsights.startTrackPage("Page1");

...

// To stop timing and log the page:
appInsights.stopTrackPage("Page1", url, properties, measurements);

첫 번째 매개 변수로 사용하는 이름은 시작 및 중지 호출을 연결합니다. 기본적으로 현재 페이지 이름이 지정됩니다.

메트릭 탐색기에 표시된 결과 페이지 로드 기간은 시작 및 중지 호출 사이의 간격에서 파생됩니다. 실제로 걸리는 시간 간격에 달려 있습니다.

Log Analytics의 페이지 원격 분석

Log Analytics에서는 두 개의 테이블에 브라우저 작업의 데이터가 표시됩니다.

• pageViews: URL 및 페이지 제목에 대한 데이터를 포함합니다.
• browserTimings: 들어오는 데이터를 처리하는 데 걸리는 시간과 같은 클라이언트 성능에 대한 데이터를 포함합니다.

브라우저가 다른 페이지를 처리하는 데 걸리는 시간을 보려면

browserTimings
| summarize avg(networkDuration), avg(processingDuration), avg(totalDuration) by name

다양한 브라우저의 인기도를 검색합니다.

pageViews
| summarize count() by client_Browser

페이지 보기를 AJAX 호출과 상호 연결하려면(종속성과 조인)

pageViews
| join (dependencies) on operation_Id

TrackRequest

서버 SDK에서 TrackRequest를 사용하여 HTTP 요청을 로그합니다.

실행 중인 웹 서비스 모듈이 없는 상황에서 요청을 시뮬레이션하고 싶다면 사용자가 직접 호출할 수도 있습니다.

요청 원격 분석을 보내는 데 권장되는 방법은 요청이 작업 컨텍스트로 작동하는 것입니다.

작업 컨텍스트

원격 분석 항목을 작업 컨텍스트와 연결하여 상호 연결할 수 있습니다. 표준 요청 추적 모듈은 예외 및 HTTP 요청이 처리되는 동안 전송되는 다른 이벤트에 대해 이를 수행합니다. 검색 및 분석에서 작업 ID를 사용하여 요청과 연결된 모든 이벤트를 쉽게 찾을 수 있습니다.

상관 관계에 대한 자세한 내용은 Application Insights의 원격 분석 상관 관계를 참조하세요.

원격 분석을 수동으로 추적하는 경우 원격 분석 상관 관계를 확인하는 가장 쉬운 방법은 다음 패턴을 사용하는 것입니다.

C#

// Establish an operation context and associated telemetry item:
using (var operation = telemetryClient.StartOperation<RequestTelemetry>("operationName"))
{
    // Telemetry sent in here will use the same operation ID.
    ...
    telemetryClient.TrackTrace(...); // or other Track* calls
    ...

    // Set properties of containing telemetry item--for example:
    operation.Telemetry.ResponseCode = "200";

    // Optional: explicitly send telemetry item:
    telemetryClient.StopOperation(operation);

} // When operation is disposed, telemetry item is sent.

작업 컨텍스트 설정과 함께 StartOperation은 지정하는 유형의 원격 분석 항목을 만듭니다. 작업을 삭제하거나 명시적으로 StopOperation을 호출하는 경우 원격 분석 항목을 보냅니다. 원격 분석 형식으로 RequestTelemetry를 사용하는 경우 해당 기간은 시작 및 중지 사이의 시간 제한 간격으로 설정됩니다.

작업 범위 내에서 보고되는 원격 분석 항목은 이러한 작업의 자식이 됩니다. 작업 컨텍스트는 중첩될 수 있습니다.

검색에서 작업 컨텍스트는 관련 항목 목록을 만드는 데 사용됩니다.

사용자 지정 작업 추적에 대한 자세한 내용은 Application Insights .NET SDK를 통한 사용자 지정 작업 추적을 참조하세요.

Log Analytics의 요청

Application Insights 분석에서 요청은 requests 테이블에 표시됩니다.

샘플링이 작동 중인 경우 itemCount 속성에서 1보다 큰 값을 표시합니다. 예를 들어 itemCount==10은 샘플링 프로세스에서 trackRequest()에 대한 10개 호출 중 하나만 전송했음을 의미합니다. 요청 이름별로 분할된 정확한 요청 수 및 평균 기간을 가져오려면 다음과 같은 코드를 사용합니다.

requests
| summarize count = sum(itemCount), avgduration = avg(duration) by name

TrackException

Application Insights로 예외를 보냅니다.

• 문제의 빈도 표시로 계산하려면
• 개별 항목을 검사하려면

보고서는 스택 추적을 포함합니다.

C#

try
{
    ...
}
catch (Exception ex)
{
    telemetry.TrackException(ex);
}

Java

try {
    ...
} catch (Exception ex) {
    telemetry.trackException(ex);
}

JavaScript

try
{
    ...
}
catch (ex)
{
    appInsights.trackException({exception: ex});
}

Node.JS

try
{
    ...
}
catch (ex)
{
    telemetry.trackException({exception: ex});
}

SDK에서 많은 예외를 자동으로 catch하므로 항상 TrackException을 명시적으로 호출할 필요가 없습니다.

• ASP.NET: 예외를 catch하는 코드를 작성합니다.
• Java EE: 예외가 자동으로 catch됩니다.
• JavaScript: 예외가 자동으로 catch됩니다. 자동 수집을 사용하지 않도록 설정하려면 웹 페이지에 삽입하는 JavaScript(웹) SDK 로더 스크립트에 다음 한 줄을 추가합니다.

({
    instrumentationKey: "your key",
    disableExceptionTracking: true
})

Log Analytics의 예외

Application Insights 분석에서 예외는 exceptions 테이블에 표시됩니다.

샘플링이 작동 중인 경우 itemCount 속성에서 1보다 큰 값을 표시합니다. 예를 들어 itemCount==10은 샘플링 프로세스에서 trackException()에 대한 10개 호출 중 하나만 전송했음을 의미합니다. 예외 유형별로 분할된 정확한 예외 수를 가져오려면 다음과 같은 코드를 사용합니다.

exceptions
| summarize sum(itemCount) by type

대부분의 중요한 스택 정보는 이미 별도 변수로 추출되지만 좀 더 자세한 정보를 위해 details 구조를 분리할 수 있습니다. 이 구조는 동적이므로 결과를 필요한 형식으로 캐스팅해야 합니다. 예시:

exceptions
| extend method2 = tostring(details[0].parsedStack[1].method)

예외를 관련 요청과 연결하려면 다음과 같이 조인을 사용합니다.

exceptions
| join (requests) on operation_Id

TrackTrace

"이동 경로 흔적"을 Application Insights에 보내면 TrackTrace를 사용하여 문제를 진단하는 데 도움이 됩니다. 진단 데이터의 청크를 보내고 진단 검색에서 검사할 수 있습니다.

.NET 로그 어댑터에서 이 API를 사용하여 타사 로그를 포털에 보냅니다.

Java에서 Application Insights Java 에이전트는 로그를 자동으로 수집하여 포털에 보냅니다.

C#

telemetry.TrackTrace(message, SeverityLevel.Warning, properties);

Java

telemetry.trackTrace(message, SeverityLevel.Warning, properties);

Node.JS

telemetry.trackTrace({
    message: message,
    severity: applicationInsights.Contracts.SeverityLevel.Warning,
    properties: properties
});

클라이언트/브라우저 쪽 JavaScript

trackTrace({
    message: string,
    properties?: {[string]:string},
    severityLevel?: SeverityLevel
})

메서드 출입 같은 진단 이벤트를 기록합니다.

매개 변수	설명
message	진단 데이터입니다. 이름보다 훨씬 길어질 수 있습니다.
properties	문자열-문자열 맵입니다. 포털에서 예외를 필터링하는 데 더 많은 데이터가 사용됩니다. 기본적으로 비어 있습니다.
severityLevel	지원되는 값: SeverityLevel.ts

메시지 콘텐츠를 검색할 수 있지만, 속성 값과 달리 필터링할 수는 없습니다.

message의 크기 제한이 속성의 크기 제한보다 훨씬 높습니다. TrackTrace의 장점은 비교적 긴 데이터를 메시지에 넣을 수 있다는 것입니다. 예를 들어, POST 데이터를 인코딩할 수 있습니다.

메시지에 심각도 수준을 추가할 수도 있습니다. 또 다른 원격 분석처럼, 다른 추적 집합에 대해 필터링 또는 검색하는 데 도움이 되는 속성 값을 추가할 수 있습니다. 예시:

C#

var telemetry = new Microsoft.ApplicationInsights.TelemetryClient();
telemetry.TrackTrace("Slow database response",
                SeverityLevel.Warning,
                new Dictionary<string,string> { {"database", db.ID} });

Java

Map<String, Integer> properties = new HashMap<>();
properties.put("Database", db.ID);
telemetry.trackTrace("Slow Database response", SeverityLevel.Warning, properties);

검색에서 특정 데이터베이스와 관련된 특정 심각도 수준의 모든 메시지를 쉽게 필터링할 수 있습니다.

Log Analytics의 추적

Application Insights 분석에서 TrackTrace에 대한 호출은 traces 테이블에 표시됩니다.

샘플링이 작동 중인 경우 itemCount 속성에서 1보다 큰 값을 표시합니다. 예를 들어 itemCount==10은 샘플링 프로세스에서 trackTrace()에 대한 10개 호출 중 하나만 전송했음을 의미합니다. 추적 호출의 정확한 개수를 가져오려면 traces | summarize sum(itemCount)와 같은 코드를 사용합니다.

TrackDependency

TrackDependency 호출을 사용하여 응답 시간과 외부 코드 조각에 대한 호출의 성공률을 추적합니다. 포털에서 종속성 차트에 결과가 나타납니다. 종속성 호출이 수행될 때마다 다음 코드 조각을 추가해야 합니다.

참고 항목

.NET 및 .NET Core의 경우 상관 관계에 필요한 DependencyTelemetry 속성 및 시작 시간 및 기간과 같은 일부 기타 속성을 채우는 TelemetryClient.StartOperation(확장) 메서드를 대안으로 사용할 수 있으므로 다음 예제와 같이 사용자 지정 타이머를 만들 필요가 없습니다. 자세한 내용은 Application Insights .NET SDK를 통한 사용자 지정 작업 추적의 나가는 종속성 추적에 대한 섹션을 참조하세요.

C#

var success = false;
var startTime = DateTime.UtcNow;
var timer = System.Diagnostics.Stopwatch.StartNew();
try
{
    success = dependency.Call();
}
catch(Exception ex)
{
    success = false;
    telemetry.TrackException(ex);
    throw new Exception("Operation went wrong", ex);
}
finally
{
    timer.Stop();
    telemetry.TrackDependency("DependencyType", "myDependency", "myCall", startTime, timer.Elapsed, success);
}

Java

boolean success = false;
Instant startTime = Instant.now();
try {
    success = dependency.call();
}
finally {
    Instant endTime = Instant.now();
    Duration delta = Duration.between(startTime, endTime);
    RemoteDependencyTelemetry dependencyTelemetry = new RemoteDependencyTelemetry("My Dependency", "myCall", delta, success);
    dependencyTelemetry.setTimeStamp(startTime);
    telemetry.trackDependency(dependencyTelemetry);
}

Node.JS

var success = false;
var startTime = new Date().getTime();
try
{
    success = dependency.Call();
}
finally
{
    var elapsed = new Date() - startTime;
    telemetry.trackDependency({
        dependencyTypeName: "myDependency",
        name: "myCall",
        duration: elapsed,
        success: success
    });
}

서버 SDK에는 특정 종속성 호출(예: 데이터베이스 및 REST API)을 자동으로 검색하고 추적하는 종속성 모듈이 포함되어 있습니다. 모듈 작업을 만들기 위해 서버에 에이전트를 설치해야 합니다.

Java에서는 Application Insights Java 에이전트를 사용하여 많은 종속성 호출을 자동으로 추적할 수 있습니다.

자동화된 추적에서 포착하지 못하는 호출을 추적하려면 이 호출을 사용합니다.

C#에서 표준 종속성 추적 모듈을 해제하려면 ApplicationInsights.config를 편집하고 DependencyCollector.DependencyTrackingTelemetryModule에 대한 참조를 삭제합니다. Java의 경우 자동 수집된 특정 원격 분석 표시 안 함을 참조하세요.

Log Analytics의 종속성

Application Insights 분석에서 trackDependency 호출은 dependencies 테이블에 표시됩니다.

샘플링이 작동 중이면 itemCount 속성에 1보다 큰 값이 표시됩니다. 예를 들어 itemCount==10은 샘플링 프로세스에서 trackDependency()에 대한 10개 호출 중 하나만 전송했음을 의미합니다. 대상 구성 요소별로 분할된 정확한 종속 수를 가져오려면 다음과 같은 코드를 사용합니다.

dependencies
| summarize sum(itemCount) by target

종속성을 관련 요청과 연결하려면 다음과 같이 조인을 사용합니다.

dependencies
| join (requests) on operation_Id

데이터 플러시

일반적으로 SDK는 고정된 간격(일반적으로 30초)으로 또는 버퍼가 가득 찰 때마다(일반적으로 500개 항목) 데이터를 보냅니다. 경우에 따라 버퍼를 플러시해야 할 수도 있습니다. 예를 들어 종료되는 애플리케이션에서 SDK를 사용하는 경우입니다.

.NET

Flush()를 사용하는 경우 다음 패턴을 사용하는 것이 좋습니다.

telemetry.Flush();
// Allow some time for flushing before shutdown.
System.Threading.Thread.Sleep(5000);

FlushAsync()를 사용하는 경우 다음 패턴을 사용하는 것이 좋습니다.

await telemetryClient.FlushAsync()
// No need to sleep

원격 분석이 손실되지 않도록 항상 애플리케이션 종료의 일부로 플러시하는 것이 좋습니다.

Java

telemetry.flush();
//Allow some time for flushing before shutting down
Thread.sleep(5000);

Node.JS

telemetry.flush();

함수는 서버 원격 분석 채널에 대해 비동기입니다.

참고 항목

• Java 및 JavaScript SDK는 애플리케이션 종료 시 자동으로 플러시됩니다.
• 자동 플러시 구성 검토: web.config 파일에서 자동 플러시를 사용하도록 설정하면 Application Insights로 계측된 .NET 애플리케이션의 성능이 저하될 수 있습니다. 자동 플러시가 사용하도록 설정되면 System.Diagnostics.Trace.Trace* 메서드를 호출할 때마다 개별 원격 분석 항목이 수집 서비스에 대한 별도의 고유한 웹 요청으로 전송됩니다. 이로 인해 웹 서버의 네트워크 및 스토리지가 소진될 수 있습니다. 성능 향상을 위해서는 자동 플러시를 사용하지 않도록 설정하고 보다 효과적으로 원격 분석 데이터를 전송하기 위해 설계된 ServerTelemetryChannel을 활용하는 것이 좋습니다.

인증된 사용자

웹앱에서 사용자는 기본적으로 쿠키로 식별됩니다. 사용자가 다른 컴퓨터 또는 브라우저에서 앱에 액세스하거나 쿠키를 삭제하는 경우 두 번 이상 계산될 수 있습니다.

사용자가 앱에 로그인하면 브라우저 코드에서 인증된 사용자 ID를 설정하여 보다 정확한 개수를 얻을 수 있습니다.

JavaScript

// Called when my app has identified the user.
function Authenticated(signInId) {
    var validatedId = signInId.replace(/[,;=| ]+/g, "_");
    appInsights.setAuthenticatedUserContext(validatedId);
    ...
}

ASP.NET 웹 MVC 애플리케이션에서의 예:

Razor

@if (Request.IsAuthenticated)
{
    <script>
        appInsights.setAuthenticatedUserContext("@User.Identity.Name
            .Replace("\\", "\\\\")"
            .replace(/[,;=| ]+/g, "_"));
    </script>
}

사용자의 실제 로그인 이름을 사용할 필요는 없습니다. 해당 사용자에게 고유한 ID이기만 하면 됩니다. 공백이나 ,;=| 문자를 포함할 수 없습니다.

사용자 ID도 세션 쿠키에 설정되고 서버로 전송됩니다. 서버 SDK가 설치된 경우 인증된 사용자 ID가 클라이언트 및 서버 원격 분석 둘 다에 대한 컨텍스트 속성의 일부로 전송됩니다. 필터링하고 검색할 수 있습니다.

앱이 사용자를 계정으로 그룹화하는 경우 계정 식별자를 전달할 수도 있습니다. 동일한 문자 제한이 적용됩니다.

appInsights.setAuthenticatedUserContext(validatedId, accountId);

메트릭 탐색기에서 사용자, 인증 및 사용자 계정을 계산하는 차트를 만들 수 있습니다.

특정 사용자 이름과 계정으로 클라이언트 데이터 지점을 검색할 수도 있습니다.

참고 항목

.NET Core SDK에 있는 ApplicationInsightsServiceOptions 클래스의 EnableAuthenticationTrackingJavaScript 속성은 사용자 이름을 Application Insights JavaScript SDK에서 보낸 각 추적의 인증 ID로 삽입하는 데 필요한 JavaScript 구성을 간소화합니다.

이 속성을 true로 설정하면 ASP.NET Core에 있는 사용자의 사용자 이름이 클라이언트 쪽 원격 분석과 함께 출력됩니다. 이러한 이유로 ASP.NET Core용 SDK에서 이미 삽입했으므로 appInsights.setAuthenticatedUserContext를 더 이상 수동으로 추가할 필요가 없습니다. JavaScript API 참조에서 설명한 대로 인증 ID는 .NET Core의 SDK에서 식별하여 서버 쪽 원격 분석에 사용하는 서버에도 보냅니다.

ASP.NET Core MVC와 동일한 방식으로 작동하지 않는 JavaScript 애플리케이션(예: SPA 웹앱)의 경우 여전히 appInsights.setAuthenticatedUserContext를 수동으로 추가해야 합니다.

속성을 사용하여 데이터 필터링, 검색 및 분할

속성 및 측정값을 이벤트, 메트릭, 페이지 보기, 예외 및 기타 원격 분석 데이터에 연결할 수 있습니다.

속성은 사용 현황 보고서에서 원격 분석을 필터링하는 데 사용할 수 있는 문자열 값입니다. 예를 들어 앱이 여러 게임을 제공하는 경우 각 이벤트에 게임 이름을 연결하여 인기가 더 많은 게임을 확인할 수 있습니다.

문자열 길이는 8,192자로 제한됩니다. 많은 양의 데이터 청크를 보내려면 TrackTrace의 메시지 매개 변수를 사용합니다.

메트릭 은 그래픽으로 표시할 수 있는 숫자 값입니다. 예를 들어 게이머의 획득 점수가 점진적으로 증가하는지 확인할 수 있습니다. 다양한 게임에 대한 개별 또는 누적 그래프를 얻을 수 있도록 이벤트와 함께 보낸 속성을 사용하여 그래프를 분할할 수 있습니다.

메트릭 값은 0보다 크거나 같아야 올바르게 표시됩니다.

속성 수, 속성 값 및 메트릭에 사용 가능한 제한 이 몇 가지 있습니다.

JavaScript

appInsights.trackEvent({
  name: 'some event',
  properties: { // accepts any type
    prop1: 'string',
    prop2: 123.45,
    prop3: { nested: 'objects are okay too' }
  }
});

appInsights.trackPageView({
  name: 'some page',
  properties: { // accepts any type
    prop1: 'string',
    prop2: 123.45,
    prop3: { nested: 'objects are okay too' }
  }
});

C#

// Set up some properties and metrics:
var properties = new Dictionary <string, string>
    {{"game", currentGame.Name}, {"difficulty", currentGame.Difficulty}};
var metrics = new Dictionary <string, double>
    {{"Score", currentGame.Score}, {"Opponents", currentGame.OpponentCount}};

// Send the event:
telemetry.TrackEvent("WinGame", properties, metrics);

Node.JS

// Set up some properties and metrics:
var properties = {"game": currentGame.Name, "difficulty": currentGame.Difficulty};
var metrics = {"Score": currentGame.Score, "Opponents": currentGame.OpponentCount};

// Send the event:
telemetry.trackEvent({name: "WinGame", properties: properties, measurements: metrics});

Visual Basic

' Set up some properties:
Dim properties = New Dictionary (Of String, String)
properties.Add("game", currentGame.Name)
properties.Add("difficulty", currentGame.Difficulty)

Dim metrics = New Dictionary (Of String, Double)
metrics.Add("Score", currentGame.Score)
metrics.Add("Opponents", currentGame.OpponentCount)

' Send the event:
telemetry.TrackEvent("WinGame", properties, metrics)

Java

Map<String, String> properties = new HashMap<String, String>();
properties.put("game", currentGame.getName());
properties.put("difficulty", currentGame.getDifficulty());

Map<String, Double> metrics = new HashMap<String, Double>();
metrics.put("Score", currentGame.getScore());
metrics.put("Opponents", currentGame.getOpponentCount());

telemetry.trackEvent("WinGame", properties, metrics);

참고 항목

개인 식별 정보를 속성에 기록하지 마세요.

속성 및 메트릭을 설정하는 또 다른 방법

이벤트 매개 변수를 별도의 개체에 수집하는 방법이 더 편하다면 이 방법을 사용해도 됩니다.

var event = new EventTelemetry();

event.Name = "WinGame";
event.Metrics["processingTime"] = stopwatch.Elapsed.TotalMilliseconds;
event.Properties["game"] = currentGame.Name;
event.Properties["difficulty"] = currentGame.Difficulty;
event.Metrics["Score"] = currentGame.Score;
event.Metrics["Opponents"] = currentGame.Opponents.Length;

telemetry.TrackEvent(event);

Warning

동일한 원격 분석 항목 인스턴스(이 예에서는 event)를 다시 사용하여 Track*()을 여러 번 호출하지 마세요. 그러면 인해 원격 분석을 잘못된 구성과 함께 보낼 수 있습니다.

Log Analytics의 사용자 지정 측정값 및 속성

Log Analytics에서 사용자 지정 메트릭 및 속성은 각 원격 분석 레코드의 customMeasurements 및 customDimensions 특성에 표시됩니다.

예를 들어 "game"이라는 속성을 요청 원격 분석에 추가하는 경우 다음 쿼리에서는 다른 "game" 값의 발생 횟수를 계산하고 "score" 사용자 지정 메트릭의 평균을 표시합니다.

requests
| summarize sum(itemCount), avg(todouble(customMeasurements.score)) by tostring(customDimensions.game)

다음에 유의합니다.

• customDimensions 또는 customMeasurements JSON에서 값을 추출하면 동적 형식이므로 tostring 또는 todouble로 캐스팅해야 합니다.
• 샘플링 가능성을 고려하려면 count()가 아니라 sum(itemCount)를 사용합니다.

타이밍 이벤트

작업을 수행하는 데 걸리는 시간을 차트로 표시하고 싶은 경우가 있습니다. 예를 들어 게임에서 사용자가 옵션을 선택하는 데 걸리는 시간을 알고 싶을 수 있습니다. 이 정보를 얻으려면 측정값 매개 변수를 사용합니다.

C#

var stopwatch = System.Diagnostics.Stopwatch.StartNew();

// ... perform the timed action ...

stopwatch.Stop();

var metrics = new Dictionary <string, double>
    {{"processingTime", stopwatch.Elapsed.TotalMilliseconds}};

// Set up some properties:
var properties = new Dictionary <string, string>
    {{"signalSource", currentSignalSource.Name}};

// Send the event:
telemetry.TrackEvent("SignalProcessed", properties, metrics);

Java

long startTime = System.currentTimeMillis();

// Perform timed action

long endTime = System.currentTimeMillis();
Map<String, Double> metrics = new HashMap<>();
metrics.put("ProcessingTime", (double)endTime-startTime);

// Setup some properties
Map<String, String> properties = new HashMap<>();
properties.put("signalSource", currentSignalSource.getName());

// Send the event
telemetry.trackEvent("SignalProcessed", properties, metrics);

사용자 지정 원격 분석에 대한 기본 속성

작성하는 사용자 지정 이벤트의 일부에 대해 기본 속성 값을 설정하려는 경우 TelemetryClient 인스턴스에서 설정합니다. 이러한 값은 해당 클라이언트에서 보낸 모든 원격 분석 항목에 연결됩니다.

C#

using Microsoft.ApplicationInsights.DataContracts;

var gameTelemetry = new TelemetryClient();
gameTelemetry.Context.GlobalProperties["Game"] = currentGame.Name;
// Now all telemetry will automatically be sent with the context property:
gameTelemetry.TrackEvent("WinGame");

Visual Basic

Dim gameTelemetry = New TelemetryClient()
gameTelemetry.Context.GlobalProperties("Game") = currentGame.Name
' Now all telemetry will automatically be sent with the context property:
gameTelemetry.TrackEvent("WinGame")

Java

import com.microsoft.applicationinsights.TelemetryClient;
import com.microsoft.applicationinsights.TelemetryContext;
...

TelemetryClient gameTelemetry = new TelemetryClient();
TelemetryContext context = gameTelemetry.getContext();
context.getProperties().put("Game", currentGame.Name);

gameTelemetry.TrackEvent("WinGame");

Node.JS

var gameTelemetry = new applicationInsights.TelemetryClient();
gameTelemetry.commonProperties["Game"] = currentGame.Name;

gameTelemetry.TrackEvent({name: "WinGame"});

개별 원격 분석 호출이 자신의 속성 사전에 있는 기본값을 재정의할 수 있습니다.

JavaScript 웹 클라이언트의 경우 JavaScript 원격 분석 이니셜라이저를 사용합니다.

표준 컬렉션 모듈의 데이터를 포함하여 모든 원격 분석에 속성을 추가하려면ITelemetryInitializer를 구현합니다.

원격 분석 샘플링, 필터링 및 처리

Application Insights SDK에서 원격 분석 필터링 및 전처리를 참고하세요.

원격 분석 사용 안 함

원격 분석의 컬렉션 및 전송을 동적으로 중지 및 시작하려면 :

C#

using  Microsoft.ApplicationInsights.Extensibility;

TelemetryConfiguration.Active.DisableTelemetry = true;

Java

telemetry.getConfiguration().setTrackingDisabled(true);

성능 카운터, HTTP 요청 또는 종속성과 같은 선택한 표준 수집기를 사용하지 않도록 설정하려면 ApplicationInsights.config에서 관련 줄을 삭제하거나 주석 처리합니다. 예를 들어 사용자 고유의 TrackRequest 데이터를 보내려는 경우입니다.

Node.JS

telemetry.config.disableAppInsights = true;

성능 카운터, HTTP 요청 또는 종속성과 같은 선택한 표준 수집기를 사용하지 않도록 설정하려면 초기화 시 구성 메서드를 SDK 초기화 코드로 체이닝합니다.

applicationInsights.setup()
    .setAutoCollectRequests(false)
    .setAutoCollectPerformance(false)
    .setAutoCollectExceptions(false)
    .setAutoCollectDependencies(false)
    .setAutoCollectConsole(false)
    .start();

초기화 후에 이러한 수집기를 사용하지 않도록 설정하려면 applicationInsights.Configuration.setAutoCollectRequests(false) 구성 개체를 사용합니다.

개발자 모드

디버깅하는 동안 결과를 즉시 볼 수 있도록 파이프라인을 통해 원격 분석을 신속하게 처리할 때 유용합니다. 또한 원격 분석과 관련된 모든 문제를 추적하는 데 도움이 되는 다른 메시지도 받습니다. 앱 속도가 느려질 수 있으므로 프로덕션 환경에서는 이 기능을 끕니다.

C#

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = true;

Visual Basic

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = True

Node.JS

Node.js의 경우 setInternalLogging을 통해 내부 로깅을 사용하도록 설정하고 maxBatchSize를 0으로 설정하여 개발자 모드를 사용하도록 설정할 수 있습니다. 그러면 원격 분석이 수집되는 즉시 보내집니다.

applicationInsights.setup("ikey")
  .setInternalLogging(true, true)
  .start()
applicationInsights.defaultClient.config.maxBatchSize = 0;

선택한 사용자 지정 원격 분석에 대해 계측 키를 설정합니다.

C#

var telemetry = new TelemetryClient();
telemetry.InstrumentationKey = "---my key---";
// ...

동적 계측 키

개발, 테스트 및 프로덕션 환경에서 원격 분석이 섞이지 않게 방지하려면 별도의 Application Insights 리소스를 만들고 환경에 따라 키를 변경하세요.

구성 파일에서 계측 키를 가져오는 대신 코드에서 설정할 수 있습니다. ASP.NET 서비스의 global.aspx.cs와 같은 초기화 메서드에서 키를 설정합니다.

C#

protected void Application_Start()
{
    Microsoft.ApplicationInsights.Extensibility.
    TelemetryConfiguration.Active.InstrumentationKey =
        // - for example -
        WebConfigurationManager.Settings["ikey"];
    ...
}

JavaScript

appInsights.config.instrumentationKey = myKey;

웹 페이지에서는 문자 그대로 스크립트에 코딩하는 대신 웹 서버의 상태에서 설정해야 할 수도 있습니다. 예를 들어 ASP.NET 앱에서 생성된 웹 페이지에서 다음과 같이 설정합니다.

Razor에서 JavaScript

<script type="text/javascript">
// Standard Application Insights webpage script:
var appInsights = window.appInsights || function(config){ ...
// Modify this part:
}({instrumentationKey:
    // Generate from server property:
    @Microsoft.ApplicationInsights.Extensibility.
        TelemetryConfiguration.Active.InstrumentationKey;
}) // ...

    String instrumentationKey = "00000000-0000-0000-0000-000000000000";

    if (instrumentationKey != null)
    {
        TelemetryConfiguration.getActive().setInstrumentationKey(instrumentationKey);
    }

TelemetryContext

TelemetryClient에는 모든 원격 분석 데이터와 함께 보내는 값이 포함된 Context 속성이 있습니다. 일반적으로 표준 원격 분석 모듈에서 설정되지만 직접 설정할 수도 있습니다. 예시:

telemetry.Context.Operation.Name = "MyOperationName";

이러한 값을 직접 설정하는 경우 사용자의 값과 표준 값이 혼동되지 않도록 ApplicationInsights.config에서 관련 줄을 제거하는 것이 좋습니다.

• Component: 앱 및 앱 버전입니다.
• Device: 앱이 실행되는 디바이스에 대한 데이터입니다. 웹앱에서는 원격 분석을 보내는 서버 또는 클라이언트 디바이스입니다.
• InstrumentationKey: Azure에서 원격 분석이 표시되는 Application Insights 리소스입니다. 일반적으로 ApplicationInsights.config에서 가져옵니다.
• Location: 디바이스의 지리적 위치입니다.
• Operation: 웹앱에서 현재 HTTP 요청입니다. 다른 앱 유형에서는 이 값을 설정하여 이벤트를 모두 그룹화할 수 있습니다.
  • ID: 진단 검색에서 이벤트를 검사할 때 "관련 항목"을 찾을 수 있도록 여러 이벤트의 상관 관계를 지정하기 위해 생성된 값입니다.
  • Name: 식별자이며, 일반적으로 HTTP 요청의 URL입니다.
  • SyntheticSource: null이거나 비어 있지 않다면 요청의 원본이 로봇 또는 웹 테스트로 확인되었음을 나타내는 문자열입니다. 기본적으로 메트릭 탐색기의 계산에서 제외됩니다.
• Session: 사용자의 세션입니다. ID는 생성된 값으로 설정되며, 사용자가 잠시 동안 비활성 상태이면 값이 변경됩니다.
• User: 사용자 정보입니다.

제한

애플리케이션별(즉, 계측 키별) 메트릭 및 이벤트의 수에 몇 가지 제한이 있습니다. 선택하는 가격 책정 계층에 따라 제한됩니다.

리소스	기본 제한	최대 한도	주의
일당 총 데이터	100GB	지원에 문의	데이터를 줄이기 위해 한도를 설정할 수 있습니다. 더 많은 데이터가 필요한 경우 포털에서 최대 1,000GB로 한도를 늘릴 수 있습니다. 1,000GB보다 큰 용량이 필요한 경우 AIDataCap@microsoft.com으로 이메일을 보내세요.
제한	32,000 이벤트/초	지원에 문의	제한은 분을 기준으로 측정됩니다.
데이터 보존 로그	30~730일	730일	이 리소스는 로그용입니다.
데이터 보존 메트릭	90일	90일	이 리소스는 메트릭 탐색기용입니다.
가용성 다단계 테스트 자세한 결과 보존	90일	90일	이 리소스는 각 단계의 자세한 결과를 제공합니다.
최대 원격 분석 항목 크기	64KB	64KB
일괄 처리당 최대 원격 분석 항목 수	64,000	64,000
속성 및 메트릭 이름 길이	150	150	형식 스키마를 참조하세요.
속성 값 문자열 길이	8,192	8,192	형식 스키마를 참조하세요.
추적 및 예외 메시지 길이	32,768	32,768	형식 스키마를 참조하세요.
Application Insights 리소스당 가용성 테스트 수	100	100
리소스 그룹당 가용성 테스트 수	800	800	Azure Resource Manager 참조
가용성 테스트 테스트당 최대 리디렉션	10	10
가용성 테스트 최소 테스트 빈도	300초		5분 미만의 사용자 지정 테스트 빈도에는 사용자 지정 TrackAvailability 구현이 필요합니다.
프로파일러 및 스냅샷 데이터 보존	2주	지원에 문의 최대 보존 기간 제한은 6개월입니다.
일일 전송된 프로파일러 데이터	제한 없음	제한 없음
하루에 전송된 스냅샷 데이터	모니터링되는 앱별로 하루에 스냅샷 30개	제한 없음	구성을 통해 애플리케이션별로 수집되는 스냅샷 수를 수정할 수 있습니다.

가격 책정 및 할당량에 대한 자세한 내용은 Application Insights 요금 청구를 참조하세요.

데이터 속도 제한에 도달하지 않도록 하려면 샘플링을 사용합니다.

데이터 유지 기간을 결정하려면 데이터 보존 및 개인 정보를 참조하세요.

참조 문서

• .NET 참조
• Java 참조
• JavaScript 참조

SDK 코드

• .NET
• Windows Server 패키지
• Java SDK
• Node.js SDK
• JavaScript SDK

자주 묻는 질문

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

원격 분석 데이터가 누락된 이유는 무엇인가요?

TelemetryChannels는 모두 애플리케이션이 종료되기 전에 플러시되지 않으면 버퍼링된 원격 분석이 손실됩니다.

데이터 손실을 방지하려면 애플리케이션이 종료될 때 TelemetryClient를 플러시합니다.

자세한 내용은 데이터 플러시를 참조하세요.

Track_() 호출에서 throw할 수 있는 예외는 무엇인가요?

없음. try-catch 절에 래핑할 필요가 없습니다. SDK에 문제가 발생하면 메시지를 디버그 콘솔 출력에 로그하고, 메시지가 통과하면 진단 검색에 표시됩니다.

포털에서 데이터를 가져오는 REST API가 있나요?

예, 데이터 액세스 API가 있습니다. 데이터를 추출하는 다른 방법에는 Power BI(작업 영역 기반 리소스로 마이그레이션한 경우) 또는 연속 내보내기(여전히 클래식 리소스에 있는 경우)가 포함됩니다.

사용자 지정 이벤트 및 메트릭 API에 대한 호출이 무시되는 이유는 무엇인가요?

Application Insights SDK는 자동 계측과 호환되지 않습니다. 자동 계측이 사용하도록 설정되면 Track() 및 기타 사용자 지정 이벤트 및 메트릭 API에 대한 호출이 무시됩니다.

App Service 페이지의 Application Insights 탭에 있는 Azure Portal에서 자동 계측을 끄거나 ApplicationInsightsAgent_EXTENSION_VERSION을 disabled로 설정합니다.

검색 및 메트릭 차트의 수가 다른 이유는 무엇인가요?

샘플링을 하면 앱에서 포털로 전송되는 원격 분석 항목(요청, 사용자 지정 이벤트 등)의 수가 줄어듭니다. 검색에는 받은 항목 수가 표시됩니다. 이벤트 수를 표시하는 메트릭 차트에는 발생된 원래 이벤트 수가 표시됩니다.

전송되는 각 항목은 해당 항목이 나타내는 원래 이벤트의 수를 보여 주는 itemCount 속성을 전달합니다. 작업 중인 샘플링을 관찰하려면 Log Analytics에서 다음 쿼리를 실행할 수 있습니다.

    requests | summarize original_events = sum(itemCount), transmitted_events = count()

이벤트에 대한 경고를 설정하려면 어떻게 해야 하나요?

Azure 경고는 메트릭에 대해서만 설정됩니다. 이벤트가 발생할 때마다 값 임계값을 초과하는 사용자 지정 메트릭을 만듭니다. 그런 다음 메트릭에 대해 경고를 설정합니다. 메트릭이 어느 방향으로든 임계값을 초과할 때마다 알림을 받습니다. 초기 값이 높거나 낮은지에 관계없이 처음 초과할 때까지는 알림을 받지 않습니다. 항상 몇 분의 대기 시간이 있습니다.

다음 단계

• 검색 이벤트 및 로그