OpenTelemetry¶
OpenTelemetry는 Trace, Metric, Log 등 텔레메트리 데이터를 생성, 수집 및 전송하기 위한 개방형 표준입니다. OpenTelemetry를 사용하면 통합 데이터 모델과 OTLP 프로토콜을 통해 다양한 언어, 프레임워크 및 런타임 환경의 애플리케이션을 관측할 수 있습니다.
OpenTelemetry 생태계 지원¶
Guance는 OpenTelemetry 공식 Vendors 목록에 등재되었습니다. 공식 표기에 따르면 Guance는 상용 관측 가능성 벤더이며 Native OTLP를 지원하여 OpenTelemetry 텔레메트리 데이터를 기본적으로 수신할 수 있습니다. 사용자는 Guance를 통해 OpenTelemetry가 생성한 Trace, Metric 및 Log 데이터를 통합적으로 조회 및 분석하고, 인프라스트럭처, 애플리케이션 성능 및 사용자 액세스 데이터와 함께 연관 분석할 수 있습니다.
이 문서는 애플리케이션의 OpenTelemetry 데이터를 DataKit으로 전송한 후 DataKit이 Guance로 전송하는 방법을 설명합니다:
연동 방식 선택¶
언어 생태계 및 애플리케이션 수정 요구사항에 따라 Zero-code Instrumentation 또는 SDK Instrumentation을 선택하세요:
| 연동 방식 | 지원 언어 | 작동 방식 | 사용 사례 |
|---|---|---|---|
| Zero-code Instrumentation | Java, Python, PHP, Node.js, .NET, Go | Agent, 런타임 Hook, 확장, 시작 매개변수 또는 컴파일 타임 계측을 통해 지원되는 프레임워크 및 컴포넌트에 대한 텔레메트리 데이터를 자동으로 생성합니다. | 비즈니스 코드 수정을 최소화하고 일반적인 Web, HTTP, 데이터베이스 및 메시지 큐 호출을 빠르게 수집하려는 경우. |
| SDK Instrumentation | Go | 애플리케이션에서 OpenTelemetry SDK를 초기화하고 프레임워크 계측 라이브러리 또는 API를 사용하여 텔레메트리 데이터를 생성합니다. | Provider, Exporter, 샘플링, 리소스 속성 및 비즈니스 Span을 명시적으로 제어해야 하는 경우. |
Zero-code는 비즈니스 로직을 수정할 필요가 없거나 최소한만 수정한다는 의미이며, 구성 요소 설치, 전송 매개변수 구성 또는 애플리케이션 재시작이 필요 없음을 의미하지는 않습니다. 자동 계측은 지원되는 프레임워크 및 컴포넌트만을 대상으로 합니다. 비즈니스 내부의 중요한 작업은 OpenTelemetry API를 통해 사용자 정의 Span, Metric 및 속성을 추가로 보완할 수 있습니다.
Zero-code Instrumentation¶
| 언어 | 계측 방식 | 연동 문서 |
|---|---|---|
| Java | JVM -javaagent를 통해 OpenTelemetry Java Agent를 로드합니다. |
OpenTelemetry Java; Java 확장 |
| Python | opentelemetry-instrument를 통해 애플리케이션을 시작하고 해당 계측 패키지를 로드합니다. |
OpenTelemetry Python |
| PHP | OpenTelemetry PHP 확장을 통해 런타임 Hook을 제공하고 Composer 계측 패키지가 프레임워크 호출을 수집합니다. | OpenTelemetry PHP |
| Node.js | NODE_OPTIONS를 통해 OpenTelemetry 자동 계측 모듈을 사전 로드합니다. |
OpenTelemetry Node.js |
| .NET | CLR Profiler 및 Startup Hook을 통해 OpenTelemetry .NET Automatic Instrumentation을 로드합니다. | OpenTelemetry .NET |
| Go | LoongSuite를 통해 go build 컴파일 중에 OpenTelemetry SDK 및 계측 로직을 주입합니다. |
OpenTelemetry Go (LoongSuite) |
SDK Instrumentation¶
| 언어 | 계측 방식 | 연동 문서 |
|---|---|---|
| Go | OpenTelemetry Go SDK, OTLP Exporter 및 컨텍스트 전파기를 초기화하고 사용 중인 프레임워크 또는 컴포넌트에 대한 계측 라이브러리를 설치합니다. | OpenTelemetry Go SDK |
연동 프로세스¶
언어별 설치 명령어와 시작 매개변수는 다르지만, 전체 연동 프로세스는 동일합니다:
- DataKit OpenTelemetry 수집기 활성화: OTLP/HTTP 또는 OTLP/gRPC 수신 엔드포인트를 구성하고 DataKit을 재시작한 후 네트워크 연결을 확인합니다.
- 애플리케이션에 OpenTelemetry 계측 활성화: 언어에 따라 Agent, 확장, 자동 계측 모듈 또는 SDK를 설치합니다.
- 데이터 전송 매개변수 구성: 서비스 이름, 리소스 속성, OTLP 프로토콜, DataKit 주소, 샘플링 및 신호 활성화/비활성화를 설정합니다.
- 애플리케이션 재시작 및 액세스: 실제 요청을 생성하여 Trace 및 Metric 데이터를 트리거합니다.
- 데이터 확인: Guance에서 서비스, 트레이스 및 메트릭을 확인하고 애플리케이션 및 DataKit 로그를 통해 전송 오류를 트러블슈팅합니다.
DataKit OTLP 수신 주소¶
이 문서의 호스트 연동 예제에서는 다음 주소를 사용합니다. <DataKit-IP>는 애플리케이션이 액세스할 수 있는 DataKit 주소로 바꿔야 합니다:
| 프로토콜 | 신호 | 수신 주소 |
|---|---|---|
| OTLP/HTTP + Protobuf | Trace | http://<DataKit-IP>:9529/otel/v1/traces |
| OTLP/HTTP + Protobuf | Metric | http://<DataKit-IP>:9529/otel/v1/metrics |
| OTLP/HTTP + Protobuf | Log | http://<DataKit-IP>:9529/otel/v1/logs |
| OTLP/gRPC | Trace, Metric, Log | http://<DataKit-IP>:4317 |
일반 OTLP/HTTP 기본 주소를 사용하는 경우 다음과 같이 구성할 수 있습니다:
표준 OTLP 환경 변수를 지원하는 Exporter는 신호에 따라 자동으로 /v1/traces, /v1/metrics 또는 /v1/logs를 추가합니다. OTEL_EXPORTER_OTLP_TRACES_ENDPOINT와 같은 신호 전용 주소를 사용하는 경우 /otel/v1/traces를 포함한 전체 주소를 입력해야 합니다.
OTLP/gRPC 주소에는 /v1/traces와 같은 HTTP 경로를 추가할 수 없습니다. 애플리케이션과 DataKit이 동일한 호스트에 있지 않은 경우 DataKit 수신 주소, 방화벽 또는 기타 네트워크 액세스 제어를 조정해야 합니다. OTLP 수신 포트를 공용 네트워크에 직접 노출하지 마십시오.
전체 DataKit 매개변수 설명은 OpenTelemetry 수집기를 참조하세요.
공통 매개변수 권장 사항¶
언어에 관계없이 다음 리소스 속성 및 전파 매개변수를 통일하여 계획하는 것이 좋습니다:
| 매개변수 또는 속성 | 역할 | 권장 사항 |
|---|---|---|
service.name |
서비스를 식별합니다. APM 서비스 소속의 핵심 필드입니다. | 안정적이고 고유한 서비스 이름을 사용하고 Pod, 프로세스 ID 등 동적 값을 사용하지 마십시오. |
deployment.environment.name |
배포 환경을 식별합니다. | dev, test, staging, prod 등 약속된 값을 통일하여 사용하십시오. |
service.version |
애플리케이션 버전을 식별합니다. | 릴리스 버전, 빌드 버전 또는 Commit ID를 사용하여 버전 간 성능을 비교할 수 있도록 하십시오. |
OTEL_RESOURCE_ATTRIBUTES |
리소스 속성을 일괄 설정합니다. | 낮은 카디널리티를 가지며 민감한 정보를 포함하지 않는 속성만 배치하십시오. |
OTEL_PROPAGATORS |
서비스 간 컨텍스트 전파 형식을 제어합니다. | 기본적으로 tracecontext,baggage를 우선 사용하고, 호출 체인의 서비스 간 호환성을 유지하십시오. |
| 샘플링 전략 | 수집량과 오버헤드를 제어합니다. | 연동 검증 단계에서는 전체 샘플링이 가능하며, 프로덕션 환경에서는 트래픽, 스토리지 및 트러블슈팅 요구사항에 따라 조정하십시오. |
사용자 정의 리소스 속성을 Guance에서 태그로 유지하려면 DataKit customer_tags 허용 목록에 추가해야 합니다. 속성 이름의 .는 _로 변환됩니다. 예: team.name은 team_name으로 변환됩니다.
데이터 확인¶
연동 완료 후 애플리케이션 인터페이스에 액세스하여 요청을 생성한 후 다음을 확인하십시오:
curl http://<DataKit-IP>:9529/v1/ping을 실행하여 애플리케이션이 DataKit에 액세스할 수 있는지 확인합니다.- 애플리케이션 시작 로그를 확인하여 Agent, 확장 또는 SDK가 로드되었고 OTLP Exporter 오류가 없는지 확인합니다.
- Guance의 애플리케이션 성능 모니터링(APM)에서
service.name으로 서비스와 트레이스를 조회합니다. - Metric은 일반적으로 주기적으로 내보내지므로 최소 한 번의 내보내기 주기를 기다린 후 조회하십시오.
- 데이터를 찾을 수 없는 경우 DataKit 수집기 구성, 애플리케이션에서 DataKit까지의 네트워크, OTLP 프로토콜 및 전송 주소를 순서대로 확인하십시오.