Diferenças no esquema de dados do Gateway

Os processadores de gateway operam em dados de telemetria antes que eles cheguem ao New Relic, o que significa que alguns atributos disponíveis no NRDB ainda não estão disponíveis no gateway. Entender essas diferenças é fundamental ao escrever expressões OTTL para processadores de filtro, transformação e amostragem.

Por que os esquemas diferem

Fluxo de dados e enriquecimento

Quando os dados de telemetria fluem pela plataforma da New Relic:

1. Processamento do gateway - Seu gateway recebe telemetria bruta de agentes e outras fontes
2. Enriquecimento - A New Relic adiciona atributos (como entity.guid, appName) e renomeia alguns atributos existentes
3. Processamento de regras de nuvem - Regras de nuvem baseadas em NRQL operam em dados enriquecidos
4. Armazenamento - Os dados são armazenados no NRDB com todos os enriquecimentos aplicados

Impacto nos processadores de gateway

Processadores de Gateway veem dados de pré-enriquecimento, o que significa:

• Alguns atributos ainda não existem (como entity.guid, appName, entityGuid)
• Os nomes dos atributos podem diferir do que você vê no NRDB
• A lógica de filtro e transformação deve levar em conta esse conjunto reduzido de atributos

Regras de nuvem veem dados pós-enriquecimento, o que significa:

• Todos os atributos enriquecidos estão disponíveis
• Consultas NRQL podem referenciar atributos que não existem no gateway

Fontes de dados

O gateway recebe telemetria de:

• Agentes do New Relic APM (várias linguagens suportadas)
• Agente do New Relic Infrastructure
• Coletores do OpenTelemetry
• APIs da New Relic (API de Eventos, API de Logs, API de Traces, API de Métricas)
• Outras fontes compatíveis com OTLP

Todos os dados chegam como JSON complexo e multianinhado com inúmeros atributos.

Escrevendo expressões OTTL para processadores de gateway

Disponibilidade de atributos

Ao escrever condições de filtro ou instruções de transformação OTTL:

Atributos disponíveis:

• Atributos principais de telemetria enviados por agentes/coletores
• Atributos que sua instrumentação adiciona diretamente
• Atributos OTLP padrão (como span_id, trace_id, severity.number)

Atributos indisponíveis (adicionados durante o enriquecimento):

• entity.guid, entityGuid
• appId, appName
• host (na maioria dos casos)
• realAgentId
• Vários atributos de metadados específicos do NR

Consulte a tabela de referência de atributos abaixo para obter detalhes completos.

Práticas medidas

Teste com dados reais: Use os dados de monitoramento do seu gateway para verificar quais atributos existem na sua telemetria antes de escrever filtros complexos.

Use os atributos disponíveis:

# ✓ Works - span_id exists in raw telemetry
filter/Spans:
  config:
    spans:
      - 'span_id.string == "abc123"'

# ✗ May not work - entity.guid added during enrichment
filter/Spans:
  config:
    spans:
      - 'attributes["entity.guid"] == "xyz789"'

Considere regras de nuvem para atributos enriquecidos: Se sua lógica de filtragem exigir atributos enriquecidos (como appName ou entity.guid), use regras de nuvem em vez de processadores de gateway.

Consulte a tabela de referência: Antes de usar um atributo em um filtro ou transformação, verifique se ele não está listado como "indisponível no gateway" na tabela abaixo.

Referência de atributos por tipo de dados

A tabela a seguir mostra quais atributos estão indisponíveis no nível do gateway para cada tipo de dado de telemetria. Se você precisar filtrar ou transformar com base nesses atributos, considere usar regras de nuvem.

Cenários comuns

Filtragem por entidade

Problema: Você deseja filtrar spans por entidade, mas entity.guid não existe no gateway.

Solução: Use o nome do serviço ou outros atributos de identificação que existem na telemetria bruta:

filter/Spans:
  config:
    spans:
      - 'attributes["service.name"] == "my-service"'

Filtrando por nome da aplicação

Problema: Transações de APM não têm appName no gateway.

Solução: Use atributos que seu agente define diretamente ou aplique filtragem após o enriquecimento com regras de nuvem.

Adicionando informações da entidade

Problema: Você deseja adicionar contexto de entidade à telemetria no gateway.

Solução: Você não pode acessar entity.guid no gateway, mas pode adicionar seus próprios metadados de identificação:

transform/Logs:
  config:
    log_statements:
      - set(attributes["deployment"], "production-us-east")
      - set(attributes["cluster"], "k8s-prod-01")

Resolução de problemas

O filtro não corresponde aos dados esperados

Se o seu processador de filtro não estiver correspondendo aos dados que você espera:

1. Verifique a disponibilidade do atributo - Verifique se o atributo existe no gateway (não apenas no NRDB)
2. Inspecione a telemetria real - Use o monitoramento de gateway para ver quais atributos estão realmente presentes
3. Teste o acesso ao atributo - Tente um filtro simples no atributo para ver se ele existe:

   filter/Test:
     config:
       logs:
         - 'attributes["entity.guid"] != ""'  # Will match nothing if attribute doesn't exist

   Copiar

A transformação não está definindo os valores esperados

Se os atributos não estiverem sendo adicionados ou modificados:

1. Verifique os nomes dos atributos - Os nomes dos atributos de pré-enriquecimento podem diferir do NRDB
2. Verifique o tipo de dados - Certifique-se de que você está acessando os atributos corretamente (por exemplo, attributes["key"] vs acesso direto ao campo)
3. Revise a ordem dos processadores - Garanta que as transformações sejam executadas antes dos filtros que dependem delas

Próximos passos

• Referência do processador de filtro - Aprenda a sintaxe de filtro OTTL
• Referência do processador de transformação - Aprenda as instruções de transformação OTTL
• Documentação das regras de nuvem - Use NRQL em dados enriquecidos