문제 해결¶
다음 순서로 확인하세요.
- 에이전트 버전을 확인하세요. Java JAR 파일 이름을 확인하거나
beacon --version,npm ls @beacon-observability/nodejs,beacon-dotnet version,vendor/bin/beacon-php --version을 실행하세요. - 애플리케이션을 시작하는 프로세스 환경에
OTEL_SERVICE_NAME, 수신 주소 및 프로토콜이 설정되어 있는지 확인하세요. - 애플리케이션 호스트에서 수신 포트까지 네트워크 연결을 확인하세요.
- 지원되는 프레임워크나 라이브러리를 통해 실제 요청을 발생시키세요. 애플리케이션 시작만으로는 Span이 생성되지 않을 수 있습니다.
- 아래 표에 따라 해당 언어의 진단을 활성화하고 문제를 재현한 뒤 로그를 저장하고 원래 설정으로 복원하세요.
언어별 디버깅 및 진단¶
디버깅 진입점은 언어마다 다릅니다. 구체적인 명령, 로그 위치 및 비활성화 방법은 해당 언어 페이지를 참조하세요.
| 언어 | 디버깅 또는 진단 방법 | 결과 |
|---|---|---|
| Java | OTEL_JAVAAGENT_DEBUG=true 또는 -Dotel.javaagent.debug=true |
Agent 디버그 로그 |
| Python | 애플리케이션 로그 설정에서 opentelemetry Logger 조정. 초기 진단에 OTEL_TRACES_EXPORTER=otlp,console 사용 가능 |
SDK 로그는 Python logging 설정에 따름. 콘솔 Span으로 텔레메트리 생성 여부 확인 |
| Node.js | OTEL_LOG_LEVEL=debug 설정 및 기존 사전 로드 구성 유지 |
터미널 진단 로그 |
| .NET | OTEL_LOG_LEVEL=debug와 OTEL_DOTNET_AUTO_LOG_DIRECTORY 설정 |
지정 디렉터리의 에이전트 로그. beacon-dotnet status로 설치 상태 확인 |
| PHP | OTEL_LOG_LEVEL=debug、OTEL_PHP_LOG_DESTINATION=stderr；vendor/bin/beacon-php doctor --json |
SDK 내부 로그 및 실행 환경 진단 보고서 |
이 로그는 에이전트 자체의 문제를 해결하기 위한 것으로, OTEL_LOGS_EXPORTER가 제어하는 텔레메트리 로그 내보내기와 별도로 설정합니다. 서비스 이름, OTLP 주소 및 로드 방식을 유지한 상태에서 진단을 일시적으로 활성화하고 문제를 한 번 재현한 후 원래 시작 설정으로 복원하세요. 로그를 공유하기 전에 인증 정보와 요청의 민감한 내용을 제거하세요.
Profile 데이터가 없는 경우¶
- Java: JDK 11 이상을 사용하는지 확인하고 Profile 디렉터리에 쓸 수 있는지 확인하세요.
- Python 및 Node.js:
OTEL_PROFILING_ENABLED=true가 설정되어 있고 업로드 주소가 올바르며 프로세스가 내보내기 주기보다 오래 실행되는지 확인하세요. - Profile 데이터를 OTLP Trace 주소로 보내지 마세요. Java는 JFR multipart, Python과 Node.js는 pprof multipart로 업로드합니다. DataKit에서는 Profile 수집기를 활성화해야 합니다.
Security 데이터가 없는 경우¶
- 애플리케이션 프로세스 환경에
BEACON_SECURITY_ENABLED=true와 OTLP Logs 내보내기가 설정되어 있는지 확인하세요. - Python은
BEACON_SECURITY_PYTHON_INCLUDE에 애플리케이션 모듈 접두사를 설정해야 합니다. Node.js는BEACON_SECURITY_NODE_INCLUDE에 애플리케이션 소스 루트를 설정하고 ESM--import사전 로드를 사용해야 합니다. - 런타임 SBOM은 보안 탐지 결과보다 먼저 생성될 수 있습니다. 모델링된 source와 sink를 거치는 실제 요청을 발생시키세요. 애플리케이션 시작만으로는 보안 탐지 결과가 생성되지 않습니다.
BEACON_SECURITY_LOCAL_OUTPUT_ENABLED=true를 설정하지 않으면 로컬 진단 파일은 비활성화 상태를 유지합니다. 로컬 파일이 없다는 것이 OTLP Logs 내보내기 실패를 의미하지는 않습니다.
에이전트를 활성화했을 때만 애플리케이션이 실패한다면 먼저 에이전트를 비활성화해 서비스를 복구하세요. 에이전트 디버그 로그, 런타임 버전, 민감한 정보를 제거한 명령줄 및 최소 재현 요청을 보관하세요.
DataKit 주소 또는 프로토콜이 일치하지 않는 경우¶
- OTLP/gRPC에는
http://<DataKit-IP>:4317을 사용하고 HTTP 경로를 추가하지 마세요. - OTLP/HTTP에는
http/protobuf를 사용하며 공통 주소는http://<DataKit-IP>:9529/otel입니다. 신호별 주소에는/otel/v1/traces,/otel/v1/metrics또는/otel/v1/logs전체 경로가 필요합니다. curl http://<DataKit-IP>:9529/v1/ping은 DataKit HTTP 서비스 접근 가능 여부만 확인하며 gRPC 포트나 개별 수집기 활성화 여부는 검증하지 않습니다.- 다른 호스트에서 접근할 때는 수신 주소와 네트워크 정책을 확인하세요. 컨테이너 안의
127.0.0.1은 현재 컨테이너를 가리킵니다.
설정 및 확인 절차는 공통 설정을 참조하세요.