Elasticsearch OpenTelemetry 통합 문제 해결

$
sudo systemctl status otelcol-contrib

• 서비스가 비활성화된 경우 서비스를 시작하십시오. sudo systemctl start otelcol-contrib
• 서비스 이용에 실패한 경우, 설정 오류를 수정하고 다시 시작하십시오. sudo systemctl restart otelcol-contrib

$
sudo journalctl -u otelcol-contrib.service -f

로그 출력을 검토하고 근본 원인(예: 연결 문제, 인증 실패 또는 권한 문제)을 해결하십시오.

오류 예시: dial tcp [::1]:9200: connect: connection refused

• config.yaml

  의 endpoint 이 Elasticsearch 호스트 및 포트와 일치하는지 확인하십시오.
• 수집기 호스트에서 Elasticsearch가 실행 중이고 접근 가능한지 확인하십시오.

오류 예시: permanent error: 403 Forbidden

1. /etc/systemd/system/otelcol-contrib.service.d/environment.conf 에서 NEWRELIC_LICENSE_KEY 확인합니다.

2. systemd 다시 로드하고 수집기를 재시작하세요.

   bash

   카피

   $
   sudo systemctl daemon-reload
   $
   sudo systemctl restart otelcol-contrib

오류 샘플: permission denied 또는 cannot open file

1. Elasticsearch 그룹에 수집기 사용자를 추가합니다.
   bash

   카피

   $
   sudo usermod -a -G elasticsearch otelcol-contrib

2. 수집기를 재시작하세요: sudo systemctl restart otelcol-contrib

$
# Unsecured cluster
$
curl -I http://localhost:9200
$

$
# With authentication
$
curl -u username:password -k https://localhost:9200

클러스터가 정상인지, 자격 증명이 유효한지, 방화벽 또는 보안 설정에서 액세스가 허용되는지 확인하십시오.

• 모든 메트릭 파이프라인에 resourcedetection 프로세서가 포함되어 있는지 확인하십시오.

• resource/cluster_name_override

  프로세서를 통해 elasticsearch.cluster.name 설정되었는지 확인합니다.

• filelog

  수신 경로가 올바르고 절대 경로인지 확인하십시오.
• 로그 파이프라인에 filelog 수신자와 otlphttp 수출자가 모두 포함되어 있는지 확인하십시오.

$
# Verify your Elasticsearch pods have the required label
$
kubectl get pods -n <namespace> -l app=elasticsearch --show-labels

반환되는 파드가 없으면 Elasticsearch 파드에 필수 app=elasticsearch 레이블이 누락된 것입니다. receiver_creator는 일치하는 레이블이 없으면 파드를 검색할 수 없습니다.

• StatefulSet/배포의 경우 파드 템플릿에 레이블을 추가합니다:

  spec:
    template:
      metadata:
        labels:
          app: elasticsearch

  카피
• 기존 파드의 경우 라벨을 추가하고 다시 시작합니다:
  bash

  카피

  $
  kubectl label pods -l <your-selector> app=elasticsearch -n <namespace>
  $
  kubectl rollout restart statefulset/elasticsearch -n <namespace>

• 사용자 지정 레이블을 사용하는 경우, 레이블과 일치하도록 values.yaml의 수신자 규칙을 업데이트하십시오:

  rule: type == "pod" && labels["app"] == "your-custom-label"

  카피

$
kubectl get pods -n newrelic
$
kubectl describe pod <collector-pod-name> -n newrelic

• 파드 이벤트에서 오류를 확인하세요: kubectl describe pod

• 수집기 로그 검토:

  bash

  카피

  $
  kubectl logs -n newrelic -l app.kubernetes.io/name=opentelemetry-collector

• 시크릿이 존재하는지 확인합니다:

  bash

  카피

  $
  kubectl get secret newrelic-licenses -n newrelic

• 리소스 제한이 너무 낮지 않은지 확인하십시오.

$
# Check collector logs for discovery errors
$
kubectl logs -n newrelic -l app.kubernetes.io/name=opentelemetry-collector | grep "receiver_creator"

• RBAC 권한이 올바르게 설정되었는지 확인하세요:

  bash

  카피

  $
  kubectl get clusterrole | grep opentelemetry
  $
  kubectl describe clusterrole <role-name>

• 수집기에 파드, 노드 및 엔드포인트를 감시할 수 있는 권한이 있는지 확인하세요.

• 구성에서 k8s_observer 확장이 활성화되어 있는지 확인합니다.

$
# Check network policies
$
kubectl get networkpolicies -n <namespace>
$

$
# Test connectivity from collector to Elasticsearch
$
kubectl exec -n newrelic <collector-pod> -- curl http://<es-pod-ip>:9200

• 네트워크 정책이 newrelic 네임스페이스에서 Elasticsearch 네임스페이스로의 트래픽을 허용하는지 확인합니다.
• Elasticsearch 파드가 올바른 포트를 노출하는지 확인합니다(기본값: 9200)
• 방화벽 규칙이 파드 간 통신을 차단하지 않는지 확인하세요.

오류 예시: permanent error: 403 Forbidden

• 시크릿에 올바른 라이선스 키가 포함되어 있는지 확인하세요:

  bash

  카피

  $
  kubectl get secret newrelic-licenses -n newrelic -o jsonpath='{.data.NEWRELIC_LICENSE_KEY}' | base64 -d

• OTLP 엔드포인트가 해당 리전에 올바른지 확인하세요.

• 수집기 파드에 시크릿이 마운트되어 있는지 확인합니다:

  bash

  카피

  $
  kubectl describe pod <collector-pod> -n newrelic | grep -A5 "Environment"

• mode: daemonset

  를 사용 중인지 확인합니다(배포 모드에서는 노드 로그에 액세스할 수 없습니다)

• 볼륨 마운트가 올바르게 구성되었는지 확인하세요:

  bash

  카피

  $
  kubectl describe pod <collector-pod> -n newrelic | grep -A10 "Mounts"

• 파일 로그 수신기 경로가 Elasticsearch 파드 로그와 일치하는지 확인합니다:

  bash

  카피

  $
  kubectl exec -n newrelic <collector-pod> -- ls /var/log/pods/*/elasticsearch*/*.log

• 수집기에 호스트 로그 디렉터리에 대한 읽기 권한이 있는지 확인하십시오.

• values.yaml에 K8S_CLUSTER_NAME 환경 변수가 설정되어 있는지 확인합니다.

• resource/cluster

  프로세서가 메트릭 파이프라인에 있는지 확인합니다.

• 확인할 쿼리:

  FROM Metric SELECT * WHERE metricName LIKE 'elasticsearch.%' LIMIT 1

  카피

  k8s.cluster.name 속성이 존재하는지 확인합니다.

FROM Span SELECT count(*) WHERE es.cluster.name = '<elasticsearch-cluster-name>' SINCE 30 minutes ago

• 네이티브 OTLP 트레이스 내보내기에는 Elasticsearch 9.4 이상이 필요합니다. curl http://localhost:9200 을(를) 사용하여 버전을 확인하십시오.

• elasticsearch.yml

  에 세 가지 설정이 모두 있는지 확인하십시오: telemetry.tracing.enabled: true , telemetry.export.endpoint 및 telemetry.tracing.sample_rate .
• JVM 시스템 속성 -Dtelemetry.otel.traces.enabled=true 이(가) 설정되어 있는지( jvm.options 또는 ES_JAVA_OPTS 에서) 확인한 다음 Elasticsearch를 다시 시작하십시오.
• 기본 telemetry.tracing.sample_rate 은(는) 0.001 (0.1%)입니다. 스팬이 빠르게 나타나도록 유효성을 검사하는 동안 이 값을 높이십시오.

• 수집기에 0.0.0.0:4317 에서 gRPC 프로토콜이 활성화된 otlp 수신기가 있는지, 그리고 Elasticsearch 노드에서 엔드포인트에 연결할 수 있는지 확인하십시오.

• traces

  파이프라인이 존재하고 otlp 수신기와 otlphttp 익스포터가 포함되어 있는지 확인하십시오.
• 수집기 로그에서 OTLP 수신기 또는 내보내기 오류를 확인하십시오.

호출하는 애플리케이션의 속성으로 지정할 수 없는 Elasticsearch 스팬이 뉴렐릭에 도달하면 자체 루프가 나타납니다. 흔히 발생하는 두 가지 소스는 다음과 같습니다:

• 상위가 없는(루트) Elasticsearch 스팬 — Kubernetes 상태 프로브 또는 Elasticsearch 메트릭 수신기의 자체 스크랩 호출( _nodes/stats , _cluster/health 및 유사 항목)과 같이 상위 애플리케이션 스팬이 없는 스팬입니다. 애플리케이션 트레이스의 일부가 아니기 때문에 뉴렐릭에는 호출 서비스가 없으며 클러스터 자체에 관계를 그립니다.

• 노드 자체 주소 — Elasticsearch 서버 스팬은 http.request.headers.host (및 server.address )을 전달하며, 뉴렐릭은 이를 클러스터로 다시 해석합니다.

  해결

  두 프로세서를 모두 traces 파이프라인에 추가한 다음 수집기를 다시 시작하십시오. filter/drop_rootless_es 은(는) 상위가 없는 Elasticsearch 스팬을 삭제하고(애플리케이션 기반 스팬에는 항상 상위가 있으므로 유지됨), transform/strip_es_host 은(는) 주소 속성을 제거합니다:

  processors:
    filter/drop_rootless_es:
      error_mode: ignore
      traces:
        span:
          - 'instrumentation_scope.name == "elasticsearch" and IsRootSpan()'
    transform/strip_es_host:
      error_mode: ignore
      trace_statements:
        - context: span
          statements:
            - delete_key(attributes, "http.request.headers.host") where instrumentation_scope.name == "elasticsearch"
            - delete_key(attributes, "server.address") where instrumentation_scope.name == "elasticsearch"
  # traces pipeline: processors: [filter/drop_rootless_es, transform/strip_es_host, batch]

  카피

  수정된 스팬이 도착하고 이전 관계가 만료되면 기존 자체 루프가 저절로 지워집니다(최대 약 75분이 소요될 수 있습니다).

• 애플리케이션이 계측되고 Elasticsearch 호출 시 W3C traceparent 헤더를 전파하는지 확인하십시오. 대부분의 최신 Elasticsearch 클라이언트는 애플리케이션이 OpenTelemetry로 계측된 경우 이 작업을 자동으로 수행합니다.
• Elasticsearch 호출이 포함된 분산 트레이스를 열고 애플리케이션 스팬과 Elasticsearch 스팬이 동일한 트레이스를 공유하는지 확인하십시오.
• 관계가 형성될 때까지 몇 분 정도 기다려 주십시오. 뉴렐릭은 주기적으로 엔티티 관계를 재평가합니다.

• 트레이스 경로는 es.cluster.name (Elasticsearch가 스팬에 스탬프를 찍음)을 키로 사용하고 메트릭 경로는 elasticsearch.cluster.name 을 키로 사용합니다. elasticsearchreceiver 은(는) Elasticsearch가 반환하는 값에서 자동으로 elasticsearch.cluster.name 을(를) 보고하므로, 둘 다 동일한 cluster.name 에서 파생되고 하나의 엔티티로 확인됩니다 — 추가 수집기 설정이 필요하지 않습니다.
• 메트릭 클러스터 이름을 고정된 값으로 강제하지 마십시오. 수집기 구성에서 resource 프로세서(예: 이름을 하드코딩하는 resource/cluster_name_override )로 이를 설정하는 경우 해당 재정의를 제거하십시오 — 그렇지 않으면 메트릭과 트레이스가 서로 다른 두 엔티티로 확인되고 상관된 엔티티에 메트릭 데이터가 표시되지 않습니다.
• 단일하고 명확한 엔티티에 매핑되도록 뉴렐릭 계정 내에서 Elasticsearch cluster.name 이(가) 고유한지 확인하십시오.