• /
  • EnglishEspañol日本語한국어Português
  • EntrarComeçar agora

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

Caso haja alguma divergência entre a versão em inglês e a traduzida, a versão em inglês prevalece. Acesse esta página para mais informações.

Criar um problema

Arquivo executável de integração no host: especificações JSON

Uma integração no host do agente de infraestrutura New Relic consistirá em pelo menos dois arquivos: um arquivo executável e pelo menos um arquivo de configuração. O arquivo executável gera dados JSON que são consumidos pelo agente de infraestrutura e enviados para a New Relic. Referimo-nos ao objeto JSON como protocolo de integração SDK.

Requisitos de arquivo executável

O executável pode ser qualquer arquivo executado em uma interface de linha de comando; por exemplo:

  • Um script de shell
  • Um scriptde linguagem de script
  • Um binário compilado

O único requisito do seu arquivo executável é que ele exporte dados JSON, em um formato de linha única, que atenda às especificações deste documento.

Recomendação: Utilize Go para criar integração; é a linguagem que usamos para criar integração no host e as ferramentas de construção de integração. No entanto, você pode criar uma integração em qualquer idioma.

Colocação de arquivo

O arquivo executável vai neste diretório:

  • Linux:

    /var/db/newrelic-infra/custom-integrations
  • Windows:

    C:\Program Files\New Relic\newrelic-infra\newrelic-integrations

Protocolo de integração v4: exemplo de saída JSON

A seção a seguir explica o novo esquema JSON (protocolo de integração v4). O SDK v4 oferece suporte apenas a esta nova versão do protocolo. Estas são as mudanças mais importantes:

  • Um novo objeto integration no nível superior.
  • Os objetos entity e metrics foram modificados.

Consulte o guia de migração v3 para v4 para obter mais informações.

{
"protocol_version":"4", # protocol version number
"integration":{ # this data will be added to all metrics and events as attributes,
# and also sent as inventory
"name":"integration name",
"version":"integration version"
},
"data":[ # List of objects containing entities, metrics, events and inventory
{
"entity":{ # this object is optional. If it's not provided, then the Entity will get
# the same entity ID as the agent that executes the integration.
"name":"redis:192.168.100.200:1234", # unique entity name per customer account
"type":"RedisInstance", # entity's category
"displayName":"my redis instance", # human readable name
"metadata":{} # can hold general metadata or tags. Both are key-value pairs that will
# be also added as attributes to all metrics and events
},
"metrics":[ # list of metrics using the dimensional metric format
{
"name":"redis.metric1",
"type":"count", # gauge, count, summary, cumulative-count, rate or cumulative-rate
"value":93,
"attributes":{} # set of key-value pairs that define the dimensions of the metric
}
],
"inventory":{...}, # Inventory remains the same
"events":[...] # Events remain the same
}
]
}

Protocolo de integração v3: exemplo de saída JSON

O JSON inclui:

  • Um cabeçalho, com dados básicos de integração (nome, versão)
  • Uma lista de dados, que inclui um ou mais dados de reporte da entidade (dados métricos, de inventário e/ou de eventos)

Este diagrama mostra esta estrutura:

New Relic Integrations SDK data structure diagram

Aqui está um exemplo de saída JSON (formatada com quebras de linha para facilitar a leitura). As definições e especificações seguem este exemplo:

{
"name": "my.company.integration",
"protocol_version": "3",
"integration_version": "x.y.z",
"data": [
{
"entity": {
"name": "my_garage",
"type": "building",
"id_attributes": [
{
"key": "environment",
"value": "production"
},
{
"key": "node",
"value": "master"
}
]
},
"metrics": [
{
"temperature": 25.3,
"humidity": 0.45,
"displayName": "my_garage",
"entityName": "building:my_garage",
"event_type": "BuildingStatus"
}
],
"inventory": {
"out_door": {
"status": "open"
}
},
"events": []
},
{
"entity": {
"name": "my_family_car",
"type": "car",
"id_attributes": [
{
"key": "environment",
"value": "production"
},
{
"key": "node",
"value": "master"
}
]
},
"metrics": [
{
"speed": 95,
"fuel": 768,
"displayName": "my_family_car",
"entityName": "car:my_family_car",
"event_type": "VehicleStatus"
}
],
"inventory": {
"motor": {
"brand": "renault",
"cc": 1800
}
},
"events": [
{
"category": "gear",
"summary": "gear has been changed"
}
],
"add_hostname": true
}
]
}

JSON: especificações gerais

Aqui estão as especificações gerais para a saída JSON:

JSON: cabeçalho

Aqui está um exemplo da primeira parte da saída JSON de uma integração no host:

"name":"com.myorg.nginx",
"protocol_version":"3",
"integration_version":"1.0.0",
"data": [ {entities}...]

Uma carga útil mínima seria um objeto JSON com apenas os campos de cabeçalho. Recomendação: Caso não haja dados para coletar, utilize o código de retorno do programa e a mensagem do log escrita em stderr.

Campos de cabeçalho JSON

Descrição

name

Obrigatório. Deve ser idêntico ao campo name no arquivo de configuração.

Recomendação: Use nomes de domínio reversos para gerar nomes de integração exclusivos.

protocol_version

Obrigatório. O número da versão do protocolo de troca entre a integração e o agente que o executável de integração está usando.

  • A versão atual é 3. Este protocolo requer o agente de infraestrutura 1.2.25 ou superior.

  • O Protocolo 2 requer o agente de infraestrutura 1.0.859 ou superior.

  • O protocolo 1 é compatível com todos os agentes.

    Para obter mais informações, consulte Alterações no SDK.

integration_version

Opcional. A versão de integração. Usado para rastrear a versão de integração em execução em cada host.

Uma integração pode ter mais de um executável. Portanto esta não é simplesmente a versão do executável.

data

Obrigatório para relatar dados. Uma lista contendo os dados reportados de uma ou mais entidades.

JSON: entidade

Dentro da listadata da saída JSON estão uma ou mais entidades. Os campos de entrada da entidade incluem:

Campos JSON da entidade

Descrição

entity

Obrigatório. Dados ou propriedades da entidade.

metrics

Opcional. lista de métricas relacionadas à entidade.

inventory

Opcional. Itens de inventário relacionados à entidade.

events

Opcional. lista de eventos relacionados à entidade.

add_hostname

Opcional. Boleano. Se true, a entidade métrica será decorada com o hostname.

Dentro da listadata da saída JSON estão uma ou mais entidades e seus dados. A entrada entity possui dois campos:

Campos JSON de dados da entidade

Descrição

name

Obrigatório. O identificador/nome da entidade.

Recomendação: Use nomes de domínio reversos para gerar nomes de integração exclusivos.

type

Obrigatório. O tipo de entidade. Ele será utilizado pelo agente de infraestrutura como namespace para compor um unique identifier em conjunto com o name.

id_attributes

Opcional. Uma lista de valores principais atributo que conferem exclusividade a uma entidade. Eles são anexados ao nome no formato key=value para facilitar a leitura, fornecer informações extras e melhorar a exclusividade do nome da entidade.

Identificador atributo são úteis quando o nome da entidade não é suficiente para funcionar como um identificador único ou quando não fornece informações significativas suficientes. Por exemplo:

[
{
"key": "service",
"value": "mysql"
},
{
"key": "role",
"value": "master"
}, ...
]

Substituição de endereço de loopback em nomes de entidades

A partir do agente de infraestrutura versão 1.2.25 ou superior, o protocolo v3 melhora a exclusividade da entidade remota adicionando substituição de endereço local em nomes de entidades no nível do agente.

Quando várias entidades remotas têm seus nomes baseados em um endpoint (ip ou hostname) e esse nome contém endereços de loopback, há dois problemas:

  • Este valor localhost não fornece informações valiosas sem mais contexto.
  • O name pode colidir com outro serviço nomeado com um endereço local.

Isso acontece quando:

  • Os nomes dos endpoints são como localhost:port.
  • As portas tendem a ser as mesmas para um determinado serviço; por exemplo, 3306 para MySQL.

Nos dados de entrada do protocolo v3, o agente de infraestrutura substitui os endereços de loopback no nome (e chave) da entidade pelo primeiro item disponível da lista a seguir:

  1. ID da instância do provedor de nuvem, recuperado pelo agente, se aplicável
  2. Nome de exibição, definido por meio da opção de configuração do agente display_name
  3. Nome do host, conforme recuperado pelo agente

Por exemplo, se uma integração usando o protocolo v3 retornar uma entidade com o nome localhost:3306, e o agente estiver rodando em bare metal (não possui ID do provedor de nuvem da instância), o display_name não foi definido e o nome do host for prod-mysql-01, então o agente substituirá o localhost e produzirá o nome da entidade prod-mysql-01:3306.

O agente de infraestrutura permite a substituição automática de endereços de loopback para o protocolo de integração v3. Você também pode ativar isso para v2 por meio do sinalizador de configuração do agente replace_v2_loopback_entity_names. Neste caso todas as integrações que estão sendo executadas pelo agente utilizando v2 terão seus nomes substituídos sempre que portarem um endereço local.

JSON: dados de métricas, inventário e eventos

Os valores dos dados seguem o cabeçalho do arquivo executável. Você pode registrar três tipos de dados:

Importante

Da perspectiva do painel New Relic, infraestrutura métrica e evento são classificados como dados de evento.

Copyright © 2024 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.