Solucionar problemas comuns

Importante

O Agent Control e o New Relic Control agora estão disponíveis para o público geral para Kubernetes! O suporte para hosts Linux e hosts Windows também está no programa de public preview, em conformidade com nossas políticas de pré-lançamento.

Este documento aborda as etapas para solucionar problemas comuns ao instalar ou operar o Agent Control. É organizado por ambiente.

Solução de problemas do Kubernetes

Para diagnosticar erros durante o processo de instalação, você pode aumentar o nível de log do Agent Control adicionando a seguinte configuração no seu arquivo values-newrelic.yaml :

agentControlDeployment:
  chartValues:
    config:
      log:
        level: trace

Nível de log padrão: info.
Outros níveis de log suportados: debug e trace.
Logs do coletor OTel: para habilitar logs de depuração no coletor OpenTelemetry, adicione verboseLog: true.

Para inspecionar os logs do Agent Control, execute o seguinte comando, substituindo agent-control-*** pelo nome do seu pod do Agent Control:

bash

$# 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

O Agent Control expõe um endpoint de status local que você pode usar para verificar a integridade do Agent Control e seu agente gerenciado. Este endpoint é habilitado por padrão na porta 51200. Siga estes passos para consultar o status cluster :

Encaminhe uma porta local para o pod principal agent-control :

bash

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

Solicitar o status do agente:

bash

$curl localhost:51200/status

Quando o chart agent-control-bootstrap é instalado, um job é lançado para instalar todos os recursos e charts, e a instalação pode falhar com um erro BackoffLimitExceeded:

bash

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

Você pode depurar os erros de instalação verificando os logs do installation-job:

bash

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

O agente Control requer uma credencial de autenticação válida para se conectar com segurança ao Controle de Agentes. Inicialmente, essa credencial é gerada automaticamente através da interface de instalação do agente Control e é representada pelos campos identityClientId e identityClientSecret no arquivo de valores. Por motivos de segurança, a credencial necessária para instalar o Agente Control expira após 12 horas.

Se a instalação falhar com um erro BackoffLimitExceeded, isso geralmente indica uma credencial expirada ou inválida.

Verifique os logs do trabalho Kubernetes responsável por configurar a identidade do sistema de Agent Control.

Primeiro, identifique o pod do trabalho:

bash

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

Na seção Events , procure entradas para o pod específico, da seguinte maneira:

bash

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

Veja os logs do pod com falha:

bash

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

Exemplo:

bash

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

Após revisar os logs, tente instalar novamente usando Helm enquanto observa mensagens de erro específicas e verifica os logs em busca de possíveis problemas. Abaixo estão alguns problemas conhecidos e como interpretá-los:

IdentityClientId inválido: Error getting system identity auth token. The API endpoint returned 404: Failed to find Identity: <identityClientId-value>
IdentityClientSecret inválido: Error getting system identity auth token. The API endpoint returned 400: Bad client secret.
Identidade expirada: Error getting system identity auth token. The API endpoint returned 400: Expired client secret.
Permissões necessárias ausentes: 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.

Se você vir uma mensagem de erro como a abaixo nos logs do pod de implantação do coletor OpenTelemetry, isso pode indicar uma chave de licença do New Relic inválida. Isso impede que o coletor consiga exportar dados de telemetria para o New Relic:

bash

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

Solução

Confirme se você está usando uma chave de licença válida do New Relic em sua configuração.

Se o pod de um agente gerenciado não estiver sendo criado, pode haver um problema com seu HelmRelease.

Verifique o status da versão do Helm:

bash

$kubectl get helmrelease open-telemetry -n newrelic

Uma versão bem-sucedida e saudável deve mostrar READY: True e STATUS: InstallSucceeded.

Se a liberação falhar, os campos STATUS e READY indicarão o problema. Dependendo do tipo de erro, o problema raiz pode não ser totalmente refletido no campo de status. Para obter mais detalhes, use kubectl para descrever o recurso HelmRelease:

bash

$kubectl describe helmrelease open-telemetry -n newrelic

Ao excluir o agent-control-bootstrap, um job é iniciado para excluir todos os recursos e charts criados.

Se a desinstalação exibir um erro como: * job agent-control-bootstrap-uninstall-job failed: BackoffLimitExceeded

Você pode visualizar os logs do job para depurar o erro.

bash

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

Se o comando helm delete for cancelado durante a execução, o job de desinstalação continuará funcionando, excluindo os charts e recursos, mas o segredo helm agent-control-bootstrap ainda poderá existir. Nesse caso, você não conseguirá atualizar ou instalar o chart, recebendo o erro:

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

Executar a desinstalação novamente não funcionará, os logs do job de desinstalação exibirão um erro como:

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

Solução

Exclua todos os segredos do Helm da sua release (substitua agent-control-bootstrap pelo nome da sua release, caso tenha sido alterado):

bash

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

Em seguida, você pode realizar a instalação novamente.

A ferramenta de diagnóstico New Relic NRDiag é um utilitário que reúne recursos e logs relacionados ao agente-control no seu cluster para depuração. Siga estas etapas para reunir todos os dados:

No seu host, instale a ferramenta NRDiag usando o guia de primeiros passos.
Execute a suíte de controle do agente K8s:
dica
Certifique-se de que kubectl e helm estejam instalados.
- Execute o comando no namespace definido no contexto do kubeconfig:
bash
```
$./nrdiag -suites K8s-agent-control
```
- Especifique um namespace diferente para o agente Control usando o sinalizador --k8s-namespace :
bash
```
$./nrdiag -suites K8s-agent-control --k8s-namespace=newrelic
```
- Especifique um namespace diferente para subagentes usando a flag ac-agents-namespace:
bash
```
$./nrdiag -suites K8s-agent-control --k8s-namespace=newrelic-agent-control --ac-agents-namespace=newrelic
```

A saída esperada deve ser semelhante ao seguinte relatório:

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.

Todos os logs e recursos relacionados ao Agent Control são salvos no arquivo nrdiag_output.zip no diretório atual. Você pode analisar o conteúdo do arquivo zip ou abrir um ticket de suporte com o suporte da New Relic para obter assistência adicional.

Solução de problemas de hosts Linux

Se você receber a mensagem de erro Installing agent-control (Unsupported), verifique os requisitos do sistema e certifique-se de que está executando uma versão de sistema operacional suportada.

Se você vir Installing agent-control (Failed), siga estas etapas:

Verifique os logs fornecidos com o script de instalação:
- Se você vir Error creating an identity, certifique-se de que sua chave de usuário pertença a um usuário da plataforma com a função Admin de todos os produtos.
Verifique o status do serviço newrelic-agent-control:
bash
```
$sudo systemctl status newrelic-agent-control
```
Se o serviço aparecer no estado failed ou stopped, isso significa que o agente foi instalado, mas há um problema impedindo seu funcionamento normal. Verifique os logs dos serviços do agente usando journalctl (ou qualquer ferramenta Linux similar):
bash
```
$journalctl -u newrelic-agent-control
```
Se não houver insights disponíveis, verifique como executar o agente no modo de depuração para acessar logs detalhados explicando por que o serviço não pode ser iniciado.
Se o serviço não estiver instalado, tente adicionar --debug ao final do comando de instalação da CLI da instalação guiada e execute-o novamente. Isso habilita o log detalhado para o script de instalação e pode fornecer contexto adicional explicando o erro.
Opcionalmente, responda yes quando solicitado a enviar logs para a New Relic para ajudar a solucionar problemas na instalação. Uma vez enviados, os logs podem ser acessados com a seguinte consulta NRQL:
```
SELECT * FROM Log WHERE hostname = `your-host-name`
```

Para acessar os logs, você precisará primeiro ativar o log do agente seguindo estas etapas:

Para habilitar o logging em um arquivo, use a configuração log no arquivo de configuração do Agent Control:

# Fleet Control connection settings
  #fleet_control:

  # managed agents settings
  #agents:

  # agent logging settings
  log:
    level: debug
    file:
      enable: true
      # Add a custom path if needed, default path: /var/log/newrelic-agent-control/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"

Os valores possíveis para o nível de log são:

trace
debug
info (padrão)
warning
error
Logs do agente de infraestrutura subjacente e/ou do coletor OpenTelemetry são incluídos quando o nível é debug ou trace.

Reiniciar o Controle do Agente.
Se o log file estiver habilitado, verifique o arquivo local correspondente com base na configuração path. Ou use sua ferramenta de solução de problemas de log preferida, como journalctl -u new-relic-agent-control.

Para acessar os detalhes do status de integridade, você precisará primeiro habilitar o servidor local seguindo estas etapas:

Adicione as seguintes configurações no arquivo de configuração do Agent Control:

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

Reiniciar o Controle do Agente.

Consulte o endpoint de status usando o seguinte comando:

bash

$curl 127.0.0.1:51200/status

O servidor retornará as informações de integridade no formato json, exemplo:

{
  "agent_control": {
    "healthy": true
  },
  "fleet_control": {
    "enabled": true,
    "endpoint": "https://opamp.service.newrelic.com/v1/opamp",
    "reachable": true
  },
  "sub_agents": {
    "nr-otel-collector": {
      "agent_id": "nr-otel-collector",
      "agent_type": "newrelic/com.newrelic.opentelemetry.collector:0.1.0",
      "healthy": true
    },
    "nr-infra-agent": {
      "agent_id": "nr-infra-agent",
      "agent_type": "newrelic/com.newrelic.infrastructure:0.1.0",
      "healthy": false,
      "last_error": "process exited with code: exit status: 1"
    }
  }
}

O Agent Control realiza certas validações antes de receber e aplicar a configuração remota do Fleet Control. Além disso, as configurações podem ter um formato válido (por exemplo, estrutura .yaml válida), mas incluir valores inesperados para certas configurações (por exemplo, um string quando um integer é esperado). A tabela a seguir mostra erros comuns para os diferentes agentes suportados:

Tipo de agente	Erro	Notas de solução de problemas
(Todos os agentes)	Erro ao aplicar configuração remota: não foi possível resolver a configuração	Revise o formato de sua configuração. A configuração pode não ser um arquivo `.yaml` válido, ou campos obrigatórios podem estar ausentes.
(Todos os agentes)	Configuração inválida: valores restritos detectados	Revise o conteúdo da sua configuração. Configurações específicas podem não estar disponíveis para o tipo de agente de destino com base na política de segurança.
(Todos os agentes)	`exit code 1`	Revise sua configuração. Valores inesperados estão fazendo com que o agente seja encerrado com um erro inesperado.
Agente de infraestrutura	`exit code 1`	Revise sua configuração. Valores inesperados estão fazendo com que o agente de infraestrutura encerre com uma configuração inesperada. Verifique as configurações suportadas.

Solução de problemas de hosts Windows

Se o Agent Control não estiver em execução ou íntegro, siga estas etapas de diagnóstico na ordem:

1. Verifique o status do serviço:

Get-Service -Name newrelic-agent-control

Esperado: Status : Running. Se estiver parado ou ausente, siga para a etapa 2.

2. Verifique os logs do serviço:

Visualize o arquivo de log mais recente (arquivos de log incluem sufixos de data como newrelic-agent-control.log.2026-02-09-11):

Get-ChildItem "C:\ProgramData\New Relic\newrelic-agent-control\logs\" -Filter "newrelic-agent-control.log.*" | Sort-Object LastWriteTime -Descending | Select-Object -First 1 | Get-Content -Tail 50

Dica

Configuração de log de arquivo: O Agent Control requer configuração explícita para habilitar o log de arquivo. Se não houver arquivos de log, adicione isto ao seu local_config.yaml:

log:
  file:
    enabled: true

Em seguida, reinicie o serviço para que os logs apareçam.

3. Teste a execução manual:

Execute o Agent Control a partir da linha de comando para contornar problemas específicos do serviço:

cd "C:\Program Files\New Relic\newrelic-agent-control"
.\newrelic-agent-control.exe --config "C:\Program Files\New Relic\newrelic-agent-control\local-data\agent-control\local_config.yaml"

Se ele for executado com sucesso na linha de comando, mas não como um serviço, isso indica problemas de antivírus ou de permissão.

4. Verifique o tipo de frota:

Certifique-se de que a frota seja do tipo "Host - Windows". Usar "Host - Linux" causará falhas. Verifique na UI do Fleet Control em detalhes da frota.

5. Verifique se há conflitos de porta:

O Agent Control usa a porta 51200 para seu endpoint de integridade:

netstat -ano | findstr :51200

Se outro processo estiver usando esta porta, identifique-o:

Get-Process -Id (Get-NetTCPConnection -LocalPort 51200).OwningProcess

6. Verifique a conectividade de rede:

Testar conexão com o Fleet Control:

Test-NetConnection -ComputerName fleet-control.newrelic.com -Port 443
Test-NetConnection -ComputerName download.newrelic.com -Port 443

Ambos devem mostrar TcpTestSucceeded : True.

7. Revise a sintaxe de configuração:

Verifique se há erros de sintaxe YAML:

Get-Content "C:\Program Files\New Relic\newrelic-agent-control\local-data\agent-control\local_config.yaml"

Verifique se há problemas comuns: indentação incorreta, dois-pontos ausentes, caracteres especiais sem aspas.

8. Verifique se há agentes conflitantes:

Verifique se os agentes New Relic existentes estão desinstalados:

Get-Service -Name newrelic-infra -ErrorAction SilentlyContinue
Get-Process -Name newrelic-infra -ErrorAction SilentlyContinue

Se qualquer um dos comandos retornar resultados, desinstale o Infrastructure Agent antes de prosseguir.

9. Verifique os privilégios de administrador:

Confirme se o PowerShell está sendo executado como Administrador:

([Security.Principal.WindowsPrincipal][Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)

Deve retornar True.

10. Reinicie o serviço:

Após resolver os problemas, reinicie o serviço:

Restart-Service -Name newrelic-agent-control
Start-Sleep -Seconds 30
Get-Service -Name newrelic-agent-control
Invoke-WebRequest -Uri "http://localhost:51200/status" -UseBasicParsing

Mensagem de erro comum

Erro/Sintoma	Causa provável	Solução
`Error 1067: The process terminated unexpectedly`	Bloqueio de antivírus, erro de configuração ou dependências ausentes	Adicione exclusões de antivírus, verifique a sintaxe de configuração, verifique os logs de serviço para obter detalhes
O serviço inicia e para imediatamente	Erro no arquivo de configuração ou credenciais inválidas	Revise `local_config.yaml`, verifique a chave de licença e as credenciais da frota
`Port 51200 already in use`	Conflito de porta com outra aplicação	Identifique o processo usando a porta com `netstat`, pare o serviço conflitante
`Failed to connect to Fleet Control`	Bloqueio de rede/firewall ou configuração incorreta da frota	Teste a conectividade com `Test-NetConnection`, verifique o ID e o tipo da frota
`Invalid fleet type` erro nos logs	O tipo de Fleet não é "Host - Windows"	Recrie a frota com o tipo correto na interface do Fleet Control
O serviço não inicia, executa corretamente a partir da linha de comando	Antivírus ou política de segurança do Windows bloqueando o serviço	Adicione exclusões para executáveis e diretórios, verifique com a equipe de segurança
`License key validation failed`	Chave de licença incorreta, expirada ou ausente	Verifique a chave de licença no arquivo de configuração, certifique-se de que ela é válida para sua conta
Nenhum dado aparecendo na UI após 10+ minutos	Agente não implantado ou configuração não sincronizada	Verifique a interface do Fleet Control para o status da implantação, verifique a configuração da frota

Obtendo ajuda adicional

Se a solução de problemas não resolver o seu problema:

Ative o log de depuração editando local_config.yaml:
```
log:
  level: debug
```
Reinicie o serviço e reproduza o problema

Coletar logs para suporte:

Get-ChildItem "C:\ProgramData\New Relic\newrelic-agent-control\logs\" -Filter "newrelic-agent-control.log.*" | Sort-Object LastWriteTime -Descending | ForEach-Object { Get-Content $_.FullName } | Out-File -FilePath "$env:USERPROFILE\Desktop\agent-control-debug.log"

Entre em contato com o Suporte da New Relic com os logs coletados

Esta tradução de máquina é fornecida para sua comodidade.

Importante

Solução de problemas do Kubernetes

Habilitar log de depuração

endpointde status

Falha na liberação Helm

Licença New Relic inválida

Falha no HelmRelease para agente gerenciado

Visualizar erros de desinstalação do Helm

Impossibilidade de instalar ou atualizar após uma desinstalação cancelada

Solucionar problemas com NRDiag

dica

Solução de problemas de hosts Linux

Não foi possível instalar via New Relic CLI

Diagnosticar problemas com os logs do agente

Endpoint de status de integridade local

Configuração remota inválida ou inesperada com o Fleet Control

Solução de problemas de hosts Windows

Dica

Mensagem de erro comum

Obtendo ajuda adicional

Esta tradução de máquina é fornecida para sua comodidade.

Solucionar problemas comuns

Importante

Solução de problemas do Kubernetes.css-21sua1{background:none;border:none;width:0;padding:0;}

endpointde status

Falha na liberação Helm

Licença New Relic inválida

Falha no HelmRelease para agente gerenciado

Visualizar erros de desinstalação do Helm

Impossibilidade de instalar ou atualizar após uma desinstalação cancelada

Solucionar problemas com NRDiag

Solução de problemas de hosts Linux

Não foi possível instalar via New Relic CLI

Diagnosticar problemas com os logs do agente

Endpoint de status de integridade local

Configuração remota inválida ou inesperada com o Fleet Control

Solução de problemas de hosts Windows

Dica

Mensagem de erro comum

Obtendo ajuda adicional

Solução de problemas do Kubernetes