Python용 Azure Monitor 수집 클라이언트 라이브러리 - 버전 1.0.3

  • 아티클

Azure Monitor 수집 클라이언트 라이브러리는 로그 수집 API를 사용하여 Azure Monitor에 사용자 지정 로그를 보내는 데 사용됩니다.

이 라이브러리를 사용하면 거의 모든 원본에서 지원되는 기본 제공 테이블 또는 Log Analytics 작업 영역에서 만든 사용자 지정 테이블로 데이터를 보낼 수 있습니다. 사용자 지정 열을 사용하여 기본 제공 테이블의 스키마를 확장할 수도 있습니다.

리소스:

시작

필수 구성 요소

패키지 설치

pip를 사용하여 Python용 Azure Monitor 수집 클라이언트 라이브러리를 설치합니다.

pip install azure-monitor-ingestion

클라이언트 만들기

Azure Monitor에 로그를 업로드하려면 인증된 클라이언트가 필요합니다. 라이브러리에는 클라이언트의 동기 및 비동기 양식이 모두 포함됩니다. 인증하려면 토큰 자격 증명의 instance 만듭니다. 를 만들 LogsIngestionClient때 해당 instance 사용합니다. 다음 예제에서는 azure-identity 패키지에서 를 사용합니다DefaultAzureCredential.

동기 클라이언트

로그를 업로드하기 위한 동기 클라이언트를 만드는 다음 예제를 고려합니다.

import os
from azure.identity import DefaultAzureCredential
from azure.monitor.ingestion import LogsIngestionClient

endpoint = os.environ['DATA_COLLECTION_ENDPOINT']
credential = DefaultAzureCredential()
logs_client = LogsIngestionClient(endpoint, credential)

비동기 클라이언트

클라이언트 API의 비동기 양식은 접미사가 있는 네임스페이 .aio스에 있습니다. 예:

import os
from azure.identity.aio import DefaultAzureCredential
from azure.monitor.ingestion.aio import LogsIngestionClient

endpoint = os.environ['DATA_COLLECTION_ENDPOINT']
credential = DefaultAzureCredential()
logs_client = LogsIngestionClient(endpoint, credential)

비공용 Azure 클라우드에 대한 클라이언트 구성

기본적으로 는 LogsIngestionClient 퍼블릭 Azure 클라우드에 연결하도록 구성됩니다. 비공용 Azure 클라우드에 연결하려면 몇 가지 추가 구성이 필요합니다. 키워드(keyword) 인수를 사용하여 credential_scopes 인증에 적합한 scope 제공해야 합니다. 다음 예제에서는 Azure 미국 정부에 연결하도록 클라이언트를 구성하는 방법을 보여줍니다.

logs_client = LogsIngestionClient(endpoint, credential_scopes=["https://monitor.azure.us//.default"])

주요 개념

데이터 수집 엔드포인트

DCE(데이터 컬렉션 엔드포인트)를 사용하면 Azure Monitor에 대한 수집 설정을 고유하게 구성할 수 있습니다. 이 문서에서 는 해당 콘텐츠 및 구조를 포함한 데이터 수집 엔드포인트의 개요와 이를 만들고 작업하는 방법을 제공합니다.

데이터 수집 규칙

DCR(데이터 수집 규칙)은 Azure Monitor에서 수집한 데이터를 정의하고 해당 데이터를 보내거나 저장해야 하는 방법과 위치를 지정합니다. REST API 호출은 사용할 DCR을 지정해야 합니다. 단일 DCE는 여러 DCR을 지원할 수 있으므로 다른 원본 및 대상 테이블에 대해 다른 DCR을 지정할 수 있습니다.

DCR은 입력 데이터의 구조와 대상 테이블의 구조를 이해해야 합니다. 두 구조가 일치하지 않으면 변환 을 사용하여 원본 데이터를 대상 테이블과 일치하도록 변환할 수 있습니다. 변환을 사용하여 원본 데이터를 필터링하고 다른 계산 또는 변환을 수행할 수도 있습니다.

자세한 내용은 Azure Monitor의 데이터 수집 규칙을 참조하고 DCR 구조에 대한 자세한 내용은 이 문서를 참조하세요. DCR ID를 검색하는 방법에 대한 자세한 내용은 이 자습서를 참조하세요.

Log Analytics 작업 영역 테이블

사용자 지정 로그는 사용자가 만든 모든 사용자 지정 테이블과 Log Analytics 작업 영역의 특정 기본 제공 테이블로 데이터를 보낼 수 있습니다. 대상 테이블이 있어야 데이터를 보낼 수 있습니다. 현재 지원되는 기본 제공 테이블은 다음과 같습니다.

로그 검색

이 라이브러리를 사용하여 업로드된 로그는 Azure Monitor 쿼리 클라이언트 라이브러리를 사용하여 쿼리할 수 있습니다.

예제

사용자 지정 로그 업로드

이 예제에서는 Azure Monitor에 로그 업로드를 보여 줍니다.

import os

from azure.core.exceptions import HttpResponseError
from azure.identity import DefaultAzureCredential
from azure.monitor.ingestion import LogsIngestionClient

endpoint = os.environ['DATA_COLLECTION_ENDPOINT']
credential = DefaultAzureCredential()

client = LogsIngestionClient(endpoint=endpoint, credential=credential, logging_enable=True)

rule_id = os.environ['LOGS_DCR_RULE_ID']
body = [
      {
        "Time": "2021-12-08T23:51:14.1104269Z",
        "Computer": "Computer1",
        "AdditionalContext": "context-2"
      },
      {
        "Time": "2021-12-08T23:51:14.1104269Z",
        "Computer": "Computer2",
        "AdditionalContext": "context"
      }
    ]

try:
    client.upload(rule_id=rule_id, stream_name=os.environ['LOGS_DCR_STREAM_NAME'], logs=body)
except HttpResponseError as e:
    print(f"Upload failed: {e}")

사용자 지정 오류 처리로 업로드

사용자 지정 오류 처리를 사용하여 로그를 업로드하려면 콜백 함수를 메서드의 upload 매개 변수에 on_error 전달할 수 있습니다. 콜백 함수는 업로드 중에 발생하는 각 오류에 대해 호출되며 개체에 해당하는 LogsUploadError 인수 하나가 필요합니다. 이 개체에는 발생한 오류와 업로드에 실패한 로그 목록이 포함됩니다.

# Example 1: Collect all logs that failed to upload.
failed_logs = []
def on_error(error):
    print("Log chunk failed to upload with error: ", error.error)
    failed_logs.extend(error.failed_logs)

# Example 2: Ignore all errors.
def on_error_pass(error):
    pass

client.upload(rule_id=rule_id, stream_name=os.environ['LOGS_DCR_STREAM_NAME'], logs=body, on_error=on_error)

문제 해결

다양한 오류 시나리오 진단에 대한 자세한 내용은 문제 해결 가이드를 참조하세요.

다음 단계

Azure Monitor에 대한 자세한 내용은 Azure Monitor 서비스 설명서를 참조하세요.

샘플

다음 코드 샘플은 Azure Monitor 수집 클라이언트 라이브러리를 사용하는 일반적인 시나리오를 보여 줍니다.

로그 수집 샘플

참여

이 프로젝트에 대한 기여와 제안을 환영합니다. 대부분의 경우 기여하려면 권한을 부여하며 실제로 기여를 사용할 권한을 당사에 부여한다고 선언하는 CLA(기여자 라이선스 계약)에 동의해야 합니다. 자세한 내용은 cla.microsoft.com.

끌어오기 요청을 제출하면 CLA-bot은 CLA를 제공하고 PR을 적절하게 데코레이팅해야 하는지 여부를 자동으로 결정합니다(예: 레이블, 설명). 봇에서 제공하는 지침을 따르기만 하면 됩니다. CLA를 사용하여 모든 리포지토리에서 한 번만 수행하면 됩니다.

이 프로젝트는 Microsoft 오픈 소스 준수 사항을 채택했습니다. 자세한 내용은 준수 사항 FAQ를 참조하거나 opencode@microsoft.com에 추가 질문 또는 의견을 알려주세요.