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 계측 또는 SDK 계측을 선택하세요.
| 연동 방식 | 지원 언어 | 작동 방식 | 사용 사례 |
|---|---|---|---|
| Zero-code 계측 | Java, Python, PHP, Node.js, .NET, Go | Agent, 런타임 Hook, 확장, 시작 파라미터 또는 컴파일 타임 계측을 통해 지원되는 프레임워크 및 구성 요소에 대한 텔레메트리 데이터를 자동으로 생성합니다. | 비즈니스 코드를 최대한 수정하지 않고 일반적인 Web, HTTP, 데이터베이스 및 메시지 큐 호출을 빠르게 수집하려는 경우. |
| SDK 계측 | Go | 애플리케이션에서 OpenTelemetry SDK를 초기화하고 프레임워크 계측 라이브러리 또는 API를 사용하여 텔레메트리 데이터를 생성합니다. | Provider, Exporter, 샘플링, 리소스 속성 및 비즈니스 Span을 명시적으로 제어해야 하는 경우. |
Zero-code는 비즈니스 로직을 수정하지 않거나 최소한으로 수정한다는 의미이며, 구성 요소 설치, 전송 파라미터 구성 또는 애플리케이션 재시작이 필요하지 않다는 의미는 아닙니다. 자동 계측은 지원되는 프레임워크와 구성 요소에만 적용됩니다. 비즈니스 내부의 중요한 작업은 OpenTelemetry API를 통해 사용자 정의 Span, Metric 및 속성을 추가할 수 있습니다.
Zero-code 계측¶
| 언어 | 계측 방식 | 연동 문서 |
|---|---|---|
| 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 | otelc를 사용하여 컴파일 단계에서 OpenTelemetry SDK 초기화 및 구성 요소 계측 로직을 자동으로 주입. |
OpenTelemetry Go（otelc） |
| Go | LoongSuite를 통해 go build 컴파일 중 OpenTelemetry SDK 및 계측 로직 주입. |
OpenTelemetry Go（LoongSuite） |
SDK 계측¶
| 언어 | 계측 방식 | 연동 문서 |
|---|---|---|
| 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 프로토콜 및 전송 주소를 순서대로 확인하십시오.