자습서 - 로그 수집 API를 사용하여 Azure Monitor에 데이터 보내기(Resource Manager 템플릿)

아티클
10/15/2024

Azure Monitor의 로그 수집 API를 사용하면 사용자 지정 데이터를 Log Analytics 작업 영역으로 보낼 수 있습니다. 이 자습서에서는 ARM 템플릿(Azure Resource Manager 템플릿)을 사용하여 API를 지원하는 데 필요한 구성 요소의 구성을 안내한 다음 REST API 및 .NET, Go, Java, JavaScript 및 Python용 클라이언트 라이브러리를 모두 사용하는 샘플 애플리케이션을 제공합니다.

참고 항목

이 자습서에서는 ARM 템플릿을 사용하여 로그 수집 API를 지원하는 데 필요한 구성 요소를 구성합니다. Azure Portal UI를 사용하여 이러한 구성 요소를 구성하는 유사한 자습서는 자습서: 로그 수집 API(Azure Portal)를 사용하여 Azure Monitor 로그에 데이터 보내기를 참조하세요.

로그 수집 API를 구성하는 데 필요한 단계는 다음과 같습니다.

API에 대해 인증할 Microsoft Entra 애플리케이션을 만듭니다.
Log Analytics 작업 영역에서 사용자 지정 표를 만듭니다. 이것은 데이터를 보낼 표입니다.
DCR(데이터 수집 규칙)을 만들어 데이터를 대상 테이블로 전달합니다.
Microsoft Entra 애플리케이션에 DCR에 대한 액세스 권한을 부여합니다.
로그 수집 API를 사용하여 데이터를 전송하는 샘플 코드는 로그 수집 API를 사용하여 Azure Monitor로 데이터를 보내는 샘플 코드를 참조하세요.

참고 항목

이 문서에는 DCR 수집 엔드포인트나 DCE(데이터 수집 엔드포인트)를 사용하기 위한 옵션이 포함되어 있습니다. 두 가지 중 하나를 사용할 수 있지만, 프라이빗 링크를 사용하는 경우 로그 수집 API에 DCE가 필요합니다. DCE가 필요한 경우는 언제인가요?를 참조하세요.

필수 조건

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

최소한 기여자 권한이 있는 Log Analytics 작업 영역.
작업 영역에서 DCR 개체를 만들 수 있는 권한입니다.

작업 영역 세부 정보 수집

먼저 작업 영역에서 필요한 정보를 수집합니다.

Azure Portal의 Log Analytics 작업 영역 메뉴의 작업 영역으로 이동합니다. 속성 페이지에서 리소스 ID를 복사하고 나중에 사용하기 위해 저장합니다.

Microsoft Entra 애플리케이션 만들기

먼저 API에 대해 인증할 Microsoft Entra 애플리케이션을 등록합니다. 모든 Resource Manager 인증 체계가 지원되지만 이 자습서에서는 클라이언트 자격 증명 부여 흐름 체계를 따릅니다.

Azure Portal의 Microsoft Entra ID 메뉴에서 앱 등록>새 등록을 선택합니다.
기본값이 환경에 적합하지 않은 경우 애플리케이션에 이름을 지정하고 테넌트 범위를 변경합니다. 리디렉션 URI는 필요하지 않습니다.
등록되면 애플리케이션의 세부 정보를 볼 수 있습니다. 애플리케이션(클라이언트) ID 및 디렉터리(테넌트) ID를 기록해 둡니다. 이 값은 나중에 프로세스에서 필요합니다.
이제 사용자 이름과 함께 사용할 암호를 만드는 것과 유사한 애플리케이션 클라이언트 암호를 만듭니다. 인증서 및 비밀>새 클라이언트 암호를 차례로 선택합니다. 비밀 이름을 지정하여 목적을 식별하고 만료 기간을 선택합니다. 여기서는 12개월 옵션이 선택되어 있습니다. 프로덕션 구현의 경우 비밀 순환 절차에 대한 모범 사례를 따르거나 인증서와 같은 보다 안전한 인증 모드를 사용합니다.
추가를 선택하여 비밀을 저장한 다음 값을 기록해 둡니다. 이 페이지를 나면 복구할 수 없으므로 이 값을 기록해야 합니다. 암호는 기능적으로 대체 가능한 제품이므로 암호를 안전하게 보관할 때와 동일한 보안 측정값을 사용합니다.

DCR 수집 엔드포인트를 사용하는 경우 DCE가 필요하지 않습니다.

Azure Monitor로 전송되는 데이터를 수락하려면 DCE가 필요합니다. DCE를 구성하고 DCR에 연결하면 애플리케이션에서 HTTP를 통해 데이터를 보낼 수 있습니다. DCE는 데이터가 전송될 DCR 및 Log Analytics 작업 영역과 동일한 지역에 있어야 합니다.

Azure Portal의 검색 상자에 템플릿을 입력한 다음 사용자 지정 템플릿 배포를 선택합니다.
편집기에서 사용자 고유의 템플릿을 빌드합니다.를 선택합니다.

편집기에 이 ARM 템플릿을 붙여넣고 저장을 선택합니다. 매개 변수에 대한 값을 제공하므로 이 템플릿을 수정할 필요가 없습니다.

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "dataCollectionEndpointName": {
            "type": "string",
            "metadata": {
                "description": "Specifies the name of the Data Collection Endpoint to create."
            }
        },
        "location": {
            "type": "string",
            "defaultValue": "westus2",
            "metadata": {
                "description": "Specifies the location for the Data Collection Endpoint."
            }
        }
    },
    "resources": [
        {
            "type": "Microsoft.Insights/dataCollectionEndpoints",
            "name": "[parameters('dataCollectionEndpointName')]",
            "location": "[parameters('location')]",
            "apiVersion": "2021-04-01",
            "properties": {
                "networkAcls": {
                "publicNetworkAccess": "Enabled"
                }
            }
        }
    ],
    "outputs": {
        "dataCollectionEndpointId": {
            "type": "string",
            "value": "[resourceId('Microsoft.Insights/dataCollectionEndpoints', parameters('dataCollectionEndpointName'))]"
        }
    }
}

사용자 지정 배포 화면에서 구독 및 리소스 그룹을 지정하여 DCR을 저장한 다음 값에 DCE의 이름을 제공합니다. 위치는 작업 영역과 동일한 위치여야 합니다. 지역은 이미 채워져 있으며 DCE의 위치에 사용됩니다.
검토 + 만들기를 선택한 다음, 세부 정보를 검토한 후 만들기를 선택합니다.
JSON 보기를 선택하여 DCE에 대한 다른 세부 정보를 봅니다. 이후 단계에서 필요한 리소스 ID 및 logsIngestion 엔드포인트 를 복사합니다.

Log Analytics 작업 영역에서 새 테이블 만들기

데이터를 보내기 전에 사용자 지정 테이블을 만들어야 합니다. 이 자습서의 표에는 아래 스키마에 설명된 대로 세 개의 열이 포함됩니다. name, type 및 description 속성은 각 열에 대해 필수입니다. 속성 isHidden과 isDefaultDisplay 둘 다 명시적으로 지정되지 않은 경우 기본값은 false입니다. 가능한 데이터 형식은 string, int, long, real, boolean, dateTime, guid 및 dynamic입니다.

참고 항목

이 자습서에서는 Azure Cloud Shell의 PowerShell을 사용하여 Azure Monitor Tables API를 사용하여 REST API를 호출합니다. 다른 방법을 사용하여 이러한 호출을 수행할 수 있습니다.

Important

사용자 지정 테이블은 _CL 접미사를 사용해야 합니다.

Azure Portal에서 Cloud Shell 단추를 선택하고 환경이 PowerShell로 설정되어 있는지 확인합니다.

다음 PowerShell 코드를 복사하고 Path 매개 변수의 변수를 Invoke-AzRestMethod 명령의 작업 영역에 대한 적절한 값으로 바꿉니다. Cloud Shell 프롬프트에 붙여넣어 실행합니다.

$tableParams = @'
{
    "properties": {
        "schema": {
            "name": "MyTable_CL",
            "columns": [
                {
                    "name": "TimeGenerated",
                    "type": "datetime",
                    "description": "The time at which the data was generated"
                },
               {
                    "name": "Computer",
                    "type": "string",
                    "description": "The computer that generated the data"
                },
                {
                    "name": "AdditionalContext",
                    "type": "dynamic",
                    "description": "Additional message properties"
                },
                {
                    "name": "CounterName",
                    "type": "string",
                    "description": "Name of the counter"
                },
                {
                    "name": "CounterValue",
                    "type": "real",
                    "description": "Value collected for the counter"
                }
            ]
        }
    }
}
'@

Invoke-AzRestMethod -Path "/subscriptions/{subscription}/resourcegroups/{resourcegroup}/providers/microsoft.operationalinsights/workspaces/{workspace}/tables/MyTable_CL?api-version=2022-10-01" -Method PUT -payload $tableParams

데이터 수집 규칙 만들기

DCR은 데이터가 수신되면 처리되는 방법을 정의합니다. 다음 내용이 포함됩니다.

엔드포인트로 전송되는 데이터의 스키마
작업 영역으로 전송되기 전에 데이터에 적용되는 변환
변환된 데이터가 전송될 대상 작업 영역 및 테이블

Azure Portal의 검색 상자에 템플릿을 입력한 다음 사용자 지정 템플릿 배포를 선택합니다.
편집기에서 사용자 고유의 템플릿을 빌드합니다.를 선택합니다.

편집기에 이 ARM 템플릿을 붙여넣고 저장을 선택합니다.

DCR 엔드포인트
DCE

이 템플릿에 정의된 DCR에서 다음 세부 정보를 확인합니다.

streamDeclarations: 들어오는 데이터의 열 정의입니다.
destinations: 대상 작업 영역입니다.
dataFlows: 스트림을 대상 작업 영역과 일치시키고 변환 쿼리 및 대상 테이블을 지정합니다. 대상 쿼리의 출력은 대상 테이블로 전송됩니다.

{
    "$schema": "https://schema.management.azure.com/schemas/2019-08-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "dataCollectionRuleName": {
            "type": "string",
            "metadata": {
                "description": "Specifies the name of the Data Collection Rule to create."
            }
        },
        "location": {
            "type": "string",
            "metadata": {
                "description": "Specifies the location in which to create the Data Collection Rule."
            }
        },
        "workspaceResourceId": {
            "type": "string",
            "metadata": {
                "description": "Specifies the Azure resource ID of the Log Analytics workspace to use."
            }
        }
    },
    "resources": [
        {
            "type": "Microsoft.Insights/dataCollectionRules",
            "name": "[parameters('dataCollectionRuleName')]",
            "location": "[parameters('location')]",
            "apiVersion": "2023-03-11",
            "kind": "Direct",
            "properties": {
                "streamDeclarations": {
                    "Custom-MyTableRawData": {
                        "columns": [
                            {
                                "name": "Time",
                                "type": "datetime"
                            },
                            {
                                "name": "Computer",
                                "type": "string"
                            },
                            {
                                "name": "AdditionalContext",
                                "type": "string"
                            },
                            {
                                "name": "CounterName",
                                "type": "string"
                            },
                            {
                                "name": "CounterValue",
                                "type": "real"
                            }
                        ]
                    }
                },
                "destinations": {
                    "logAnalytics": [
                        {
                            "workspaceResourceId": "[parameters('workspaceResourceId')]",
                            "name": "myworkspace"
                        }
                    ]
                },
                "dataFlows": [
                    {
                        "streams": [
                            "Custom-MyTableRawData"
                        ],
                        "destinations": [
                            "myworkspace"
                        ],
                        "transformKql": "source | extend jsonContext = parse_json(AdditionalContext) | project TimeGenerated = Time, Computer, AdditionalContext = jsonContext, CounterName=tostring(jsonContext.CounterName), CounterValue=toreal(jsonContext.CounterValue)",
                        "outputStream": "Custom-MyTable_CL"
                    }
                ]
            }
        }
    ],
    "outputs": {
        "dataCollectionRuleId": {
            "type": "string",
            "value": "[resourceId('Microsoft.Insights/dataCollectionRules', parameters('dataCollectionRuleName'))]"
        }
    }
}

이 템플릿에 정의된 DCR에서 다음 세부 정보를 확인합니다.

dataCollectionEndpointId: 데이터 컬렉션 엔드포인트의 리소스 ID입니다.
streamDeclarations: 들어오는 데이터의 열 정의입니다.
destinations: 대상 작업 영역입니다.
dataFlows: 스트림을 대상 작업 영역과 일치시키고 변환 쿼리 및 대상 테이블을 지정합니다. 대상 쿼리의 출력은 대상 테이블로 전송됩니다.

{
    "$schema": "https://schema.management.azure.com/schemas/2019-08-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "dataCollectionRuleName": {
            "type": "string",
            "metadata": {
                "description": "Specifies the name of the Data Collection Rule to create."
            }
        },
        "location": {
            "type": "string",
            "metadata": {
                "description": "Specifies the location in which to create the Data Collection Rule."
            }
        },
        "workspaceResourceId": {
            "type": "string",
            "metadata": {
                "description": "Specifies the Azure resource ID of the Log Analytics workspace to use."
            }
        },
        "endpointResourceId": {
            "type": "string",
            "metadata": {
                "description": "Specifies the Azure resource ID of the Data Collection Endpoint to use."
            }
        }
    },
    "resources": [
        {
            "type": "Microsoft.Insights/dataCollectionRules",
            "name": "[parameters('dataCollectionRuleName')]",
            "location": "[parameters('location')]",
            "apiVersion": "2023-03-11",
            "kind": "Direct",
            "properties": {
                "dataCollectionEndpointId": "[parameters('endpointResourceId')]",
                "streamDeclarations": {
                    "Custom-MyTableRawData": {
                        "columns": [
                            {
                                "name": "Time",
                                "type": "datetime"
                            },
                            {
                                "name": "Computer",
                                "type": "string"
                            },
                            {
                                "name": "AdditionalContext",
                                "type": "string"
                            },
                            {
                                "name": "CounterName",
                                "type": "string"
                            },
                            {
                                "name": "CounterValue",
                                "type": "real"
                            }
                        ]
                    }
                },
                "destinations": {
                    "logAnalytics": [
                        {
                            "workspaceResourceId": "[parameters('workspaceResourceId')]",
                            "name": "myworkspace"
                        }
                    ]
                },
                "dataFlows": [
                    {
                        "streams": [
                            "Custom-MyTableRawData"
                        ],
                        "destinations": [
                            "myworkspace"
                        ],
                        "transformKql": "source | extend jsonContext = parse_json(AdditionalContext) | project TimeGenerated = Time, Computer, AdditionalContext = jsonContext, CounterName=tostring(jsonContext.CounterName), CounterValue=toreal(jsonContext.CounterValue)",
                        "outputStream": "Custom-MyTable_CL"
                    }
                ]
            }
        }
    ],
    "outputs": {
        "dataCollectionRuleId": {
            "type": "string",
            "value": "[resourceId('Microsoft.Insights/dataCollectionRules', parameters('dataCollectionRuleName'))]"
        }
    }
}

사용자 지정 배포 화면에서 구독 및 리소스 그룹을 지정하여 DCR을 저장합니다. 그런 다음 템플릿에 정의된 값을 제공합니다. 이 값에는 DCR의 이름과 이전 단계에서 수집한 작업 영역 리소스 ID가 포함됩니다. 위치는 작업 영역과 동일한 위치여야 합니다. 지역은 이미 채워져 있으며 DCR의 위치에 사용됩니다.
검토 + 만들기를 선택한 다음, 세부 정보를 검토한 후 만들기를 선택합니다.
배포가 완료되면 배포 세부 정보 상자를 확장하고 DCR을 선택하여 세부 정보를 봅니다. JSON 보기를 선택합니다.
DCR에 대한 변경이 불가능한 ID와 로그 수집 URI를 복사합니다. API를 사용하여 Azure Monitor로 데이터를 보낼 때 이를 사용합니다.

DCR에 권한 할당

DCR이 만들어지면 애플리케이션에 권한을 부여해야 합니다. 권한을 통해 올바른 애플리케이션 ID와 애플리케이션 키를 사용하는 모든 애플리케이션이 새 DCR에 데이터를 보낼 수 있습니다.

Azure Portal의 DCR에서 액세스 제어(IAM)>역할 할당 추가를 선택합니다.
모니터링 메트릭 게시자를 선택하고 다음을 선택합니다. 대신 Microsoft.Insights/Telemetry/Write 데이터 작업으로 사용자 지정 작업을 만들 수 있습니다.
액세스 권한 할당에 대해 사용자, 그룹 또는 서비스 주체를 선택하고 멤버 선택을 선택합니다. 만든 애플리케이션을 선택하고 선택을 선택합니다.
검토 + 할당을 선택하고 역할 할당을 저장하기 전에 세부 정보를 확인합니다.