OpenTelemetry 데이터 흐름 엔드포인트 구성(미리 보기)

중요합니다

이 페이지에는 미리 보기 상태인 Kubernetes 배포 매니페스트를 사용하여 Azure IoT Operations 구성 요소를 관리하기 위한 지침이 포함되어 있습니다. 이 기능은 몇 가지 제한 사항을 제공하며 프로덕션 워크로드에 사용하면 안 됩니다.

베타, 미리 보기로 제공되거나 아직 일반 공급으로 릴리스되지 않은 Azure 기능에 적용되는 약관은 Microsoft Azure 미리 보기에 대한 추가 사용 약관을 참조하세요.

OpenTelemetry 데이터 흐름 엔드포인트는 메트릭 및 로그를 OpenTelemetry 수집기로 보내는 데 사용되며, 그러면 이는 Grafana 대시보드 및 Azure Monitor와 같은 가시성 플랫폼에 데이터를 전달할 수 있습니다. 엔드포인트 설정, 인증, TLS(전송 계층 보안) 및 일괄 처리 옵션을 구성할 수 있습니다.

필수 조건

Azure IoT Operations의 인스턴스
Azure IoT 작업 클러스터에서 배포되고 액세스할 수 있는 OpenTelemetry 수집기

OpenTelemetry 엔드포인트 개요

OpenTelemetry 엔드포인트를 사용하면 OTLP(OpenTelemetry Protocol)를 사용하여 Azure IoT 작업 데이터 흐름에서 OpenTelemetry 수집기로 원격 분석 데이터를 내보낼 수 있습니다. 이를 통해 디바이스 및 시스템 원격 분석을 기존 가시성 인프라에 통합할 수 있습니다.

일반적인 시나리오

디바이스 진단: 온도, 압력 및 기타 센서 판독값을 메트릭으로 내보내어 디바이스 상태를 모니터링합니다.
팩터리 모니터링: 운영 가시성을 위해 Grafana 대시보드에 프로덕션 라인 원격 분석 전송
시스템 가시성: 중앙 집중식 모니터링을 위해 애플리케이션 로그 및 메트릭을 Azure Monitor에 전달
사용자 지정 메트릭: 개선된 필터링 및 분석을 위해 팩터리 ID 또는 위치와 같은 컨텍스트 특성을 메트릭에 추가

데이터 형식 요구 사항

OpenTelemetry 엔드포인트에는 metrics 배열, logs 배열 또는 둘 다를 사용하여 특정 JSON 스키마를 준수하는 데이터가 필요합니다. 이 스키마를 준수하지 않는 메시지는 메시지 손실을 방지하기 위해 삭제되고 승인됩니다.

JSON 페이로드는 다음 최상위 구조를 사용해야 합니다.

{
  "metrics": [ /* array of metric objects */ ],
  "logs": [ /* array of log objects */ ]
}

하나 이상의 metrics 또는 logs이(가) 있어야 합니다.

들어오는 모든 메시지는 필수 스키마에 대해 유효성이 검사됩니다. 유효성 검사에 실패한 메시지는 삭제되고, 브로커에 다시 승인되고, 문제 해결을 위해 기록됩니다. 일반적인 유효성 검사 실패에는 누락된 필수 필드, 잘못된 데이터 형식, 지원되지 않는 메트릭 형식 또는 로그 수준 및 잘못된 형식의 타임스탬프가 포함됩니다. MQTT 메시지에 만료 타임스탬프가 포함된 경우 만료된 메시지는 처리하기 전에 필터링됩니다.

메트릭 형식

metrics 배열의 각 메트릭 개체에는 다음 필드가 포함되어야 합니다.

필수 필드:

name (문자열): 메트릭 이름
type (문자열): 메트릭 형식(지원되는 메트릭 형식 참조)
value (숫자): 메트릭의 숫자 값

선택적 필드:

description (문자열): 메트릭에 대한 사람이 읽을 수 있는 설명
timestamp (숫자): 메트릭이 기록되었을 때 Unix Epoch 타임스탬프(나노초)
attributes (배열): 메트릭 레이블 지정 및 필터링을 위한 키-값 쌍

{
  "metrics": [
    {
      "name": "temperature",
      "description": "The temperature reading from sensor",
      "type": "f64_gauge",
      "value": 72.5,
      "timestamp": 1754851200000000000,
      "attributes": [
        {
          "key": "factoryId",
          "value": "factory1"
        },
        {
          "key": "location",
          "value": "warehouse"
        }
      ]
    }
  ]
}

attributes 배열의 각 특성에는 다음이 있어야 합니다.

key (문자열): 특성 이름
value (문자열): 특성 값(문자열이어야 함)

로그 형식

logs 배열의 각 로그 개체에는 다음 필드가 포함되어야 합니다.

필수 필드:

value (문자열): 로그 메시지 내용
level (문자열): 로그 수준(지원되는 로그 수준 참조)

선택적 필드:

timestamp (숫자): 로그가 기록되었을 때 Unix Epoch 타임스탬프(나노초)
attributes (배열): 로그 컨텍스트 및 필터링을 위한 키-값 쌍

{
  "logs": [
    {
      "value": "Device temperature sensor initialized",
      "level": "info",
      "timestamp": 1754851200000000000,
      "attributes": [
        {
          "key": "deviceId",
          "value": "sensor001"
        },
        {
          "key": "component",
          "value": "temperature-sensor"
        }
      ]
    }
  ]
}

attributes 배열의 각 특성에는 다음이 있어야 합니다.

key (문자열): 특성 이름
value (문자열): 특성 값(문자열이어야 함)

지원되는 메트릭 형식

지원되는 OpenTelemetry 메트릭 형식은 다음과 같습니다.

카운터: u64_counter, f64_counter - 단순한게 증가하는 값
위/아래 카운터: i64_up_down_counter, f64_up_down_counter - 증가 또는 감소할 수 있는 값
게이지: u64_gauge, i64_gauge, f64_gauge - 특정 시점 값
히스토그램: f64_histogram, u64_histogram - 값의 분포

지원되는 로그 수준

지원되는 로그 수준은 다음과 같습니다.

trace
debug
info
warn
error
fatal

OpenTelemetry 엔드포인트 만들기

작업 환경, Bicep 또는 Kubernetes를 사용하여 OpenTelemetry 데이터 흐름 엔드포인트를 만들 수 있습니다.

작업 환경
Bicep
Kubernetes (쿠버네티스)

작업 환경에서 OpenTelemetry 데이터 흐름을 만들려면 데이터 흐름 엔드포인트로 이동합니다.
데이터 흐름 엔드포인트 페이지에서 Open Telemetry 를 식별하고 + 새로 만들기를 선택합니다.
새 데이터 흐름 엔드포인트 만들기: 원격 분석 열기 창에서 기본 구성 탭을 선택하고 다음 정보를 제공합니다.
- 이름: 엔드포인트의 고유한 이름입니다.
- 호스트: OpenTelemetry 수집기 엔드포인트는 다음과 같은 형식입니다<host>:<port> 예: otel-collector.monitoring.svc.cluster.local:4317.
- 인증 방법: 다음 인증 방법 중 하나를 선택합니다.
  - Kubernetes 서비스 계정 토큰: Kubernetes 서비스 계정 토큰을 사용하여 OpenTelemetry 수집기를 사용하여 인증합니다. OpenTelemetry 수집기 구성에 대한 대상 그룹 값을 제공합니다. 자세한 내용은 SAT(서비스 계정 토큰) 를 참조하세요.
  - 익명: OpenTelemetry 수집기에서 인증이 필요하지 않은 경우에 사용합니다.
  - X509 인증서: 상호 TLS 인증에 클라이언트 인증서를 사용합니다. 클라이언트 인증서를 포함하는 Kubernetes 비밀의 이름을 제공합니다. 자세한 내용은 X.509 인증서 를 참조하세요.
고급 구성 탭을 선택하고 다음 정보를 제공합니다.
- 일괄 처리 대기 시간(초): 일괄 처리를 보내기 전에 대기하는 최대 시간입니다. 기본값은 5초입니다.
- 메시지 수: 일괄 처리의 최대 메시지 수입니다. 기본값은 100000 메시지입니다.
- TLS 모드: 다음 TLS 모드 중 하나를 선택합니다.
  - 사용: OpenTelemetry 수집기와의 보안 통신을 위해 TLS를 사용하도록 설정합니다. 신뢰할 수 있는 CA 인증서를 포함하는 Kubernetes ConfigMap의 이름을 제공합니다.
  - 사용 안 함: TLS를 사용하지 않도록 설정합니다.
- 신뢰할 수 있는 CA 인증서 구성 맵 이름: 신뢰할 수 있는 CA 인증서를 포함하는 Kubernetes ConfigMap의 이름입니다.
적용을 선택하여 OpenTelemetry 엔드포인트를 만듭니다.

다음 콘텐츠로 Bicep .bicep 파일을 만듭니다. 필요에 따라 설정을 업데이트하고 <AIO_INSTANCE_NAME>과(와) 같은 자리 표시자 값을 원하는 값으로 바꿉니다.

param aioInstanceName string = '<AIO_INSTANCE_NAME>'
param customLocationName string = '<CUSTOM_LOCATION_NAME>'
param endpointName string = '<ENDPOINT_NAME>'
param collectorHost string = '<COLLECTOR_HOST>'

resource aioInstance 'Microsoft.IoTOperations/instances@2024-11-01' existing = {
  name: aioInstanceName
}

resource customLocation 'Microsoft.ExtendedLocation/customLocations@2021-08-31-preview' existing = {
  name: customLocationName
}

resource openTelemetryEndpoint 'Microsoft.IoTOperations/instances/dataflowEndpoints@2024-11-01' = {
  parent: aioInstance
  name: endpointName
  extendedLocation: {
    name: customLocation.id
    type: 'CustomLocation'
  }
  properties: {
    endpointType: 'OpenTelemetry'
    openTelemetrySettings: {
      host: collectorHost
      authentication: {
        method: 'ServiceAccountToken'
        serviceAccountTokenSettings: {
          audience: '<OTEL_AUDIENCE>'
        }
      }
      tls: {
        mode: 'Enabled'
        trustedCaCertificateConfigMapRef: '<CA_CONFIGMAP_NAME>'
      }
      batching: {
        latencySeconds: 5
        maxMessages: 100
      }
    }
  }
}

다음 Azure CLI 명령을 실행하여 파일을 배포합니다.

az deployment group create --resource-group <RESOURCE_GROUP> --template-file <FILE>.bicep

다음 콘텐츠를 사용하여 Kubernetes 매니페스트 .yaml 파일을 만듭니다.

apiVersion: connectivity.iotoperations.azure.com/v1beta1
kind: DataflowEndpoint
metadata:
  name: <ENDPOINT_NAME>
  namespace: azure-iot-operations
spec:
  endpointType: OpenTelemetry
  openTelemetrySettings:
    host: <COLLECTOR_HOST>
    authentication:
      method: ServiceAccountToken
      serviceAccountTokenSettings:
        audience: <OTEL_AUDIENCE>
    tls:
      mode: Enabled
      trustedCaCertificateConfigMapRef: <CA_CONFIGMAP_NAME>
    batching:
      latencySeconds: 5
      maxMessages: 100

Kubernetes 클러스터에 매니페스트 파일을 적용합니다.

kubectl apply -f <FILE>.yaml

구성 옵션

이 섹션에서는 OpenTelemetry 데이터 흐름 엔드포인트에 대한 구성 옵션에 대해 설명합니다.

호스트

이 host 속성은 OpenTelemetry 수집기 엔드포인트 URL을 지정합니다. 프로토콜(http:// 또는 https://) 및 포트 번호를 포함합니다.

예제:

https://otel-collector.monitoring.svc.cluster.local:4317
http://localhost:4317
https://otel-collector:4317

인증

OpenTelemetry 엔드포인트는 수집기에서 안전하게 연결하는 몇 가지 인증 방법을 지원합니다.

SAT(서비스 계정 토큰)

SAT(서비스 계정 토큰) 인증은 Kubernetes 서비스 계정 토큰을 사용하여 OpenTelemetry 수집기에 인증합니다.

OpenTelemetry 수집기 구성에 대한 대상 그룹 값으로 <OTEL_AUDIENCE>을(를) 대체합니다. 이 값은 수집기의 예상 대상 그룹과 일치해야 합니다.

작업 환경
Bicep
Kubernetes (쿠버네티스)

새 데이터 흐름 엔드포인트 만들기: 원격 분석 열기 창의 기본 구성 탭에서 인증 방법으로 Kubernetes 서비스 계정 토큰을 선택합니다.
OpenTelemetry 수집기 구성에 대한 서비스 대상 그룹 값을 제공합니다.

중요합니다

새 OpenTelemetry 데이터 흐름 엔드포인트를 만들 때만 인증 방법을 선택할 수 있습니다. OpenTelemetry 데이터 흐름 엔드포인트를 만든 후에는 인증 방법을 변경할 수 없습니다. 기존 데이터 흐름의 인증 방법을 변경하려면 원래 데이터 흐름을 삭제하고 새 인증 방법으로 새 데이터 흐름을 만듭니다.

authentication: {
  method: 'ServiceAccountToken'
  serviceAccountTokenSettings: {
    audience: '<OTEL_AUDIENCE>'
  }
}

authentication:
  method: ServiceAccountToken
  serviceAccountTokenSettings:
    audience: <OTEL_AUDIENCE>

X.509 인증서

X.509 인증서 인증은 상호 TLS 인증에 클라이언트 인증서를 사용합니다.

작업 환경
Bicep
Kubernetes (쿠버네티스)

새 데이터 흐름 엔드포인트 만들기: 원격 분석 열기 창의 기본 구성 탭에서 인증 방법으로 X509 인증서를 선택합니다.
Azure Key Vault에서 다음 정보를 제공합니다.
- 동기화된 비밀 이름: 클라이언트 인증서를 포함하는 Kubernetes 비밀의 이름입니다.
- X509 클라이언트 인증서: 클라이언트 인증서입니다.
- X509 클라이언트 키: 클라이언트 인증서의 프라이빗 키입니다.
- X509 중간 인증서: 클라이언트 인증서 체인에 대한 중간 인증서입니다.

authentication: {
  method: 'X509Certificate'
  x509CertificateSettings: {
    secretRef: '<X509_SECRET_NAME>'
  }
}

authentication:
  method: X509Certificate
  x509CertificateSettings:
    secretRef: <X509_SECRET_NAME>

X.509 인증서 인증을 사용하기 전에 클라이언트 인증서를 사용하여 Kubernetes 비밀을 만듭니다.

kubectl create secret tls <X509_SECRET_NAME> \
  --cert=client.crt \
  --key=client.key \
  -n azure-iot-operations

익명 인증

익명 인증은 OpenTelemetry 수집기에 인증이 필요하지 않은 경우에 사용됩니다.

작업 환경
Bicep
Kubernetes (쿠버네티스)

새 데이터 흐름 엔드포인트 만들기: 원격 분석 열기 창의 기본 구성 탭에서 인증 방법으로 익명을 선택합니다. 추가 설정은 필요하지 않습니다.

authentication: {
  method: 'Anonymous'
  anonymousSettings: {}
}

authentication:
  method: Anonymous
  anonymousSettings: {}

TLS 구성

OpenTelemetry 수집기와의 보안 통신을 위해 TLS(전송 계층 보안) 설정을 구성합니다.

신뢰할 수 있는 CA를 사용하여 TLS 사용

작업 환경
Bicep
Kubernetes (쿠버네티스)

새 데이터 흐름 엔드포인트 만들기: 원격 분석 열기 창의 고급 구성 탭에서 TLS 모드로 [사용]을 선택합니다.
신뢰할 수 있는 CA 인증서 구성 맵 이름에서 신뢰할 수 있는 CA 인증서를 포함하는 Kubernetes ConfigMap의 이름을 제공합니다.

tls: {
  mode: 'Enabled'
  trustedCaCertificateConfigMapRef: '<CA_CONFIGMAP_NAME>'
}

tls:
  mode: Enabled
  trustedCaCertificateConfigMapRef: <CA_CONFIGMAP_NAME>

TLS 사용 안 함

작업 환경
Bicep
Kubernetes (쿠버네티스)

새 데이터 흐름 엔드포인트 만들기: 원격 분석 열기 창의 고급 구성 탭에서 TLS 모드로 사용 안 함을 선택합니다.

tls: {
  mode: 'Disabled'
}

tls:
  mode: Disabled

일괄 처리

수집기로 보내기 전에 여러 메시지를 그룹화하여 성능을 최적화하도록 일괄 처리 설정을 구성합니다.

작업 환경
Bicep
Kubernetes (쿠버네티스)

새 데이터 흐름 엔드포인트 만들기: 원격 분석 열기 창의 고급 구성 탭에서 다음 일괄 처리 설정을 제공합니다.

일괄 처리 대기 시간(초): 일괄 처리를 보내기 전에 대기하는 최대 시간입니다. 기본값은 5초입니다.
메시지 수: 일괄 처리의 최대 메시지 수입니다. 기본값은 100000 메시지입니다.

batching: {
  latencySeconds: 5
  maxMessages: 100
}

재산	설명	기본값
`latencySeconds`	일괄 처리를 보내기 전에 대기하는 최대 시간입니다.	60초
`maxMessages`	일괄 처리의 최대 메시지 수입니다.	100,000개의 메시지

batching:
  latencySeconds: 5
  maxMessages: 100

재산	설명	기본값
`latencySeconds`	일괄 처리를 보내기 전에 대기하는 최대 시간입니다.	60초
`maxMessages`	일괄 처리의 최대 메시지 수입니다.	100,000개의 메시지

오류 처리 및 문제 해결

메시지 유효성 검사

OpenTelemetry 엔드포인트는 필요한 스키마에 대해 들어오는 메시지의 유효성을 검사합니다. 데이터 흐름 파이프라인에서 메시지 손실을 방지하기 위해 잘못된 메시지가 삭제되고 승인됩니다.

일반적인 유효성 검사 오류:

필수 필드 누락(메트릭의 경우 name, type, value, 로그의 경우 value, level)
잘못된 메트릭 형식 또는 로그 수준
메트릭 value 필드의 숫자가 아닌 값
잘못된 형식의 타임스탬프 값

배달 보장

OpenTelemetry 엔드포인트는 수집기 자체에 배달 보장을 제공하지만 수집기에서 데이터를 전달할 수 있는 업스트림 서비스에는 제공하지 않습니다. 데이터가 수집기에 도달하면 Azure IoT 작업은 최종 대상에 도달하는지 여부를 확인할 수 없습니다.

피드백

이 페이지가 도움이 되었나요?

Last updated on 2025-10-04