OTLP source
출처: 문서
본문
OTLP 소스
otlp 소스는 OpenTelemetry Protocol (OTLP) 사양을 따르는 통합 OpenTelemetry 소스로, 단일 엔드포인트를 통해 로그, 메트릭, 트레이스를 수신할 수 있어요. 이 소스는 개별 otel_logs_source, otel_metrics_source, otel_trace_source 소스의 기능을 하나로 통합해서 모든 OpenTelemetry 텔레메트리 신호를 수집하는 간소화된 방식을 제공해요.
otlp 소스는 OTLP/gRPC와 OTLP/HTTP 프로토콜을 모두 지원해요. OTLP/HTTP의 경우 Protobuf 인코딩만 지원돼요. 덕분에 다양한 OpenTelemetry 컬렉터와 계측 라이브러리와 호환될 수 있어요.
{: .note}
설정
다음 옵션으로 otlp 소스를 설정할 수 있어요.
| 옵션 | 타입 | 설명 |
|---|---|---|
port |
Integer | otlp 소스가 수신 대기하는 포트예요. 기본값은 21893이에요. |
logs_path |
String | 로그에 대한 프레이밍되지 않은 HTTP 요청을 보내는 경로예요. /로 시작해야 하고 최소 길이는 1이어야 해요. 기본값은 /opentelemetry.proto.collector.logs.v1.LogsService/Export예요. |
metrics_path |
String | 메트릭에 대한 프레이밍되지 않은 HTTP 요청을 보내는 경로예요. /로 시작해야 하고 최소 길이는 1이어야 해요. 기본값은 /opentelemetry.proto.collector.metrics.v1.MetricsService/Export예요. |
traces_path |
String | 트레이스에 대한 프레이밍되지 않은 HTTP 요청을 보내는 경로예요. /로 시작해야 하고 최소 길이는 1이어야 해요. 기본값은 /opentelemetry.proto.collector.trace.v1.TraceService/Export예요. |
request_timeout |
Duration | 요청 타임아웃 시간이에요. 기본값은 10s예요. |
retry_info |
Object | 재시도 동작을 설정해요. 지수 백오프를 제어하는 min_delay(기본값 100ms)와 max_delay(기본값 2s) 파라미터를 지원해요. 재시도 정보를 참고하세요. |
health_check_service |
Boolean | grpc.health.v1.Health/Check 아래에서 gRPC 헬스 체크 서비스를 활성화해요. unframed_requests가 true이면 /health에서 HTTP 헬스 체크를 활성화해요. 기본값은 false예요. |
proto_reflection_service |
Boolean | Protobuf 서비스를 위한 리플렉션 서비스를 활성화해요(ProtoReflectionService와 gRPC 리플렉션 참고). 기본값은 false예요. |
unframed_requests |
Boolean | gRPC 와이어 프로토콜로 프레이밍되지 않은 요청을 활성화해요. 기본값은 false예요. |
thread_count |
Integer | 스케줄링된 스레드 풀에 유지할 스레드 수예요. 기본값은 200이에요. |
max_connection_count |
Integer | 허용되는 최대 열린 연결 수예요. 기본값은 500이에요. |
max_request_length |
String | 단일 gRPC 또는 HTTP 요청의 페이로드에 허용되는 최대 바이트 수예요. 기본값은 10mb예요. |
compression |
String | 클라이언트 요청 페이로드에 적용되는 압축 유형이에요. 유효한 값은 none(압축 없음) 또는 gzip(gzip 압축 해제 적용)이에요. 기본값은 none이에요. |
output_format |
String | 개별 출력 포맷 옵션이 설정되지 않은 경우 모든 신호(로그, 메트릭, 트레이스)에 대한 디코딩된 출력 포맷을 지정해요. 유효한 값은 otel(OpenTelemetry 포맷)과 opensearch(OpenSearch 포맷)예요. 기본값은 otel이에요. |
logs_output_format |
String | 로그 전용 디코딩 출력 포맷을 지정해요. 로그에 대해서는 output_format보다 우선 적용돼요. 유효한 값은 otel과 opensearch예요. 기본값은 otel이에요. |
metrics_output_format |
String | 메트릭 전용 디코딩 출력 포맷을 지정해요. 메트릭에 대해서는 output_format보다 우선 적용돼요. 유효한 값은 otel과 opensearch예요. 기본값은 otel이에요. |
traces_output_format |
String | 트레이스 전용 디코딩 출력 포맷을 지정해요. 트레이스에 대해서는 output_format보다 우선 적용돼요. 유효한 값은 otel과 opensearch예요. 기본값은 otel이에요. |
개별 출력 포맷(예: logs_output_format)이 설정되면 해당 신호 유형에 대해서는 일반 output_format보다 우선 적용돼요. 둘 다 설정되지 않으면 기본값은 otel이에요.
{: .note}
SSL/TLS 설정
다음 옵션으로 otlp 소스에서 SSL/TLS를 설정할 수 있어요.
| 옵션 | 타입 | 설명 |
|---|---|---|
ssl |
Boolean | SSL/TLS를 활성화해요. 기본값은 true예요. |
ssl_certificate_file |
String | SSL 인증서 체인 파일 경로 또는 Amazon Simple Storage Service(Amazon S3) 경로예요(예: s3://<bucketName>/<path>). ssl이 true로 설정되면 필수예요. |
ssl_key_file |
String | SSL 키 파일 경로 또는 Amazon S3 경로예요(예: s3://<bucketName>/<path>). ssl이 true로 설정되면 필수예요. |
use_acm_cert_for_ssl |
Boolean | AWS Certificate Manager(ACM)의 인증서와 프라이빗 키를 사용해 SSL/TLS를 활성화해요. 기본값은 false예요. |
acm_certificate_arn |
String | ACM 인증서의 Amazon Resource Name(ARN)이에요. ACM 인증서는 Amazon S3 또는 로컬 파일 시스템 인증서보다 우선 적용돼요. use_acm_cert_for_ssl이 true로 설정되면 필수예요. |
acm_private_key_password |
String | 프라이빗 키를 복호화하는 ACM 프라이빗 키 비밀번호예요. 제공하지 않으면 OpenSearch Data Prepper가 암호화 없이 프라이빗 키를 사용해요. |
aws_region |
String | ACM 또는 Amazon S3가 사용하는 AWS 리전이에요. use_acm_cert_for_ssl이 true로 설정되었거나 ssl_certificate_file과 ssl_key_file이 Amazon S3 경로인 경우 필수예요. |
인증 설정
기본적으로 otlp 소스는 인증 없이 실행돼요. 다음 옵션을 사용해 인증을 설정할 수 있어요.
인증을 명시적으로 비활성화하려면 다음 설정을 지정하세요:
source:
otlp:
authentication:
unauthenticated:
{% include copy.html %}
HTTP Basic 인증을 활성화하려면 다음 설정을 지정하세요:
source:
otlp:
authentication:
http_basic:
username: my-user
password: my_s3cr3t
{% include copy.html %}
이 플러그인은 gRPC 서버에 플러그형 인증을 사용해요. 커스텀 인증을 제공하려면 GrpcAuthenticationProvider를 구현하는 플러그인을 만드세요.
재시도 정보
retry_info 설정을 사용해 재시도 동작을 지정할 수 있어요. 백프레셔가 발생했을 때 다음 요청까지 얼마나 기다릴지 지정하는 거예요. 재시도 메커니즘은 설정 가능한 최대 지연 시간과 함께 지수 백오프를 적용해요:
source:
otlp:
retry_info:
min_delay: 100ms # defaults to 100ms
max_delay: 2s # defaults to 2s
{% include copy.html %}
사용법
다음 예제는 다양한 시나리오에서 otlp 소스를 설정하고 사용하는 방법을 보여줘요.
기본 설정
otlp 소스를 시작하려면 다음 최소 설정이 담긴 pipeline.yaml 파일을 만드세요:
pipeline:
source:
otlp:
ssl: false
sink:
- stdout:
{% include copy.html %}
텔레메트리 신호 라우팅
otlp 소스의 핵심 기능 중 하나는 필요에 맞게 서로 다른 텔레메트리 신호(로그, 메트릭, 트레이스)를 서로 다른 프로세서나 싱크로 라우팅할 수 있다는 점이에요. 라우팅은 getEventType() 함수를 사용하는 메타데이터를 기준으로 결정돼요:
version: "2"
otel-telemetry:
source:
otlp:
ssl: false
route:
- traces: 'getEventType() == "TRACE"'
- logs: 'getEventType() == "LOG"'
- metrics: 'getEventType() == "METRIC"'
sink:
- opensearch:
routes:
- logs
hosts: [ "https://opensearch:9200" ]
index: logs-%{yyyy.MM.dd}
username: admin
password: yourStrongPassword123!
insecure: true
- pipeline:
name: traces-raw
routes:
- traces
- pipeline:
name: otel-metrics
routes:
- metrics
traces-raw:
source:
pipeline:
name: otel-telemetry
processor:
- otel_trace_raw:
sink:
- opensearch:
hosts: [ "https://opensearch:9200" ]
index_type: trace-analytics-raw
username: admin
password: yourStrongPassword123!
insecure: true
otel-metrics:
source:
pipeline:
name: otel-telemetry
processor:
- otel_metrics:
calculate_histogram_buckets: true
calculate_exponential_histogram_buckets: true
exponential_histogram_max_allowed_scale: 10
flatten_attributes: false
sink:
- opensearch:
hosts: [ "https://opensearch:9200" ]
index: metrics-otel-%{yyyy.MM.dd}
username: admin
password: yourStrongPassword123!
insecure: true
{% include copy.html %}
OpenSearch 출력 포맷 사용하기
모든 텔레메트리 신호에 대해 OpenSearch 포맷의 데이터를 생성하려면 다음 설정을 지정하세요:
source:
otlp:
output_format: opensearch
{% include copy.html %}
신호 유형별로 서로 다른 출력 포맷을 사용하려면 다음 설정을 지정하세요:
source:
otlp:
logs_output_format: opensearch
metrics_output_format: otel
traces_output_format: opensearch
{% include copy.html %}
SSL/TLS를 사용한 설정
로컬 인증서로 SSL/TLS를 활성화하려면 다음 설정을 지정하세요:
source:
otlp:
ssl: true
ssl_certificate_file: "/path/to/certificate.crt"
ssl_key_file: "/path/to/private-key.key"
{% include copy.html %}
ACM을 사용하려면 다음 설정을 지정하세요:
source:
otlp:
ssl: true
use_acm_cert_for_ssl: true
acm_certificate_arn: "arn:aws:acm:us-east-1:123456789012:certificate/12345678-1234-1234-1234-123456789012"
aws_region: "us-east-1"
{% include copy.html %}
메트릭
otlp 소스에는 성능과 상태를 모니터링하기 위한 다음 메트릭이 포함되어 있어요.
카운터
다음 카운터들은 otlp 소스의 요청 활동과 오류를 추적해요.
| 메트릭 | 설명 |
|---|---|
requestTimeouts |
타임아웃된 요청의 총 개수예요. |
requestsReceived |
otlp 소스가 수신한 요청의 총 개수예요. |
successRequests |
otlp 소스가 성공적으로 처리한 요청의 총 개수예요. |
badRequests |
otlp 소스가 처리한, 형식이 잘못된 요청의 총 개수예요. |
requestsTooLarge |
최대 허용 크기를 초과한 요청의 총 개수예요. |
internalServerError |
otlp 소스에서 커스텀 예외 유형과 함께 처리된 요청의 총 개수예요. |
타이머
다음 타이머들은 otlp 소스의 요청 활동과 오류를 추적해요.
| 메트릭 | 설명 |
|---|---|
requestProcessDuration |
otlp 소스가 처리한 요청의 지연 시간이에요(초 단위). |
분포 요약
다음 분포 요약들은 otlp 소스의 요청 활동과 오류를 추적해요.
| 메트릭 | 설명 |
|---|---|
payloadSize |
수신되는 요청 페이로드 크기의 분포예요(바이트 단위). |
개별 OpenTelemetry 소스에서 마이그레이션
개별 otel_logs_source, otel_metrics_source, otel_trace_source 소스를 사용 중이라면 다음 단계를 따라 통합 otlp 소스로 마이그레이션할 수 있어요:
- 세 소스를 모두 단일
otlp소스로 교체해요. - 라우팅 설정을 사용해 서로 다른 신호 유형을 알맞은 파이프라인으로 보내요.
- 필요하면 포트 번호를 변경해요(
otlp소스는 기본적으로21893포트를 사용해요).
마이그레이션 예제
다음 예제는 개별 OpenTelemetry 로그, 메트릭, 트레이스 소스를 단일 otlp 소스로 통합하는 방법을 보여줘요.
로그, 메트릭, 트레이스가 각각 따로 설정된 환경을 가정해 보세요:
logs-pipeline:
source:
otel_logs_source:
port: 21892
sink:
- opensearch:
index: logs
metrics-pipeline:
source:
otel_metrics_source:
port: 21891
sink:
- opensearch:
index: metrics
traces-pipeline:
source:
otel_trace_source:
port: 21890
sink:
- opensearch:
index: traces
다음과 같이 로그, 메트릭, 트레이스를 단일 otlp 소스로 통합할 수 있어요:
otlp-pipeline:
source:
otlp:
port: 21893
route:
- logs: 'getEventType() == "LOG"'
- metrics: 'getEventType() == "METRIC"'
- traces: 'getEventType() == "TRACE"'
sink:
- opensearch:
routes:
- logs
index: logs
- opensearch:
routes:
- metrics
index: metrics
- opensearch:
routes:
- traces
index: traces
{% include copy.html %}