다음을 통해 공유


OpenTelemetry에서 Azure Data Explorer로 데이터 수집

Important

이 커넥터는 Microsoft Fabric의 실시간 인텔리전스 에서 사용할 수 있습니다. 다음 예외를 제외하고 이 문서의 지침을 사용합니다.

OTel(OpenTelemetry)은 애플리케이션 관찰 가능성을 위한 개방형 프레임워크입니다. 계측은 메트릭, 로그추적을 포함하여 관찰 가능성 데이터에 대한 표준 인터페이스를 제공하는 CNCF(Cloud Native Computing Foundation)에서 호스트합니다. OTel Collector는 다음 세 가지 구성 요소 로 구성됩니다. 수신기 는 수집기에 데이터를 가져오는 방법을 처리하고, 프로세서 는 수신된 데이터로 수행할 작업을 결정하며 , 내보내기는 수신된 데이터를 보낼 위치를 담당합니다.

Azure Data Explorer 내보내기는 여러 수신기에서 Azure Data Explorer로의 데이터 수집을 지원합니다.

참고 항목

이 문서에서는 다음 방법을 설명합니다.

  • 환경 설정
  • Azure Data Explorer 내보내기 구성
  • 샘플 애플리케이션 실행
  • 들어오는 데이터 쿼리

필수 구성 요소

환경 설정

이 섹션에서는 OTel 내보내기를 사용하도록 환경을 준비합니다.

Microsoft Entra 앱 등록 만들기

Microsoft Entra 애플리케이션 인증은 사용자가 없는 Azure Data Explorer에 액세스해야 하는 애플리케이션에 사용됩니다. OTel 내보내기를 사용하여 데이터를 수집하려면 Microsoft Entra 서비스 주체를 만들고 등록한 다음, 이 보안 주체에게 Azure Data Explorer 데이터베이스의 데이터를 수집하도록 권한을 부여해야 합니다.

  1. Azure Data Explorer 클러스터를 사용하여 Azure Data Explorer에서 Microsoft Entra 애플리케이션 등록 만들기의 1-7단계를 수행합니다.
  2. 이후 단계에서 사용할 다음 값을 저장합니다.
    • 애플리케이션(클라이언트) ID
    • 디렉터리(테넌트) ID
    • 클라이언트 비밀 키 값

Microsoft Entra 앱 권한 부여

  1. 웹 UI쿼리 탭에서 클러스터에 연결합니다. 연결하는 방법에 대한 자세한 내용은 클러스터 추가를 참조 하세요.

  2. 데이터를 수집하려는 데이터베이스로 찾습니다.

  3. 자리 표시자를 대체하여 다음 관리 명령을 실행합니다. DatabaseName을 대상 데이터베이스의 이름으로 바꾸고 ApplicationID를 이전에 저장된 값으로 바꿉니다. 이 명령은 앱에 데이터베이스 수집자 역할을 부여합니다. 자세한 내용은 데이터베이스 보안 역할 관리를 참조하세요.

    .add database <DatabaseName> ingestors ('aadapp=<ApplicationID>') 'Azure Data Explorer App Registration'
    

    참고 항목

    마지막 매개 변수는 데이터베이스와 연결된 역할을 쿼리할 때 메모로 표시되는 문자열입니다. 자세한 내용은 기존 보안 역할 보기를 참조하세요.

대상 테이블 만들기

  1. Azure Data Explorer 웹 UI로 이동합니다.

  2. 왼쪽 메뉴에서 쿼리를 선택합니다.

  3. 왼쪽 창에서 대상 클러스터를 확장합니다.

  4. 대상 데이터베이스를 선택하여 쿼리에 올바른 컨텍스트를 제공합니다.

  5. 다음 명령을 실행하여 들어오는 데이터에 대한 테이블 및 스키마 매핑을 만듭니다.

    .create-merge table <Logs-Table-Name> (Timestamp:datetime, ObservedTimestamp:datetime, TraceID:string, SpanID:string, SeverityText:string, SeverityNumber:int, Body:string, ResourceAttributes:dynamic, LogsAttributes:dynamic) 
    
    .create-merge table <Metrics-Table-Name> (Timestamp:datetime, MetricName:string, MetricType:string, MetricUnit:string, MetricDescription:string, MetricValue:real, Host:string, ResourceAttributes:dynamic,MetricAttributes:dynamic) 
    
    .create-merge table <Traces-Table-Name> (TraceID:string, SpanID:string, ParentID:string, SpanName:string, SpanStatus:string, SpanKind:string, StartTime:datetime, EndTime:datetime, ResourceAttributes:dynamic, TraceAttributes:dynamic, Events:dynamic, Links:dynamic) 
    

스트리밍 수집 설정

Azure Data Explorer에는 일괄 처리와 스트리밍이라는 두 가지 주요 수집 형식이 있습니다. 자세한 내용은 일괄 처리 및 스트리밍 처리를 참조하세요. 스트리밍 메서드는 Azure Data Explorer 내보내기 구성에서 관리되는 메서드라고 합니다. 근 실시간으로 로그 및 추적을 사용할 수 있어야 하는 경우 스트리밍 수집이 좋은 선택일 수 있습니다. 그러나 스트리밍 수집은 일괄 처리 수집보다 더 많은 리소스를 사용합니다. OTel 프레임워크 자체는 데이터를 일괄 처리하며, 수집에 사용할 방법을 선택할 때 고려해야 합니다.

참고

managed 옵션을 사용하려면 Azure Data Explorer 클러스터에서 스트리밍 수집을 사용하도록 설정해야 합니다. .show 데이터베이스 스트리밍 수집 정책 명령을 사용하여 스트리밍이 사용하도록 설정되었는지 확인할 수 있습니다.

세 테이블 각각에 대해 다음 명령을 실행하여 스트리밍 수집을 사용하도록 설정합니다.

.alter table <Table-Name> policy streamingingestion enable

Azure Data Explorer 내보내기 구성

OpenTelemetry 데이터를 Azure Data Explorer로 수집하려면 다음 Azure Data Explorer 내보내기 구성으로 OpenTelemetry 배포를 배포하고 실행해야 합니다.

  1. 다음 필드를 사용하여 Azure Data Explorer 내보내기를 구성합니다.

    필드 Description 권장되는 설정
    Exporters 내보내기의 형식 Azure Data Explorer
    cluster_uri 데이터베이스 및 테이블을 보유하는 Azure Data Explorer 클러스터의 URI https:// <cluster>.kusto.windows.net
    application_id 클라이언트 ID <애플리케이션 ID>
    application_key 클라이언트 암호 <애플리케이션 키>
    tenant_id 테넌트 <애플리케이션 테넌트>
    db_name 로그를 받는 데이터베이스 oteldb 또는 이미 만든 다른 데이터베이스
    metrics_table_name 내보낸 메트릭 데이터를 저장하는 데이터베이스 db_name의 대상 테이블입니다. OTELMetrics
    logs_table_name 내보낸 로그 데이터를 저장하는 데이터베이스 db_name의 대상 테이블입니다. OTELLogs
    traces_table_name 내보낸 추적 데이터를 저장하는 데이터베이스 db_name의 대상 테이블입니다. OTELTraces
    ingestion_type 수집 형식: 관리(스트리밍) 또는 일괄 처리 관리
    metrics_table_json_mapping 선택적 매개 변수입니다. 기본 테이블 매핑은 OTeL 메트릭 특성을 기반으로 테이블을 만드는 동안 정의됩니다. 이 매개 변수를 사용하여 기본 매핑을 변경할 수 있습니다. <json metrics_table_name mapping>
    logs_table_json_mapping 선택적 매개 변수입니다. 기본 테이블 매핑은 OTeL 로그 특성을 기반으로 테이블을 만드는 동안 정의됩니다. 이 매개 변수를 사용하여 기본 매핑을 변경할 수 있습니다. <json logs_table_name 매핑>
    traces_table_json_mapping 선택적 매개 변수입니다. 기본 테이블 매핑은 OTeL 추적 특성을 기반으로 테이블을 만드는 동안 정의됩니다. 이 매개 변수를 사용하여 기본 매핑을 변경할 수 있습니다. <json traces_table_name 매핑>
    traces 서비스: 사용하도록 설정할 구성 요소 추적 수신기: [otlp]
    processors: [batch]
    exporters: [azuredataexplorer]
    메트릭 서비스: 사용하도록 설정할 메트릭 구성 요소 수신기: [otlp]
    processors: [batch]
    exporters: [azuredataexplorer]
    로그 서비스: 사용하도록 설정할 로그 구성 요소 수신기: [otlp]
    processors: [batch]
    exporters: [ azuredataexplorer]
  2. "--config" 플래그를 사용하여 Azure Data Explorer 내보내기를 실행합니다.

다음은 Azure Data Explorer 내보내기에 대한 예제 구성입니다.

---
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
processors:
  batch:
exporters:
  azuredataexplorer:
    cluster_uri: "https://<cluster>.kusto.windows.net"
    application_id: "<application id>"
    application_key: "<application key>"
    tenant_id: "<application tenant>"
    db_name: "oteldb"
    metrics_table_name: "OTELMetrics"
    logs_table_name: "OTELLogs"
    traces_table_name: "OTELTraces"
    ingestion_type : "managed"
    metrics_table_json_mapping : "<json metrics_table_name mapping>"
    logs_table_json_mapping  : "<json logs_table_name mapping>"
    traces_table_json_mapping  : "<json traces_table_name mapping>"
service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [azuredataexplorer]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [azuredataexplorer]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [azuredataexplorer]

샘플 애플리케이션으로 데이터 수집

이제 수집기가 구성되었으므로 수집할 데이터를 보내야 합니다. 이 예제에서는 Java OTeL 수집기 에이전트와 함께 샘플 스프링 애완 동물 클리닉 애플리케이션을 사용합니다.

  1. 여기에서 수집기 에이전트 다운로드: 원격 분석 수집기 에이전트 열기.

  2. 샘플 애플리케이션에 대해 개방형 원격 분석을 사용하도록 설정하려면 다음 환경 변수를 설정합니다. open-telemetry-collector-host는 Azure Data Explorer 내보내기가 구성되고 실행되는 호스트를 참조합니다.

    $env:OTEL_SERVICE_NAME="pet-clinic-service"
    $env:OTEL_TRACES_EXPORTER="otlp"
    $env:OTEL_LOGS_EXPORTER="otlp "                   
    $env:OTEL_EXPORTER_OTLP_ENDPOINT="http://<open-telemetry-collector-host>:4317"
    
  3. 다음 명령줄 인수를 사용하여 샘플 spring-boot 애플리케이션을 실행합니다.

    java -javaagent:./opentelemetry-javaagent.jar -jar spring-petclinic-<version>-SNAPSHOT.jar    
    

들어오는 데이터 쿼리

샘플 앱이 실행되면 데이터가 Azure Data Explorer의 정의된 테이블에 수집되었습니다. 이러한 테이블은 OTel 수집기 구성에서 oteldb로 정의된 데이터베이스에 만들어졌습니다. 만든 테이블은 OTel 수집기 구성에서 정의되었습니다. 이 예에서는 OTELMetrics, OTELLogsOTELTraces라는 세 개의 테이블을 만들었습니다. 이 섹션에서는 각 테이블을 개별적으로 쿼리하여 사용 가능한 데이터의 작은 선택을 가져옵니다.

  1. Azure Data Explorer 웹 UI로 이동합니다.

  2. 왼쪽 메뉴에서 쿼리를 선택합니다.

  3. 왼쪽 창에서 대상 클러스터를 확장합니다.

  4. 쿼리에 올바른 컨텍스트를 제공하려면 oteldb 데이터베이스를 선택합니다.

  5. 다음 쿼리를 순차적으로 복사/붙여넣기하여 각 테이블에서 임의 개수의 행을 확인합니다.

    • 메트릭

      OTELMetrics
      |take 2
      

      다음 표와 비슷하지만 정확히 동일하지 않은 결과를 가져와야 합니다.

      타임스탬프 MetricName MetricType MetricUnit MetricDescription MetricValue 호스트 MetricAttributes ResourceAttributes
      2022-07-01T12:55:33Z http.server.active_requests 합계 requests 현재 진행 중인 동시 HTTP 요청 수 0 DESKTOP-SFS7RUQ {"http.flavor":"1.1", "http.host":"localhost:8080", "scope.name":"io.opentelemetry.tomcat-7.0", "scope.version":"1.14.0-alpha", "http.method":"GET", "http.scheme":"http"} {"host.name":"DESKTOP-SFS7RUQ", "process.command_line":"C:\Program Files\Java\jdk-18.0.1.1;bin;java.exe -javaagent:./opentelemetry-javaagent.jar", "process.runtime.description":"Oracle Corporation Java HotSpot(TM) 64-Bit Server VM 18.0.1.1+2-6", "process.runtime.version":"18.0.1.1+2-6", "telemetry.sdk.language":"java", "host.arch":"amd64", "process.runtime.name":"Java(TM) SE Runtime Environment", "telemetry.auto.version":"1.14.0", "telemetry.sdk.name":"opentelemetry", "os.type":"windows", "os.description":"Windows 11 10.0", "process.executable.path":"C:\Program Files\Java\jdk-18.0.1.1;bin;java.exe", "process.pid":5980, "service.name":"my-service", "telemetry.sdk.version":"1.14.0"}
      2022-07-01T12:55:33Z http.server.duration_sum 히스토그램 ms 인바운드 HTTP 요청 기간(샘플 합계) 114.9881 DESKTOP-SFS7RUQ {"http.flavor":"1.1", "http.host":"localhost:8080", "scope.name":"io.opentelemetry.tomcat-7.0", "scope.version":"1.14.0-alpha", "http.method":"GET", "http.scheme":"http", "http.route":"/owners/find", "http.status_code":200} {"host.name":"DESKTOP-SFS7RUQ", "process.command_line":"C:\Program Files\Java\jdk-18.0.1.1;bin;java.exe -javaagent:./opentelemetry-javaagent.jar", "process.runtime.description":"Oracle Corporation Java HotSpot(TM) 64-Bit Server VM 18.0.1.1+2-6", "process.runtime.version":"18.0.1.1+2-6", "telemetry.sdk.language":"java", "host.arch":"amd64", "process.runtime.name":"Java(TM) SE Runtime Environment", "telemetry.auto.version":"1.14.0", "telemetry.sdk.name":"opentelemetry", "os.type":"windows", "os.description":"Windows 11 10.0", "process.executable.path":"C:\Program Files\Java\jdk-18.0.1.1;bin;java.exe", "process.pid":5980, "service.name":"my-service", "telemetry.sdk.version":"1.14.0"}
    • 로그

      OTELLogs
      |take 2
      

      다음 표와 비슷하지만 정확히 동일하지 않은 결과를 가져와야 합니다.

      타임스탬프 TraceId SpanId SeverityText SeverityNumber 본문 ResourceAttributes LogsAttributes
      2022-07-01T13:00:39Z INFO 9 Starting PetClinicApplication v2.7.0-SNAPSHOT using Java 18.0.1.1 on DESKTOP-SFS7RUQ with PID 37280 (C:\Users\adxuser\Documents\Repos\spring-petclinic\target\spring-petclinic-2.7.0-SNAPSHOT.jar started by adxuser in C:\Users\adxuser\Documents\Repos\spring-petclinic) {"host.name":"DESKTOP-SFS7RUQ", "process.executable.path":"C:\Program Files\Java\jdk-18.0.1.1;bin;java.exe", "process.pid":37280, "process.runtime.description":"Oracle Corporation Java HotSpot(TM) 64-Bit Server VM 18.0.1.1+2-6", "process.runtime.name":"Java(TM) SE Runtime Environment", "telemetry.sdk.name":"opentelemetry", "os.type":"windows", "process.runtime.version":"18.0.1.1+2-6", "telemetry.sdk.language":"java", "telemetry.sdk.version":"1.14.0", "process.command_line":"C:\Program Files\Java\jdk-18.0.1.1;bin;java.exe -javaagent:./opentelemetry-javaagent.jar", "os.description":"Windows 11 10.0", "service.name":"my-service", "telemetry.auto.version":"1.14.0", "host.arch":"amd64"} {"scope.name":"org.springframework.samples.petclinic.PetClinicApplication"}
      2022-07-01T13:00:39Z INFO 9 활성 프로필 집합 없음, 기본 프로필 1개로 대체: "default" {"host.name":"DESKTOP-SFS7RUQ", "process.executable.path":"C:\Program Files\Java\jdk-18.0.1.1;bin;java.exe", "process.pid":37280, "process.runtime.description":"Oracle Corporation Java HotSpot(TM) 64-Bit Server VM 18.0.1.1+2-6", "process.runtime.name":"Java(TM) SE Runtime Environment", "telemetry.sdk.name":"opentelemetry", "os.type":"windows", "process.runtime.version":"18.0.1.1+2-6", "telemetry.sdk.language":"java", "telemetry.sdk.version":"1.14.0", "process.command_line":"C:\Program Files\Java\jdk-18.0.1.1;bin;java.exe -javaagent:./opentelemetry-javaagent.jar", "os.description":"Windows 11 10.0", "service.name":"my-service", "telemetry.auto.version":"1.14.0", "host.arch":"amd64"} {"scope.name":"org.springframework.samples.petclinic.PetClinicApplication"}
    • Traces

      OTELTraces
      |take 2
      

      다음 표와 비슷하지만 정확히 동일하지 않은 결과를 가져와야 합니다.

      TraceId SpanId ParentId SpanName SpanStatus SpanKind StartTime EndTime ResourceAttributes TraceAttributes 이벤트 링크
      573c0e4e002a9f7281f6d63eafe4ef87 dab70d0ba8902c5e 87d003d6-02c1-4f3d-8972-683243c35642 STATUS_CODE_UNSET SPAN_KIND_CLIENT 2022-07-01T13:17:59Z 2022-07-01T13:17:59Z {"telemetry.auto.version":"1.14.0", "os.description":"Windows 11 10.0", "process.executable.path":"C:\Program Files\Java\jdk-18.0.1.1;bin;java.exe", "process.runtime.description":"Oracle Corporation Java HotSpot(TM) 64-Bit Server VM 18.0.1.1+2-6", "service.name":"my-service", "process.runtime.name":"Java(TM) SE Runtime Environment", "telemetry.sdk.language":"java", "telemetry.sdk.name":"opentelemetry", "host.arch":"amd64", "host.name":"DESKTOP-SFS7RUQ", "process.pid":34316, "process.runtime.version":"18.0.1.1+2-6", "os.type":"windows", "process.command_line":"C:\Program Files\Java\jdk-18.0.1.1;bin;java.exe -javaagent:./opentelemetry-javaagent.jar", "telemetry.sdk.version":"1.14.0"} {"db.user":"sa", "thread.id":1, "db.name":"87d003d6-02c1-4f3d-8972-683243c35642", "thread.name":"main", "db. system":"h2", "scope.name":"io.opentelemetry.jdbc", "scope.version":"1.14.0-alpha", "db.connection_string":"h2:mem:", "db .statement":"DROP TABLE vet_specialties IF EXISTS"} [] []
      84a9a8c4009d91476da02dfa40746c13 3cd4c0e91717969a 87d003d6-02c1-4f3d-8972-683243c35642 STATUS_CODE_UNSET SPAN_KIND_CLIENT 2022-07-01T13:17:59Z 2022-07-01T13:17:59Z {"telemetry.auto.version":"1.14.0", "os.description":"Windows 11 10.0", "process.executable.path":"C:\Program Files\Java\jdk-18.0.1.1;bin;java.exe", "process.runtime.description":"Oracle Corporation Java HotSpot(TM) 64-Bit Server VM 18.0.1.1+2-6", "service.name":"my-service", "process.runtime.name":"Java(TM) SE Runtime Environment", "telemetry.sdk.language":"java", "telemetry.sdk.name":"opentelemetry", "host.arch":"amd64", "host.name":"DESKTOP-SFS7RUQ", "process.pid":34316, "process.runtime.version":"18.0.1.1+2-6", "os.type":"windows", "process.command_line":"C:\Program Files\Java\jdk-18.0.1.1;bin;java.exe -javaagent:./opentelemetry-javaagent.jar", "telemetry.sdk.version":"1.14.0"} {"db.user":"sa", "thread.id":1, "db.name":"87d003d6-02c1-4f3d-8972-683243c35642", "thread.name":"main", "db.system":"h2", "scope.name":"io.opentelemetry.jdbc", "scope.version":"1.14.0-alpha", "db.connection_string":"h2:mem:", "db.statement":"DROP TABLE vets IF EXISTS"} [] []

추가 데이터 처리

업데이트 정책을 사용하면 수집된 데이터를 애플리케이션 필요에 따라 추가로 처리할 수 있습니다. 자세한 내용은 업데이트 정책 개요를 참조하세요.

  1. 다음 예에서는 히스토그램 메트릭을 버킷 및 집계가 있는 히스토그램별 테이블로 내보냅니다. Azure Data Explorer 웹 UI의 쿼리 창에서 다음 명령을 실행합니다.

    .create table HistoBucketData (Timestamp: datetime, MetricName: string , MetricType: string , Value: double, LE: double, Host: string , ResourceAttributes: dynamic, MetricAttributes: dynamic )
    
    .create function 
    with ( docstring = "Histo bucket processing function", folder = "UpdatePolicyFunctions") ExtractHistoColumns()
    {
        OTELMetrics
        | where MetricType == 'Histogram' and MetricName has "_bucket"
        | extend f=parse_json(MetricAttributes)
        | extend le=todouble(f.le)
        | extend M_name=replace_string(MetricName, '_bucket','')
        | project Timestamp, MetricName=M_name, MetricType, MetricValue, LE=le, Host, ResourceAttributes, MetricAttributes
    }
    
    .alter table HistoBucketData policy update 
    @'[{ "IsEnabled": true, "Source": "OTELMetrics","Query": "ExtractHistoColumns()", "IsTransactional": false, "PropagateIngestionProperties": false}]'
    
  2. 다음 명령은 히스토그램 메트릭 형식의 개수 및 합계 값만 포함하고 업데이트 정책을 첨부하는 테이블을 만듭니다. Azure Data Explorer 웹 UI의 쿼리 창에서 다음 명령을 실행합니다.

     .create table HistoData (Timestamp: datetime, MetricName: string , MetricType: string , Count: double, Sum: double, Host: string , ResourceAttributes: dynamic, MetricAttributes: dynamic)
    
     .create function 
    with ( docstring = "Histo sum count processing function", folder = "UpdatePolicyFunctions") ExtractHistoCountColumns()
    {
       OTELMetrics
        | where MetricType =='Histogram'
        | where MetricName has "_count"
        | extend Count=MetricValue
        | extend M_name=replace_string(MetricName, '_bucket','')
        | join kind=inner (OTELMetrics
        | where MetricType =='Histogram'
        | where MetricName has "_sum"
        | project Sum = MetricValue , Timestamp)
     on Timestamp | project Timestamp, MetricName=M_name, MetricType, Count, Sum, Host, ResourceAttributes, MetricAttributes
    }
    
    .alter table HistoData policy update 
    @'[{ "IsEnabled": true, "Source": "RawMetricsData","Query": "ExtractHistoCountColumns()", "IsTransactional": false, "PropagateInge