다음을 통해 공유

Azure Monitor의 로그 수집 API

  • 아티클

Azure Monitor의 로그 수집 API를 통해 REST API 호출 또는 클라이언트 라이브러리를 사용하여 Log Analytics 작업 영역으로 데이터를 보낼 수 있습니다. API를 사용하면 지원되는 Azure 테이블 또는 사용자가 만든 사용자 지정 테이블로 데이터를 보낼 수 있습니다. 사용자 지정 열을 사용하여 Azure 테이블의 스키마를 확장하여 추가 데이터를 허용할 수도 있습니다.

기본 작업

REST API를 호출할 수 있는 모든 애플리케이션에서 로그 수집 API로 데이터를 보낼 수 있습니다. 이는 사용자가 만든 사용자 지정 애플리케이션일 수도 있고, API에 데이터를 보내는 방법을 이해하는 애플리케이션 또는 에이전트일 수도 있습니다. 대상 테이블과 작업 영역, 그리고 지정된 DCR에 액세스할 수 있는 앱 등록 자격 증명을 포함하는 DCR(데이터 수집 규칙)을 지정합니다. 프라이빗 링크를 사용하는 경우 DCR에서 지정한 엔드포인트 또는 DCE(데이터 수집 엔드포인트)에 데이터를 보냅니다.

애플리케이션에서 API로 보낸 데이터는 JSON 형식이어야 하며 DCR에서 예상하는 구조와 일치해야 합니다. DCR에 테이블의 구조와 일치하도록 데이터를 변환하는 변환을 포함할 수 있으므로 대상 테이블의 구조와 일치할 필요는 없습니다. API 호출 또는 원본 데이터를 변경하지 않고 DCR을 수정하여 대상 테이블 및 작업 영역을 수정할 수 있습니다.

로그 수집 API의 개요를 보여주는 다이어그램.

구성

다음 표에서는 로그 수집 API를 사용하기 전에 구성해야 하는 Azure의 각 구성 요소에 대해 설명합니다.

참고 항목

이러한 구성 요소의 구성을 자동화하는 PowerShell 스크립트는 로그 수집 API를 사용하여 Azure Monitor에 데이터를 보내는 샘플 코드를 참조하세요.

구성 요소 함수
앱 등록 및 비밀 애플리케이션 등록은 API 호출을 인증하는 데 사용됩니다. 아래 설명된 DCR에 대한 권한을 부여받아야 합니다. API 호출에는 애플리케이션의 애플리케이션(클라이언트) ID, 디렉터리(테넌트) ID 및 애플리케이션 비밀의 값이 포함됩니다.

리소스에 액세스할 수 있는 Microsoft Entra 애플리케이션 및 서비스 주체 만들기 및 새 애플리케이션 비밀 만들기를 참조하세요.
Log Analytics 작업 영역의 테이블 Log Analytics 작업 영역의 테이블이 있어야 데이터를 보낼 수 있습니다. 지원되는 Azure 테이블 중 하나를 사용하거나 사용 가능한 방법을 사용하여 사용자 지정 테이블을 만들 수 있습니다. Azure Portal을 사용하여 테이블을 만드는 경우 필요한 경우 변환을 포함하여 DCR이 만들어집니다. 다른 방법을 사용하려면 다음 섹션에 설명된 대로 DCR을 수동으로 만들어야 합니다.

사용자 지정 테이블 만들기를 참조하세요.
DCR(데이터 수집 규칙) Azure Monitor는 DCR(데이터 수집 규칙)을 사용하여 수신 데이터의 구조와 해당 데이터로 수행할 작업을 이해합니다. 테이블의 구조와 수신 데이터가 일치하지 않는 경우 DCR은 원본 데이터를 대상 테이블과 일치하도록 변환하는 변환을 포함할 수 있습니다. 변환을 사용하여 원본 데이터를 필터링하고 다른 계산 또는 변환을 수행할 수도 있습니다.

Azure Portal을 사용하여 사용자 지정 테이블을 만드는 경우 제공한 샘플 데이터를 기반으로 DCR 및 변환이 만들어집니다. 기존 테이블을 사용하거나 다른 방법을 사용하여 사용자 지정 테이블을 만드는 경우 다음 섹션의 세부 정보를 사용하여 DCR을 수동으로 만들어야 합니다.

DCR이 만들어지면 첫 번째 단계에서 만든 애플리케이션에 대한 액세스 권한을 부여해야 합니다. Azure Portal의 모니터링 메뉴에서 데이터 수집 규칙을 선택한 다음 만든 DCR을 선택합니다. DCR에 대해 액세스 제어(IAM)를 선택한 다음 역할 할당 추가를 선택하여 모니터링 메트릭 게시자 역할을 추가합니다.

엔드포인트

로그 수집 API에 대한 REST API 엔드포인트는 DCE(데이터 수집 엔드포인트) 또는 DCR 로그 수집 엔드포인트일 수 있습니다.

DCR 로그 수집 엔드포인트는 직접 수집을 위한 DCR을 만들 때 생성됩니다. 이 엔드포인트를 검색하려면 Azure Portal의 JSON 보기에서 DCR을 엽니다. 엔드포인트를 표시하려면 API 버전을 최신 버전으로 변경해야 할 수 있습니다.

DCR의 로그 수집 엔드포인트를 보여 주는 스크린샷

DCE는 프라이빗 링크를 사용하여 Log Analytics 작업 영역에 연결하거나 DCR에 로그 수집 엔드포인트가 포함되지 않은 경우에만 필요합니다. 이전 DCR을 사용하거나 매개 변수 없이 "kind": "Direct" DCR을 만든 경우일 수 있습니다. 자세한 내용은 아래 DCR(데이터 수집 규칙)을 참조하세요.

참고 항목

이 logsIngestion 숙박 시설은 2024년 3월 31일에 추가되었습니다. 이 날짜 이전에는 로그 수집 API에 DCE가 필요했습니다. 엔드포인트는 기존 DCR에 추가할 수 없지만 기존 DCE와 함께 기존 DCR을 계속 사용할 수 있습니다. DCR 엔드포인트로 이동하려면 기존 DCR를 대체할 새 DCR을 만들어야 합니다. 엔드포인트가 있는 DCR은 DCE를 사용할 수도 있습니다. 이 경우 DCR을 사용하는 각 클라이언트에 대해 DCE 또는 DCR 엔드포인트를 사용할지 여부를 선택할 수 있습니다.

DCR(데이터 수집 규칙)

Azure Portal을 사용하여 Log Analytics 작업 영역에서 사용자 지정 테이블을 만들 때 로그 수집 API와 함께 사용할 수 있는 DCR이 만들어집니다. 이미 존재하는 테이블에 데이터를 보내는 경우에는 DCR을 수동으로 만들어야 합니다. 아래 샘플 DCR부터 시작하여 템플릿에서 다음 매개 변수에 대한 값을 대체합니다. Azure Monitor에서 DCR(데이터 수집 규칙 만들기 및 편집)에 설명된 메서드를 사용하여 DCR을 만듭니다.

매개 변수 설명
region DCR을 만들 지역입니다. 사용 중인 경우 Log Analytics 작업 영역의 지역 및 DCE와 일치해야 합니다.
dataCollectionEndpointId DCE의 리소스 ID입니다. DCR 수집 지점을 사용하는 경우 이 매개 변수를 제거합니다.
streamDeclarations 열 목록을 들어오는 데이터의 열로 변경합니다. 스트림 이름은 dataFlows의 streams 이름과 일치하면 되므로 변경할 필요가 없습니다.
workspaceResourceId Log Analytics 작업 영역의 리소스 ID입니다. dataFlows의 destinations 이름과 일치하면 되므로 이름을 변경할 필요가 없습니다.
transformKql 들어오는 데이터에 적용할 KQL 쿼리입니다. 들어오는 데이터의 스키마가 테이블의 스키마와 일치하는 경우 들어오는 데이터를 변경되지 않은 상태로 전달하는 변환에 source를 사용할 수 있습니다. 그렇지 않으면 대상 테이블 스키마와 일치하도록 데이터를 변환하는 쿼리를 사용합니다.
outputStream 데이터를 전송할 테이블 이름입니다. 사용자 지정 테이블의 경우 접두사 Custom-<table-name>을 추가합니다. 기본 제공 테이블의 경우 접두사 Microsoft-<table-name>을 추가합니다. 
{
    "location": "eastus",
    "dataCollectionEndpointId": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/my-resource-group/providers/Microsoft.Insights/dataCollectionEndpoints/dce-eastus",
    "kind": "Direct",
    "properties": {
        "streamDeclarations": {
            "Custom-MyTable": {
                "columns": [
                    {
                        "name": "Time",
                        "type": "datetime"
                    },
                    {
                        "name": "Computer",
                        "type": "string"
                    },
                    {
                        "name": "AdditionalContext",
                        "type": "string"
                    }
                ]
            }
        },
        "destinations": {
            "logAnalytics": [
                {
                    "workspaceResourceId": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/cefingestion/providers/microsoft.operationalinsights/workspaces/my-workspace",
                    "name": "LogAnalyticsDest"
                }
            ]
        },
        "dataFlows": [
            {
                "streams": [
                    "Custom-MyTable"
                ],
                "destinations": [
                    "LogAnalyticsDest"
                ],
                "transformKql": "source",
                "outputStream": "Custom-MyTable_CL"
            }
        ]
    }
}

클라이언트 라이브러리

REST API 호출 외에도 다음 클라이언트 라이브러리를 사용하여 로그 수집 API에 데이터를 보낼 수 있습니다. 라이브러리에는 구성에 설명된 것과 동일한 구성 요소가 필요합니다. 이러한 각 라이브러리를 사용하는 예는 로그 수집 API를 사용하여 Azure Monitor에 데이터를 보내는 샘플 코드를 참조하세요.

REST API 호출

REST API 호출을 사용하여 Azure Monitor에 데이터를 보내려면 HTTP를 통해 POST 호출을 수행합니다. 이 호출에 필요한 세부 정보는 이 섹션에 설명되어 있습니다.

URI

URI에는 지역, DCE 또는 DCR 수집 엔드포인트, DCR ID 및 스트림 이름이 포함됩니다. 또한 API 버전을 지정합니다.

URI는 다음 형식을 사용합니다.

{Endpoint}/dataCollectionRules/{DCR Immutable ID}/streams/{Stream Name}?api-version=2023-01-01

예시:

https://my-dce-5kyl.eastus-1.ingest.monitor.azure.com/dataCollectionRules/dcr-000a00a000a00000a000000aa000a0aa/streams/Custom-MyTable?api-version=2023-01-01

DCR Immutable ID DCR을 만들 때 생성됩니다. Azure Portal의 DCR에 대한 개요 페이지에서 검색할 수 있습니다.

변경할 수 없는 ID를 보여 주는 데이터 수집 규칙의 스크린샷

Stream Name 는 사용자 지정 데이터를 처리해야 하는 DCR의 스트림 을 참조합니다.

헤더

다음 표에서는 API 호출에 대한 헤더를 설명합니다.

헤더 필수 여부 설명
Authorization 예 클라이언트 자격 증명 흐름을 통해 가져오는 전달자 토큰입니다. 클라우드에 대한 토큰 대상 그룹자 값을 사용합니다.

Azure 퍼블릭 클라우드 - https://monitor.azure.com
21Vianet에서 운영하는 Microsoft Azure 클라우드 - https://monitor.azure.cn
Azure 미국 정부 클라우드 - https://monitor.azure.us
콘텐츠-형식 예 application/json
Content-Encoding 아니요 gzip
x-ms-client-request-id 아니요 문자열 형식 GUID. 이는 Microsoft에서 문제 해결 목적으로 사용할 수 있는 요청 ID입니다.

본문

호출 본문에는 Azure Monitor로 보낼 사용자 지정 데이터가 포함됩니다. 데이터의 모양은 DCR의 스트림에서 예상하는 형식과 일치하는 항목 구조를 가진 JSON 배열이어야 합니다. API 호출 내에서 단일 항목을 전송해야 하는 경우 데이터는 단일 항목 배열로 전송되어야 합니다.

예시:

[
{
    "TimeGenerated": "2023-11-14 15:10:02",
    "Column01": "Value01",
    "Column02": "Value02"
}
]

데이터 전송 문제를 방지하려면 요청 본문이 UTF-8로 올바르게 인코딩되었는지 확인합니다.

예시

PowerShell을 사용한 API 호출의 예는 로그 수집 API를 사용하여 Azure Monitor에 데이터를 보내는 샘플 코드를 참조하세요.

지원되는 테이블

수집 API로 전송된 데이터는 다음 테이블로 전송될 수 있습니다.

테이블 설명
사용자 정의 테이블 Log Analytics 작업 영역에서 만드는 모든 사용자 지정 테이블입니다. 대상 테이블이 있어야 데이터를 보낼 수 있습니다. 사용자 지정 테이블에는 _CL 접미사가 있어야 합니다.
Azure 테이블 현재 다음 Azure 테이블이 지원됩니다. 다른 테이블은 지원이 구현될 때 이 목록에 추가될 수 있습니다.

참고 항목

열 이름은 문자로 시작해야 하며 최대 45자의 영숫자와 밑줄(_)로 구성될 수 있습니다. _ResourceId, id, _ResourceId, _SubscriptionId, TenantId, Type, UniqueId 및 Title은 예약된 열 이름입니다. Azure 테이블에 추가하는 사용자 지정 열에는 _CF 접미사가 있어야 합니다.

제한 사항

로그 수집 API와 관련된 제한은 Azure Monitor 서비스 제한을 참조하세요.

다음 단계