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:

O código de saída deve sair com um código de status 0 e seguir as convenções específicas da plataforma. Por exemplo:

Linux: 0 == EX_OK
Windows: 0 == ERROR_SUCCESS
Se o executável sair com um status diferente de zero, o agente descartará todos os dados de stdout e gravará uma mensagem em seu arquivo de log com o nome da integração, o código de saída e qualquer informação de diagnóstico que puder coletar.

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" }, ... ]`

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:

ID da instância do provedor de nuvem, recuperado pelo agente, se aplicável
Nome de exibição, definido por meio da opção de configuração do agente display_name
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:

Métrica
Evento
Inventário

Importante

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

Dados de infraestrutura métrica normalmente são usados para dados numéricos simples; por exemplo:

Contagem de solicitações MySQL em uma fila por segundo

Contagem de conexões ativas com um sistema específico por minuto

Além dos metadados associados, uma métrica é essencialmente apenas um nome de métrica e um valor numérico. Para saber mais sobre esses dados, consulte Dados do evento.

Aqui está um exemplo de JSON de dados métricos de uma entidade:

[ 
    {
         "event_type":"MyorgNginxSample",
         "net.connectionsActive": 54,  # metric data (a key/value pair)
         "net.requestsPerSecond": 21,  # metric data (a key/value pair)
         "net.reading": 23,   # metric data (a key/value pair)
    }
]

Campo de dados de métrica JSON	Descrição
`event_type`	Obrigatório. `event_type` define onde a métrica será armazenada. Cada conjunto de métricas é armazenado como uma amostra dentro do tipo de evento especificado. Cada integração deve armazenar seus dados em seu próprio tipo de evento. Se você estiver gerando vários tipos de amostras da mesma integração, use tipos de eventos diferentes para cada um. Recomendação: Para garantir que os tipos de eventos usados pela sua integração sejam exclusivos, prefixe o tipo de evento com o nome ou sigla da sua empresa. Por exemplo, se sua integração personalizada capturar a métrica do nó Cassandra e a métrica da família de colunas Cassandra como amostras diferentes, armazene-as em tipos de eventos diferentes, como `MyOrgCassandraSample` e `MyOrgCassandraColumnFamilySample`. Caso o tipo de evento não exista, ele será criado automaticamente quando New Relic receber os dados da sua integração e disponibilizá-los na interface.
Um ou mais pares principais de valores de dados métricos	Obrigatório (pelo menos um). Uma medida métrica contendo um nome (chave) e seu valor. Certifique-se de que estes estejam geralmente em conformidade com a especificação do tipo de entidade para máxima compatibilidade com o recurso de infraestrutura. Recomendação: Prefixe sua métrica com uma categoria para ajudar na navegação pela métrica na interface do New Relic . A integração New Relic usa atualmente: `net`: Número de conexões, solicitações do servidor web, bytes transmitidos pela rede, etc.; por exemplo, `net.connectionsActive`. `query`: métrica diretamente relacionada com consulta ao banco de dados; por exemplo, `query.comInsertPerSecond`. `db`: Banco de dados interno métrico; por exemplo, `db.openTables`. Use prefixos multiníveis para agrupamento adicional quando fizer sentido; por exemplo, `db.innodb.bufferPoolPagesFree`. Use o formato de nomenclatura `innerCamelCase` ; por exemplo: `net.requestsPerSecond`. Use um nome de métrica o mais próximo possível do original, respeitando as demais especificações. Por exemplo: Nome original: `Qcache_hits` Nome da métrica: `db.qCacheHits`
Unidade de medida	Recomendação: Especifique a unidade de medida usando um sufixo de unidade se ainda não estiver incluído no nome da métrica original, como nos exemplos a seguir: Porcentagens: Use `Percent`; por exemplo: `cpuUtilPercent`. Taxas: use um formato como `PerSecond`. Segundos é a medida de taxa padrão, mas você também pode usar outras unidades, como `PerMinute` ou `PerDay`. Medições de bytes: Use `Bytes`. Recomendação: Se uma métrica for capturada em uma unidade diferente, como `Megabytes`, converta-a para `Bytes`. Por exemplo: `db.allMemtablesOffHeapSizeBytes`. Medições de tempo: Use `Milliseconds`. Recomendação: Se uma métrica for capturada em uma unidade diferente, como `Seconds`, converta-a para `Milliseconds`. Por exemplo: `query.readLatency50thPercentileMilliseconds`
Valor	Use uma string ou um número (inteiro ou float). Strings podem ser utilizadas como metadados associados, permitindo que os dados sejam filtrados na interface New Relic . Um booleano precisaria ser expresso como uma string ("true", "false") ou um número inteiro (1, 0). Não utilize tipos complexos de valores, como matriz ou aplicar hash.

Dados de eventos de infraestrutura representam mensagens arbitrárias e únicas para atividades-chave em um sistema; por exemplo:

Iniciando um serviço específico

Criando uma nova tabela

Você pode visualizar esses dados na página infraestrutura Events e infraestrutura evento mapa de calor. Você também pode consultar o tipo de evento InfrastructureEvent no New Relic.

Aqui está um exemplo de carga útil JSON de dados de evento de uma integração, que segue o cabeçalho JSON e as definições de campo.

[
   {
      "summary":"More than 10 request errors logged in the last 5 minutes",
      "category": "notifications"
   }
]

Campo de evento JSON	Descrição
`summary`	Obrigatório. A mensagem a ser enviada. Use uma string simples.
`category`	Opcional. Valor de string de uma das categorias existentes utilizadas no monitoramento de infraestrutura ou de uma nova categoria. O valor padrão é `notifications`. Exemplos de categorias: `applications` `automation` `configuration` `metadata` `notifications` `os` `packages` `services` `sessions` `system` `users`

Campo de evento JSON

Descrição

summary

Obrigatório. A mensagem a ser enviada. Use uma string simples.

category

Opcional. Valor de string de uma das categorias existentes utilizadas no monitoramento de infraestrutura ou de uma nova categoria. O valor padrão é notifications. Exemplos de categorias:

applications
automation
configuration
metadata
notifications
os
packages
services
sessions
system
users

Os dados de inventário de infraestrutura capturam informações do sistema de estado em tempo real; por exemplo:

Dados de configuração
Versões do sistema instaladas
Outros metadados do sistema
Você pode visualizar esses dados na páginaInventory e infraestrutura do evento mapa de calor. Você também pode consultar dados relacionados a alterações de estoque.
O tipo de dados inventory é um hash de aplicação de um ou mais subobjetos JSON contendo:
Uma chave de identificação de inventário exclusiva (obrigatório): o identificador do item de inventário. Isso é usado em combinação com o prefixo da integração para criar um caminho para os dados do item de inventário. Caminhos semelhantes combinam-se entre entidades e mostram possíveis variações. Este ID aponta para um hash aplicar.
Aplica-se hash de pares de valores principais, um por atributo de inventário. Pelo menos um é necessário.
As chaves devem ser strings.
Os valores podem ser do tipo escalar (string ou número) or ou aplicar objeto hash de valor principal. New Relic suporta hierarquia, mas os nós de valor final devem ser escalares.
Aqui está um exemplo de JSON de dados de inventário de uma integração:
```
{
    "events/worker_connections": {
        "value": 1024
                },
    "http/gzip" : {
        "value": "on"
                }
}
```

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

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

Requisitos de arquivo executável

Colocação de arquivo

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

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

JSON: especificações gerais

Saída geral e formatação JSON

Erros e registro

Sair/fechar o executável

JSON: cabeçalho

JSON: entidade

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

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

Importante

Dados métricos

Dados do evento

Dados de inventário

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

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

Requisitos de arquivo executável .css-21sua1{background:none;border:none;width:0;padding:0;}

Colocação de arquivo

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

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

JSON: especificações gerais

Erros e registro

Sair/fechar o executável

JSON: cabeçalho

JSON: entidade

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

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

Importante

Dados métricos

Dados do evento

Dados de inventário

Requisitos de arquivo executável