LightIngest를 사용하여 Azure Data Explorer에 데이터 수집

  • 아티클

LightIngest는 Azure Data Explorer 임시 데이터 수집을 위한 명령줄 유틸리티입니다. 유틸리티는 로컬 폴더, Azure Blob Storage 컨테이너 또는 Amazon S3 버킷에서 원본 데이터를 가져올 수 있습니다.

LightIngest는 수집 기간에 시간 제약이 없으므로 많은 양의 데이터를 수집하려는 경우에 가장 유용합니다. 또한 나중에 수집한 시간이 아니라 만든 시간에 따라 레코드를 쿼리하려는 경우에도 유용합니다.

LightIngest 명령을 자동으로 생성하는 방법에 대한 예제는 기록 데이터 수집을 참조하세요.

참고

수집 가능한 최대 파일 크기는 6GB입니다. 100MB에서 1GB 사이의 파일을 수집하는 것이 좋습니다.

사전 요구 사항

LightIngest 실행

LightIngest를 실행하려면 다음을 수행합니다.

  1. 명령 프롬프트에서 LightIngest를 입력한 다음, 관련 명령줄 인수를 입력합니다.

    팁

    지원되는 명령줄 인수 목록을 보려면 LightIngest /help를 입력하세요.

  2. ingest-를 입력한 다음, 수집을 관리할 Azure Data Explorer 클러스터에 대한 연결 문자열을 입력합니다. 연결 문자열을 큰따옴표로 묶고, Kusto 연결 문자열 사양을 따릅니다.

    예를 들어 다음과 같습니다.

    LightIngest "https://ingest-{Cluster name and region}.kusto.windows.net;Fed=True" -db:{Database} -table:Trips -source:"https://{Account}.blob.core.windows.net/{ROOT_CONTAINER};{StorageAccountKey}" -pattern:"*.csv.gz" -format:csv -limit:2 -ignoreFirst:true -cr:10.0 -dontWait:true

성능 권장 사항

  • 수집 부하를 가장 잘 관리하고 일시적인 오류에서 복구하려면 에서 https://ingest-{yourClusterNameAndRegion}.kusto.windows.net수집 엔드포인트를 사용합니다.

  • 최적의 수집 성능을 위해 LightIngest에서 압축되지 않은 로컬 파일의 크기를 예측할 수 있도록 원시 데이터 크기가 필요합니다. 그러나 LightIngest는 먼저 압축된 Blob을 다운로드하지 않고는 해당 원시 크기를 올바르게 예측하지 못할 수 있습니다. 따라서 압축된 Blob을 수집하는 경우 Blob 메타데이터의 rawSizeBytes 속성을 압축되지 않은 데이터 크기(바이트)로 설정합니다.

명령줄 인수

인수 형식 Description 필수
string 수집을 처리하는 Kusto 엔드포인트를 지정하는 Kusto 연결 문자열. 이 값은 큰따옴표로 묶어야 합니다. ✔️
-database, -db string 대상 Azure Data Explorer 데이터베이스 이름입니다.
-table string 대상 Azure Data Explorer 테이블 이름입니다. ✔️
-sourcePath, -source string 로컬 파일 경로, Azure Blob 컨테이너의 루트 URI 또는 Amazon S3 버킷의 URI일 수 있는 원본 데이터의 위치입니다. 데이터가 Azure Blob에 저장된 경우 URI에는 스토리지 계정 키 또는 SAS(공유 액세스 서명)가 포함되어야 합니다. 데이터가 S3 버킷에 있는 경우 URI에는 자격 증명 키가 포함되어야 합니다. 이 값을 큰따옴표로 묶는 것이 좋습니다. 자세한 내용은 스토리지 연결 문자열을 참조하세요. Pass -sourcePath:; 가장 하여 사용자 권한이 있는 Azure Storage 항목을 나열합니다(사용자 프롬프트 권한 부여). ✔️
-managedIdentity, -mi string 연결에 사용할 관리 ID(사용자 할당 또는 시스템 할당)의 클라이언트 ID입니다. 시스템 할당 ID에 "시스템"을 사용합니다.
-ingestWithManagedIdentity, -imgestmi string 연결에 사용할 관리 ID(사용자 할당 또는 시스템 할당)의 클라이언트 ID입니다. 시스템 할당 ID에 "시스템"을 사용합니다.
-connectToStorageWithUserAuth, -storageUserAuth string 사용자 자격 증명을 사용하여 데이터 원본 스토리지 서비스에 인증합니다. 이 값에 대한 옵션은 또는 DEVICE_CODE입니다PROMPT.
-connectToStorageLoginUri, -storageLoginUri string 이 설정된 경우 -connectToStorageWithUserAuth 필요에 따라 Microsoft Entra ID 로그인 URI를 제공할 수 있습니다.
-prefix string 수집할 원본 데이터가 Blob 스토리지에 있는 경우 이 URL 접두사는 컨테이너 이름을 제외한 모든 Blob에서 공유됩니다.
예를 들어 데이터가 MyContainer/Dir1/Dir2에 있는 경우 접두사는 Dir1/Dir2여야 합니다. 이 값을 큰따옴표로 묶는 것이 좋습니다.
-pattern string 원본 파일/Blob이 선택되는 패턴입니다. 와일드카드를 지원합니다. 예: "*.csv". 이 값을 큰따옴표로 묶는 것이 좋습니다.
-zipPattern string ZIP 보관 파일에서 수집할 파일을 선택할 때 사용할 정규식입니다. 보관 파일의 다른 모든 파일은 무시됩니다. 예: "*.csv". 이 값을 큰따옴표로 묶는 것이 좋습니다.
-format, -f string 원본 데이터 형식입니다. 지원되는 형식 중 하나여야 합니다.
-ingestionMappingPath, -mappingPath string 수집 열 매핑을 위한 로컬 파일의 경로입니다. 데이터 매핑을 참조하세요.
-ingestionMappingRef, -mappingRef string 테이블에서 이전에 만든 수집 열 매핑의 이름입니다. 데이터 매핑을 참조하세요.
-creationTimePattern string 설정되면 파일 또는 Blob 경로에서 CreationTime 속성을 추출하는 데 사용됩니다. 를 사용하여 CreationTime데이터를 수집하는 방법을 참조하세요.
-ignoreFirstRow, -ignoreFirst bool 설정하면 각 파일/Blob의 첫 번째 레코드가 무시됩니다. 예를 들어 원본 데이터에 헤더가 있는 경우입니다.
-tag string 수집된 데이터와 연결할 태그입니다. 여러 개의 발생이 허용됩니다.
-dontWait bool 로 true설정하면 수집이 완료될 때까지 기다리지 않습니다. 많은 양의 파일/Blob을 수집할 때 유용합니다.
-compression, -cr double 압축 비율 힌트입니다. Azure Data Explorer에서 원시 데이터 크기를 평가하는 데 도움이 되도록 압축 파일/Blob을 수집하는 경우에 유용합니다. 원래 크기로 압축된 크기로 나눈 값으로 계산됩니다.
-limit, -l integer 설정된 경우 수집을 첫 번째 N 파일로 제한합니다.
-listOnly, -list bool 설정된 경우 수집을 위해 선택한 항목만 표시합니다.
-ingestTimeout 정수 모든 수집 작업을 완료하는 데 적용되는 시간 제한(분)입니다. 기본값은 60입니다.
-forceSync bool 설정되면 동기 수집을 강제로 수행합니다. 기본값은 false입니다.
-대화형 bool 로 false설정하면 인수 확인 메시지가 표시되지 않습니다. 무인 흐름 및 비대화형 환경의 경우. 기본값은 true입니다.
-dataBatchSize 정수 각 수집 작업의 총 크기 제한(MB, 압축되지 않음)을 설정합니다.
-filesInBatch 정수 각 수집 작업의 파일/Blob 개수 제한을 설정합니다.
-devTracing, -trace string 설정된 경우 진단 로그는 로컬 디렉터리에 기록됩니다(기본적으로 RollingLogs 현재 디렉터리에서 또는 스위치 값을 설정하여 수정할 수 있음).

Azure Blob 관련 기능

Azure Blob과 함께 사용하는 경우 LightIngest는 특정 Blob 메타데이터 속성을 사용하여 수집 프로세스를 보강합니다.

메타데이터 속성 사용
rawSizeBytes, kustoUncompressedSizeBytes 설정되면 압축되지 않은 데이터 크기로 해석됩니다.
kustoCreationTime, kustoCreationTimeUtc UTC 타임스탬프로 해석됩니다. 설정되면 Kusto에서 만든 시간을 재정의하는 데 사용됩니다. 백필 시나리오에 유용합니다.

사용 예

다음 예제에서는 운영 체제에 LightIngest 이진 파일을 설치했다고 가정합니다. LightIngest를 .NET 도구로 설치한 경우 예제에서 을 로 대체 LightIngestLightIngest 합니다.

CreationTime 속성을 사용하여 기록 데이터 수집

기존 시스템에서 Azure Data Explorer 기록 데이터를 로드하면 모든 레코드가 동일한 수집 날짜를 받습니다. 데이터를 수집 시간이 아니라 만든 시간을 기준으로 분할하도록 설정하려면 -creationTimePattern 인수를 사용할 수 있습니다. -creationTimePattern 인수는 파일 또는 Blob 경로에서 CreationTime 속성을 추출합니다. 패턴은 전체 항목 경로를 반영할 필요가 없으며, 사용하려는 타임스탬프를 포함하는 섹션만 반영합니다.

인수 값은 다음을 포함해야 합니다.

  • 타임스탬프 형식 바로 앞에 있는 상수 텍스트(작은따옴표(접두사)로 묶음)
  • 표준 .NET 날짜/시간 표기법의 타임스탬프 형식
  • 타임스탬프(접미사) 바로 뒤에 있는 상수 텍스트

중요

만든 시간을 재정의하도록 지정하는 경우 대상 테이블의 유효 익스텐트 병합 정책에 있는 Lookback 속성이 파일 또는 Blob 경로의 값과 일치하는지 확인하세요.

예제

  • historicalvalues19840101.parquet와 같은 날짜/시간이 포함된 Blob 이름(타임스탬프는 연도에 대해 4자리, 월에 대해 2자리, 월의 날짜에 대해 2자리임)의 경우

    -creationTimePattern 인수의 값은 파일 이름의 일부( "'historicalvalues'yyyyMMdd'.parquet'" )입니다.

    LightIngest "https://ingest-{Cluster name and region}.kusto.windows.net;Fed=True" -db:{Database} -table:Trips -source:"https://{Account}.blob.core.windows.net/{ROOT_CONTAINER};{StorageAccountKey}" -creationTimePattern:"'historicalvalues'yyyyMMdd'.parquet'"
 -pattern:"*.parquet" -format:parquet -limit:2 -cr:10.0 -dontWait:true

  • https://storageaccount/mycontainer/myfolder/2002/12/01/blobname.extension과 같은 계층 구조 폴더 구조를 참조하는 Blob URI의 경우

    -creationTimePattern 인수의 값은 폴더 구조의 일부( "'folder/'yyyy/MM/dd'/blob'" )입니다.

      LightIngest "https://ingest-{Cluster name and region}.kusto.windows.net;Fed=True" -db:{Database} -table:Trips -source:"https://{Account}.blob.core.windows.net/{ROOT_CONTAINER};{StorageAccountKey}" -creationTimePattern:"'mycontainer/myfolder/'yyyy/MM/dd'/'"
   -pattern:"*.csv.gz" -format:csv -limit:2 -ignoreFirst:true -cr:10.0 -dontWait:true

스토리지 계정 키 또는 SAS 토큰을 사용하여 Blob 수집

  • CONT 컨테이너 아래의 DIR 폴더에 있는 지정된 ACCOUNT 스토리지 계정에서 *.csv.gz 패턴과 일치하는 10개의 Blob을 수집합니다.
  • 대상은 DB 데이터베이스의 TABLE 테이블이며, MAPPING 수집 매핑이 대상에 미리 만들어져 있습니다.
  • 수집 작업이 완료될 때까지 도구가 대기합니다.
  • 대상 데이터베이스 및 스토리지 계정 키와 SAS 토큰을 지정하는 다양한 옵션을 확인합니다.
LightIngest "https://ingest-{ClusterAndRegion}.kusto.windows.net;Fed=True"
  -database:DB
  -table:TABLE
  -source:"https://ACCOUNT.blob.core.windows.net/{ROOT_CONTAINER};{StorageAccountKey}"
  -prefix:"DIR"
  -pattern:*.csv.gz
  -format:csv
  -mappingRef:MAPPING
  -limit:10

LightIngest "https://ingest-{ClusterAndRegion}.kusto.windows.net;Fed=True;Initial Catalog=DB"
  -table:TABLE
  -source:"https://ACCOUNT.blob.core.windows.net/{ROOT_CONTAINER}?{SAS token}"
  -prefix:"DIR"
  -pattern:*.csv.gz
  -format:csv
  -mappingRef:MAPPING
  -limit:10

컨테이너의 모든 Blob 수집(헤더 행 제외)

  • CONT 컨테이너 아래의 DIR1/DIR2 폴더에 있는 지정된 ACCOUNT 스토리지 계정에서 *.csv.gz 패턴과 일치하는 모든 Blob을 수집합니다.
  • 대상은 DB 데이터베이스의 TABLE 테이블이며, MAPPING 수집 매핑이 대상에 미리 만들어져 있습니다.
  • 원본 Blob에 헤더 줄이 포함되어 있으므로 각 Blob의 첫 번째 레코드를 삭제하도록 도구에 지시합니다.
  • 이 도구는 수집을 위해 데이터를 게시하고 수집 작업이 완료되기를 기다리지 않습니다.
LightIngest "https://ingest-{ClusterAndRegion}.kusto.windows.net;Fed=True"
  -database:DB
  -table:TABLE
  -source:"https://ACCOUNT.blob.core.windows.net/{ROOT_CONTAINER}?{SAS token}"
  -prefix:"DIR1/DIR2"
  -pattern:*.csv.gz
  -format:csv
  -mappingRef:MAPPING
  -ignoreFirstRow:true

경로에서 모든 JSON 파일 수집

  • PATH 경로 아래에서 *.json 패턴과 일치하는 모든 파일을 수집합니다.
  • 대상은 DB 데이터베이스의 TABLE 테이블이며, 수집 매핑은 MAPPING_FILE_PATH 로컬 파일에 정의되어 있습니다.
  • 이 도구는 수집을 위해 데이터를 게시하고 수집 작업이 완료되기를 기다리지 않습니다.
LightIngest "https://ingest-{ClusterAndRegion}.kusto.windows.net;Fed=True"
  -database:DB
  -table:TABLE
  -source:"PATH"
  -pattern:*.json
  -format:json
  -mappingPath:"MAPPING_FILE_PATH"

파일 수집 및 진단 추적 파일 쓰기

  • PATH 경로 아래에서 *.json 패턴과 일치하는 모든 파일을 수집합니다.
  • 대상은 DB 데이터베이스의 TABLE 테이블이며, 수집 매핑은 MAPPING_FILE_PATH 로컬 파일에 정의되어 있습니다.
  • 이 도구는 수집을 위해 데이터를 게시하고 수집 작업이 완료되기를 기다리지 않습니다.
  • 진단 추적 파일은 폴더 아래에 로컬로 기록됩니다. LOGS_PATH
LightIngest "https://ingest-{ClusterAndRegion}.kusto.windows.net;Fed=True"
  -database:DB
  -table:TABLE
  -source:"PATH"
  -pattern:*.json
  -format:json
  -mappingPath:"MAPPING_FILE_PATH"
  -trace:"LOGS_PATH"