일반적인 문제 해결

설치 프로세스 중에 오류를 진단하려면 values-newrelic.yaml 파일에 다음 설정을 추가하여 에이전트 제어에 대한 로그 수준을 높일 수 있습니다.

agentControlDeployment:
  chartValues:
    config:
      log:
        level: trace

• 기본 로그 수준: info.
• 기타 지원되는 로그 레벨: debug 및 trace.
• OTel 수집기 로그: OpenTelemetry 수집기에서 디버그 로그를 활성화하려면 verboseLog: true 추가합니다.

에이전트 제어 로그를 검사하려면 다음 명령을 실행하고 agent-control-*** 에이전트 제어 파드의 이름으로 바꾸세요.

$
# Find the Agent Control pod name
$
kubectl get pods -n newrelic-agent-control
$

$
# Inspect the logs, replacing `agent-control-***` with your pod's name
$
kubectl logs agent-control-*** -n newrelic-agent-control

Agent Control은 Agent Control 및 관리되는 에이전트의 상태를 확인하는 데 사용할 수 있는 로컬 상태 엔드포인트를 노출합니다. 이 엔드포인트는 기본적으로 포트 51200 에서 활성화됩니다. 클러스터 상태를 쿼리하려면 다음 단계를 따르세요.

로컬 포트를 메인 agent-control 파드로 전달:

$
kubectl port-forward <pod-name> 51200:51200

에이전트 상태 요청:

$
curl localhost:51200/status

Agent-control-부트스트랩 차트가 설치되면 모든 리소스와 차트를 설치하는 작업이 설치되고 BackoffLimitExceeded 오류로 인해 설치가 실패할 수 있습니다.

Error: UPGRADE FAILED: pre-upgrade hooks failed: job failed: BackoffLimitExceeded

설치 작업 로그를 살펴보면 설치 오류를 디버깅할 수 있습니다.

$
kubectl logs agent-control-bootstrap-install-job-**** -n newrelic-agent-control

Agent Control이 플릿위험에 안전하게 연결하려면 유효한 인증 자격 증명이 필요합니다. 처음에 이 자격 증명은 에이전트 Control 설치 UI 통해 자동 생성되며 값 파일의 systemIdentity.parentIdentity.clientId 및 systemIdentity.parentIdentity.clientSecret 필드로 표시됩니다. 보안상의 이유로 에이전트 Control 설치에 필요한 인증정보는 12시간 후 만료됩니다.

BackoffLimitExceeded 오류로 인해 설치가 실패하는 경우 자격 증명이 만료되었거나 유효하지 않은 경우가 많습니다.

에이전트 제어 시스템 ID를 설정하는 Kubernetes 작업의 서버를 확인하세요.

먼저, 해당 직무의 파드를 확인하세요.

$
kubectl describe job agent-control-generate-system-identity -n <your-namespace>

Events 섹션에서 다음과 같이 특정 파드에 대한 항목을 찾으세요.

Events:
      Type     Reason                Age   From            Message
      ----     ------                ----  ----            -------
      Normal   SuccessfulCreate      88s   job-controller  Created pod: agent-control-generate-system-identity-jr6cg
      Normal   SuccessfulCreate      73s   job-controller  Created pod: agent-control-generate-system-identity-wnx2v
      Normal   SuccessfulCreate      50s   job-controller  Created pod: agent-control-generate-system-identity-8zsqd
      Normal   SuccessfulCreate      7s    job-controller  Created pod: agent-control-generate-system-identity-btqh7
      Warning  BackoffLimitExceeded  1s    job-controller  Job has reached the specified backoff limit

실패한 패드의 로그 보기:

$
kubectl logs <pod-name> -n <your-namespace>

예시:

$
kubectl logs agent-control-generate-system-identity-btqh7 -n newrelic-agent-control

로그를 검토한 후 Helm을 사용하여 설치를 다시 시도하고 특정 오류 메시지가 있는지 살피고 로그를 확인하여 잠재적인 문제를 파악합니다. 알려진 문제와 이를 해석하는 방법은 다음과 같습니다.

• 잘못된 identityClientId: Error getting system identity auth token. The API endpoint returned 404: Failed to find Identity: <identityClientId-value>
• 잘못된 identityClientSecret: Error getting system identity auth token. The API endpoint returned 400: Bad client secret.
• 신원 만료됨: Error getting system identity auth token. The API endpoint returned 400: Expired client secret.
• 필수 권한이 없습니다: Failed to create a New Relic System Identity for Fleet Control communication authentication. Please verify that your User Key is valid and that your Account Organization has the necessary permissions to create a System Identity: Exception while fetching data (/create) : Not authorized to perform this action or the entity is not found.

OpenTelemetry 수집기 구현, 배포 파드의 로그에 아래와 같은 오류 메시지가 표시되면 잘못된 뉴렐릭 볼륨 키를 나타낼 수 있습니다. 이로 인해 수집기가 텔레메트리 데이터를 뉴렐릭으로 내보낼 수 없게 됩니다.

2024-06-13T13:46:05.898Z error exporterhelper/retry_sender.go:126 Exporting failed. The error is not retryable. Dropping data. {"kind": "exporter", "data_type": "metrics", "name": "otlphttp/newrelic", "error": "Permanent error: error exporting items, request to https://otlp.nr-dat ││ go.opentelemetry.io/collector/exporter/exporterhelper.(*retrySender).send

해결책

설정에서 유효한 뉴렐릭 클러스터 키를 사용하고 있는지 확인하세요.

관리되는 에이전트의 파드가 생성되지 않는 경우 HelmRelease에 문제가 있을 수 있습니다.

Helm 릴리스 상태를 확인하세요.

$
kubectl get helmrelease open-telemetry -n newrelic

성공적이고 건강한 릴리스에는 READY: True 및 STATUS: InstallSucceeded 표시되어야 합니다.

릴리스가 실패하면 STATUS 및 READY 필드에 문제가 표시됩니다. 오류 유형에 따라서는 근본적인 문제가 상태 필드에 완전히 반영되지 않을 수도 있습니다. 더 자세한 내용을 보려면 kubectl 사용하여 HelmRelease 리소스를 설명하세요.

$
kubectl describe helmrelease open-telemetry -n newrelic

Agent-control-부트스트랩 삭제 시 생성된 모든 리소스와 차트를 삭제하는 작업이 등장합니다.

제거 과정에서 다음과 같은 오류가 발생하는 경우: * job agent-control-bootstrap-uninstall-job failed: BackoffLimitExceeded

작업 로그를 확인하여 오류를 디버깅할 수 있습니다.

$
kubectl logs agent-control-bootstrap-uninstall-job-*** -n newrelic-agent-control

helm delete 명령이 실행 중에 취소되면 작업 제거 프로그램은 계속 작동하여 차트와 리소스를 삭제하지만, 'regi-control-buttstrlap' helm secret은 여전히 남아 있을 수 있습니다. 이 경우 차트를 업그레이드하거나 설치할 수 없으며 다음과 같은 오류가 발생합니다.

Error: UPGRADE FAILED: "agent-control-bootstrap" has no deployed releases

제거 작업을 다시 실행해도 작동하지 않으며, 제거 작업 로그에 다음과 같은 오류가 표시됩니다.

Error: uninstall: Release not loaded: agent-control-cd: release: not found

해결책

릴리스에서 모든 Helm 시크릿을 삭제합니다(릴리스 이름이 변경된 경우 '릴리스 이름'을 '컨트롤-부트스트랩'으로 변경하세요).

$
kubectl delete secrets -l "name=agent-control-bootstrap"

그런 다음 설치를 다시 진행할 수 있습니다.

뉴렐릭 진단 도구 NRDiag 는 디버깅을 위해 클러스터의 에이전트 제어와 관련된 리소스 및 로그를 수집하는 유틸리티입니다. 모든 데이터를 수집하려면 다음 단계를 따르세요.

1. 호스트에서 시작 가이드를 사용하여 NRDiag 도구를 설치합니다.

2. K8s 에이전트 제어 제품군을 실행합니다.

   팁

   kubectl 및 helm 설치되어 있는지 확인하세요.

   • kubeconfig 컨텍스트에 설정된 네임스페이스에서 명령을 실행합니다.
   bash

   카피

   $
   ./nrdiag -suites K8s-agent-control

   • --k8s-namespace 플래그를 사용하여 에이전트 제어에 대해 다른 네임스페이스를 지정합니다.
   bash

   카피

   $
   ./nrdiag -suites K8s-agent-control --k8s-namespace=newrelic

   • ac-agents-namespace 플래그를 사용하여 하위 에이전트에 대해 다른 네임스페이스를 지정합니다.
   bash

   카피

   $
   ./nrdiag -suites K8s-agent-control --k8s-namespace=newrelic-agent-control --ac-agents-namespace=newrelic

3. 예상되는 출력 보고서는 다음과 같습니다.

   bash

   카피

   Check Results
   -------------------------------------------------
   Info     K8s/Flux/Charts [Successfully collected Flux Helm Charts]
   Info     K8s/Resources/Config [Successfully collected K8s configMaps ]
   Info     K8s/AgentControl/agent-control-status-server [Successfully collected K8s agent-control status se...]
   Info     K8s/Resources/Daemonset [Successfully collected K8s newrelic-infrastructure...]
   Info     K8s/Resources/Pods [Successfully collected K8s newrelic-infrastructure...]
   Info     K8s/Flux/Repositories [Successfully collected Flux Helm Repositories]
   Info     K8s/AgentControl/helm-controller-logs [Successfully collected K8s agent-control helm-cont...]
   Info     K8s/Env/Version [kubectl version output successfully collected]
   Info     K8s/Resources/Deploy [Successfully collected K8s newrelic-infrastructure...]
   Info     K8s/Helm/Releases [Successfully collected the list of helm releases]
   Info     K8s/AgentControl/agent-control-logs [Successfully collected K8s agent-control agent-con...]
   Info     K8s/Flux/Releases [Successfully collected Flux Helm Releases]
   Info     K8s/AgentControl/source-controller-logs [Successfully collected K8s agent-control source-co...]
   See nrdiag-output.json for full results.

4. 에이전트 제어와 관련된 모든 로그 및 리소스는 현재 디렉터리의 nrdiag_output.zip 파일에 저장됩니다. 압축 파일의 내용을 분석하거나 추가 지원을 위해 뉴럴릭 지원팀 에 지원 테이블을 열어 문의할 수 있습니다.

오류 메시지 Installing agent-control (Unsupported) 를 받으면 시스템 요구사항을 확인하고 지원되는 OS 버전을 실행하고 있는지 확인하세요.

Installing agent-control (Failed) 표시되면 다음 단계를 따르세요.

• 설치 스크립트와 함께 제공되는 로그를 확인하십시오.

  • Error creating an identity 표시되면 사용자 키가 모든 제품 관리자 역할을 가진 플랫폼 사용자에게 속하는지 확인하십시오.

• newrelic-agent-control 서비스의 상태를 확인하세요:

  bash

  카피

  $
  sudo systemctl status newrelic-agent-control

  서비스가 failed 또는 stopped 상태로 표시되면 에이전트가 설치되었지만 정상적인 작동을 방해하는 문제가 있음을 의미합니다. journalctl (또는 이와 유사한 Linux 도구)를 사용하여 에이전트 서비스 로그를 확인하십시오.

  bash

  카피

  $
  journalctl -u newrelic-agent-control

  사용 가능한 인사이트가 없는 경우, 서비스가 시작되지 않는 이유를 설명하는 자세한 로그에 액세스하기 위해 디버그 모드에서 도구를 실행하는 방법을 확인하십시오.

• 서비스가 설치되지 않은 경우 안내 설치 의 CLI 설치 명령 끝에 --debug 추가하고 다시 실행해 보세요. 이 기능을 사용하면 설치 스크립트에 대한 자세한 로깅이 활성화되어 오류를 설명하는 추가적인 컨텍스트를 제공할 수 있습니다.

• 선택적으로 문제 해결, 설치 해결을 돕기 위해 로그를 뉴렐릭으로 보내라는 메시지가 표시되면 yes 에 응답하세요. 제출이 완료되면 다음 NRQL 쿼리를 사용하여 로그에 액세스할 수 있습니다.

  SELECT * FROM Log WHERE hostname = `your-host-name`

  카피

로그에 액세스하려면 먼저 다음 단계를 따라 에이전트 로깅을 활성화해야 합니다.

1. 파일 로깅을 활성화하려면 에이전트 제어 구성 파일에서 log 설정을 사용하십시오.

   # Fleet Control connection settings
   #fleet_control:
   
   # managed agents settings
   #agents:
   
   # agent logging settings
   log:
     level: debug
     file:
       enabled: true
       # Add a custom path if needed, default directory: /var/log/newrelic-agent-control/agent-control/
       # Logs rotate daily, so the file name is prefixed with the current date, e.g. 2026-09-18.newrelic-agent-control.log
       # path: "/path/to/agent-control.log"
     # Optional formatting settings
     format:
       # Include the target module (disabled by default for better readability)
       target: true
       # Custom timestamp format "%Y-%m-%dT%H:%M:%S"
       timestamp: "%Y"

   카피

   로그 레벨의 가능한 값은 다음과 같습니다.

• trace

• debug

• info (기본)

• warning

• error

  레벨이 debug 또는 trace 인 경우 기본 인프라 에이전트 및/또는 OpenTelemetry 수집기의 로그가 포함됩니다.

2. 에이전트 제어를 다시 시작하십시오:

   bash

   카피

   $
   sudo systemctl restart newrelic-agent-control

3. file 로그가 활성화된 경우, path 설정의 디렉터리에서 가장 최근 로그 파일을 확인하십시오(파일에는 날짜가 지정되어 있습니다. 예: 2026-09-18.newrelic-agent-control.log). 또는 journalctl -u newrelic-agent-control 등 선호하는 로그 문제 진단, 해결 도구를 사용하십시오.

건강 상태 세부 정보를 확인하려면 먼저 다음 단계를 따라 로컬 서버를 활성화해야 합니다.

1. 에이전트 제어 구성 파일 에 다음 설정을 추가하십시오.

   server:
       enabled: true
       # default values (change if needed)
       #host: "127.0.0.1"
       #port: 51200

   카피

2. 에이전트 제어를 다시 시작하십시오:

   bash

   카피

   $
   sudo systemctl restart newrelic-agent-control

3. 다음 명령을 사용하여 EndPoint 상태를 조회합니다.

   bash

   카피

   $
   curl 127.0.0.1:51200/status

   서버는 상태 정보를 json 형식으로 반환합니다. 예:

   {
     "agent_control": {
       "healthy": true
     },
     "fleet": {
       "enabled": true,
       "endpoint": "https://opamp.service.newrelic.com/v1/opamp",
       "reachable": true
     },
     "agents": {
       "nr-otel-collector": {
         "agent_id": "nr-otel-collector",
         "agent_type": "newrelic/com.newrelic.opentelemetry.collector:0.1.0",
         "agent_start_time_unix_nano": 1730000000000000000,
         "health_info": {
           "healthy": true,
           "start_time_unix_nano": 1730000000000000000,
           "status_time_unix_nano": 1730000010000000000
         }
       },
       "nr-infra-agent": {
         "agent_id": "nr-infra-agent",
         "agent_type": "newrelic/com.newrelic.infrastructure:0.1.0",
         "agent_start_time_unix_nano": 1730000000000000000,
         "health_info": {
           "healthy": false,
           "last_error": "process exited with code: exit status: 1",
           "start_time_unix_nano": 1730000000000000000,
           "status_time_unix_nano": 1730000010000000000
         }
       }
     }
   }

   카피

에이전트 컨트롤은 플릿위험으로부터 원격 설정을 수신하고 적용하기 전에 특정 검증을 수행합니다. 또한 구성은 유효한 형식(예: 유효한 .yaml 구조)을 가질 수 있지만 특정 설정에 대해 예상치 못한 값(예: integer 가 예상되는 경우 string)을 포함할 수 있습니다. 다음 표는 지원되는 다양한 에이전트에서 발생하는 일반적인 오류를 보여줍니다.