OpenTelemetry Protocol (OTLP)은 OpenTelemetry 프로젝트를 위해 설계된 범용 텔레메트리 데이터 전송 프로토콜입니다. 각 OpenTelemetry 언어 SDK는 OTLP 내보내기 기능을 제공하고 OpenTelemetry 수집기에는 OTLP 수신기와 내보내기 기능이 있습니다. 또한 OpenTelemetry 프로젝트 외부의 다양한 도구도 OTLP 내보내기에 대한 지원을 추가했습니다.
뉴렐릭은 기본 OTLP 수집을 지원하며 OpenTelemetry 데이터를 뉴렐릭 플랫폼으로 전송하는 데 기본 방법으로 권장합니다. 이 페이지에서는 뉴렐릭의 OTLP 지원에 대한 설정, 요구 사항, 권장 사항을 포함한 내용을 다룹니다.
시작하기 전에
아직 등록하지 않았다면 무료 New Relic 계정 에 등록하십시오.
데이터를 보고하려는 뉴렐릭 계정에 대한 을 가져오세요. 이 라이선스 키는
api-key헤더를 구성할 때 사용됩니다.
구성: OTLP 엔드포인트, 포트 및 프로토콜
요구사항 수준: Required [필수]
OTLP 데이터를 뉴렐릭으로 보내도록 구성하려면 환경에 따라 아래 표의 관련 엔드포인트 및 포트를 사용하도록 OTLP 내보내기를 구성해야 합니다.
엔드포인트를 구성하는 메커니즘은 다양하지만 OpenTelemetry 언어 SDK는 일반적으로 OTEL_EXPORTER_OTLP_ENDPOINT=<INSERT_ENDPOINT> 환경 변수 설정을 지원합니다(자세한 내용은 OpenTelemetry 문서 참조).
또한 가능한 경우 프로토콜의 OTLP/HTTP 바이너리 protobuf 버전을 사용하도록 OTLP 내보내기를 구성해야 합니다. 뉴렐릭은 모든 버전의 OTLP를 지원하지만, OTLP/HTTP 바이너리 protobuf는 성능의 뚜렷한 감소 없이 gRPC보다 더 강력한 것으로 입증되었습니다.
엔드포인트를 구성하는 메커니즘은 다양하지만 OpenTelemetry 언어 SDK는 일반적으로 OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf 환경 변수 설정을 지원합니다(자세한 내용은 OpenTelemetry 문서 참조).
수집기를 사용하는 경우 otlphttpexporter 를 사용하는 것이 좋습니다.
환경 | gRPC | HTTP | 끝점 | 지원되는 포트 |
|---|---|---|---|---|
미국 OTLP | ✅ | ✅ |
|
|
EU OTLP | ✅ | ✅ |
|
|
미국 FedRAMP OTLP | ✅ | ✅ |
|
|
무한 추적 | ✅ | ✅ |
|
|
구성: TLS 암호화
요구사항 수준: Required [필수]
OTLP 데이터를 뉴렐릭으로 보내려면 TLS 1.2를 사용하도록 OTLP 내보내기 프로그램을 구성해야 합니다(자세한 내용은 TLS 암호화 참조). 일반적으로 SDK 및 수집기 내보내기 프로그램은 기본적으로 이 요구 사항을 충족합니다.
많은 OTLP 내보내기가 https 엔드포인트 구성표에서 TLS 설정을 추론하는 반면, 일부 gRPC 내보내기에서는 TLS를 명시적으로 활성화하도록 요구할 수 있습니다. gRPC TLS를 구성하는 메커니즘은 다양하지만 OpenTelemetry 언어 SDK는 일반적으로 OTEL_EXPORTER_OTLP_INSECURE=false 환경 변수 설정을 지원합니다(자세한 내용은 OpenTelemetry 문서 참조).
구성: API 키 설정
요구사항 수준: Required [필수]
OTLP 데이터를 뉴렐릭으로 보내려면 볼륨 키 에 설정된 값과 함께 api-key 이라는 헤더를 포함하도록 OTLP 내보내기 도구를 구성해야 합니다. 그렇지 않으면 인증 오류가 발생합니다.
헤더를 구성하는 메커니즘은 다양하지만 OpenTelemetry 언어 SDK는 일반적으로 OTEL_EXPORTER_OTLP_HEADERS=api-key=<INSERT_LICENSE_KEY> 환경 변수 설정을 지원합니다(자세한 내용은 OpenTelemetry 문서 참조).
구성: 속성 제한
요구사항 수준: Required [필수]
OTLP 데이터를 뉴렐릭으로 보내려면 뉴렐릭 속성 제한을 준수하도록 스프레드시트 소스를 구성해야 합니다. 그렇지 않으면 비동기 데이터 유효성 검사 중에 NrIntegrationError 이벤트가 발생할 수 있습니다.
속성 제한은 다음과 같습니다.
- 속성 이름의 최대 길이: 255자
- 속성 값의 최대 길이: 4095자
- 속성 배열 값의 최대 크기: 64개 항목
다른 제한은 지표 속성 제한 및 이벤트 속성 제한을 참조하세요.
속성 제한을 구성하는 메커니즘은 다양하지만 OpenTelemetry 언어 SDK는 일반적으로 OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT=4095 및 OTEL_ATTRIBUTE_COUNT_LIMIT=64 환경 변수 설정을 지원합니다(자세한 내용은 OpenTelemetry 문서 참조).
수집기를 사용할 때, 속성을 뉴렐릭 제한으로 자르도록 변환 프로세서를 구성할 수 있습니다.
메모:
- 리소스 속성은 속성 제한을 받지만, 이를 제한하는 표준 환경 변수는 없습니다. 리소스 속성이 허용된 한도를 초과하는 경우 수집기 변환 프로세서를 사용하여 잘라내거나 리소스 속성을 다른 값으로 덮어쓰는 것을 고려하세요.
- 속성 이름을 제한하는 표준 메커니즘은 없습니다. 그러나 리소스는 일반적으로 뉴렐릭 제한을 초과하는 속성 이름을 생성하지 않습니다. 이름 길이 제한이 발생하는 경우 수집기를 사용하여 속성을 제거하세요.
구성: 페이로드 일괄 처리, 시간 초과, 압축 및 속도 제한
요구사항 수준: Required [필수]
OTLP 데이터를 뉴렐릭으로 보내려면, 귀하의 페이로드가 최대 페이로드 크기인 1MB(10^6바이트)보다 작아야 합니다. 더 큰 페이로드는 오류 상태 코드와 함께 거부됩니다. 오류 상태 코드가 반환되기 전에 시간 초과로 인해 더 큰 페이로드를 내보내지 못할 수도 있습니다.
또한 뉴렐릭은 속도 제한을 부과합니다. 속도 제한을 초과하면 오류 상태 코드와 함께 요청이 거부됩니다.
페이로드 크기 제한 및 속도 제한을 방지하려면 적절한 간격으로 데이터를 내보내는 적절한 배치 크기를 사용하도록 OTLP 내보내기를 구성해야 합니다.
일괄 처리 구성 메커니즘은 다양합니다. OpenTelemetry SDK는 일반적으로 다음 환경 변수 설정을 지원합니다(자세한 내용은 OpenTelemetry 문서 참조).
OTEL_BSP_*범위에 대해OTEL_METRIC_EXPORT_*지표에 대한OTEL_BLRP_*로그용
수집기를 사용하는 경우 배치 프로세서가 배치 크기를 제어합니다.
또한 내보내기 제한 시간 설정에 주의를 기울여야 합니다. 일반적으로 페이로드가 더 크고 네트워크가 느릴 때(지연 시간이 길고 대역폭이 낮을 때) 내보내기 요청은 더 오래 걸립니다. 텔메트리 볼륨이 높거나 내보내기 간격이 길어서 로그가 큰 페이로드를 생성하는 경우 내보내기 오류를 방지하기 위해 기본 시간 초과 설정을 늘려야 할 수도 있습니다.
시간 초과를 구성하는 메커니즘은 다양하지만 OpenTelemetry 언어 SDK는 일반적으로 OTEL_EXPORTER_OTLP_TIMEOUT 환경 변수 설정을 지원합니다(자세한 내용은 OpenTelemetry 문서 참조).
또한 페이로드 크기를 줄이고 페이로드 크기 제한이 발생할 가능성을 제한하려면 압축을 활성화해야 합니다. 뉴렐릭은 gzip 및 zstd 압축을 지원합니다. zstd 압축은 성능이 더 높으며 내보내기 업체에서 지원하는 경우 권장됩니다. 벤치마크 정보에 대한 자세한 내용은 압축 비교를 참조하세요.
엔드포인트를 구성하는 메커니즘은 다양하지만 OpenTelemetry 언어 SDK는 일반적으로 OTEL_EXPORTER_OTLP_COMPRESSION=gzip 환경 변수 설정을 지원합니다(자세한 내용은 OpenTelemetry 문서 참조).
수집기를 사용하는 경우 기본 압축은 gzip 이지만 선택적으로 zstd 구성할 수 있습니다.
구성: 재시도
요구사항 수준: Recommended [권장]
OTLP 데이터를 뉴렐릭으로 보내려면 일시적인 오류가 발생할 때 다시 시도하도록 OTLP 내보내기를 구성해야 합니다. 인터넷은 신뢰할 수 없으며 재시도에 실패하면 데이터 손실 가능성이 높아집니다.
재시도를 구성하는 메커니즘은 다양합니다. 일부 OpenTelemetry SDK에는 언어별 환경 변수가 있을 수 있지만(예: Java는 OTEL_EXPERIMENTAL_EXPORTER_OTLP_RETRY_ENABLED=true 설정을 지원함 ) 일반적인 메커니즘은 없습니다. 프로그래밍 방식의 설정이 필요할 수 있습니다.
수집기를 사용하는 경우, otlphttpexporter 및 otlpexporter 기본적으로 재시도합니다. 자세한 내용은 exporterhelper 참조하세요.
구성: 지표 집계 시간성
요구사항 수준: Recommended [권장]
OTLP 지표 데이터를 뉴렐릭으로 보내려면 델타 집계 시간성을 선호하도록 OTLP 지표 내보내기 도구를 구성해야 합니다. 뉴렐릭은 누적 집계 시간성을 지원하지만 뉴렐릭 인덱스 쿼리는 일반적으로 델타 지수 시스템입니다. 기본 누적 설정을 사용하면 일반적으로 SDK에서 더 많은 메모리 사용량이 발생하고 데이터 수집량이 많아집니다.
엔드포인트를 구성하는 메커니즘은 다양하지만 OpenTelemetry 언어 SDK는 일반적으로 OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=delta 환경 변수 설정을 지원합니다(자세한 내용은 OpenTelemetry 문서 참조). 임시성을 수동으로 설정하는 경우, 로그다운 종류별로 다음과 같이 구성하세요.
- 카운터, 비동기 카운터, 히스토그램: 델타
- UpDownCounter, 비동기 UpDownCounter, 게이지, 비동기 게이지: 누적
누적 시간성은 계측된 에 사용되며 이는 뉴렐릭 게이지 유형 에 매핑되고 일반적으로 누적 값을 사용하여 분석됩니다.
구성: 지표 미스그램 집계
요구사항 수준: Recommended [권장]
OTLP 지표 데이터를 뉴렐릭으로 보내려면 히스토그램 축소된 측정값을 지수 히스토그램 으로 집계하도록 OTLP 지표 내보내기 도구를 구성해야 합니다. 기본 명시적 버킷 히스토그램과 함께 사용되는 정적 버킷과 달리 지수 히스토그램은 기록된 측정 범위를 반영하도록 버킷을 자동으로 조정합니다. 또한 그들은 고도로 압축된 표현을 사용하여 유선으로 전송합니다. 지수 히스토그램은 뉴렐릭 플랫폼에서 더욱 유용한 분포 데이터를 제공합니다.
엔드포인트를 구성하는 메커니즘은 다양하지만 OpenTelemetry 언어 SDK는 일반적으로 OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION=base2_exponential_bucket_histogram 환경 변수 설정을 지원합니다(자세한 내용은 OpenTelemetry 문서 참조).
OTLP 프로토콜 버전
뉴렐릭은 OTLP 릴리스 v0.18.0 을 사용합니다. 이후 버전은 지원되지만 새로운 기능은 아직 구현되지 않았습니다. 0.18.0에서 더 이상 사용할 수 없는 실험적 기능은 지원되지 않습니다.
OTLP 속성 유형
속성은 OpenTelemetry와 OTLP에서 반복되는 개념입니다. OpenTelemetry 에는 속성 값이 기본형(문자열, 부울, 이중 부동 소수점, 64비트 정수) 또는 기본형의 동종형임을 명시하는 표준 속성 정의가 있습니다. 그러나 OTLP 프로토콜 수준에서는 속성이 더 광범위한 AnyValue 정의를 사용하여 표현됩니다. 이로 인해 OTLP 클라이언트가 OpenTelemetry 표준 정의에 맞지 않는 속성을 보낼 수 있습니다.
뉴렐릭 OTLP 엔드포인트는 표준 속성 정의를 지원합니다. 맵의 맵, 객체형, 이기종 객체형과 같은 복합 유형은 지원되지 않습니다. OpenTelemetry SDK는 표준 속성 정의에 맞는 데이터만 생성해야 합니다.
중요
표준 속성 정의가 일반적으로 사용되는 반면, 로그 레코드 속성은 예외적이며 복잡한 값을 지원합니다(예: 로그 레코드 속성 유형은 map<string, any> 입니다). 그럼에도 불구하고 뉴렐릭은 현재 표준 속성 정의를 준수하는 로그 레코드 속성만 지원합니다.
OTLP 응답 페이로드
뉴렐릭 OTLP 엔드포인트 응답 페이로드와 관련하여 다음 세부 사항을 참고하세요:
- 뉴렐릭의 성공적인 응답에는 데이터 유형에 따라 Protobuf로 인코딩된 응답 대신 응답 본문이 없습니다.
- 뉴렐릭은 인증, 페이로드 크기, 속도 제한을 확인한 후 응답합니다. 페이로드 콘텐츠의 유효성 검사는 비동기식으로 수행됩니다. 따라서 뉴렐릭은 데이터 수집이 궁극적으로 실패하고
NrIntegrationError이벤트가 발생하더라도 성공 상태 코드를 반환할 수 있습니다. - 뉴렐릭의 실패 응답에는
Status.message또는Status.details포함되지 않습니다.