Différences de schéma de données du gateway

Les processeurs de gateway traitent les données de télémétrie avant qu'elles n'atteignent New Relic, ce qui signifie que certains attributs disponibles dans NRDB ne sont pas encore disponibles au niveau du gateway. Comprendre ces différences est essentiel lors de la rédaction d'expressions OTTL pour les processeurs de filtrage, de transformation et d'échantillonnage.

Pourquoi les schémas diffèrent

Flux de données et enrichissement

Lorsque les données de télémétrie transitent par la plateforme New Relic :

Traitement du gateway - Votre gateway reçoit la télémétrie brute des agents et d'autres sources
Enrichissement - New Relic ajoute des attributs (comme entity.guid, appName) et renomme certains attributs existants
Traitement des règles cloud - Les règles cloud basées sur le NRQL opèrent sur des données enrichies
Stockage - Les données sont stockées dans NRDB avec tous les enrichissements appliqués

Impact sur les processeurs de gateway

Les processeurs de gateway voient les données de pré-enrichissement, ce qui signifie :

Certains attributs n'existent pas encore (comme entity.guid, appName, entityGuid)
Les noms d'attributs peuvent différer de ce que vous voyez dans NRDB.
La logique de filtrage et de transformation doit prendre en compte cet ensemble réduit d'attributs

Les règles cloud voient les données post-enrichissement, ce qui signifie :

Tous les attributs enrichis sont disponibles
Les requêtes NRQL peuvent référencer des attributs qui n'existent pas au niveau du gateway

Sources de données

Le gateway reçoit la télémétrie de :

Agents APM New Relic (plusieurs langages pris en charge)
agent New Relic Infrastructure
Collecteurs OpenTelemetry
APIs New Relic (API Events, API Logs, API Traces, API Metrics)
Autres sources compatibles OTLP

Important

Consultez la documentation de configuration de l'agent pour vérifier quels agents et versions sont pris en charge pour le déploiement du gateway.

Toutes les données arrivent sous forme de JSON complexe et multi-imbriqué avec de nombreux attributs.

Écriture d'expressions OTTL pour les processeurs de gateway

Disponibilité des attributs

Lors de la rédaction de conditions de filtrage ou d'instructions de transformation OTTL :

Attributs disponibles :

Attributs de télémétrie de base envoyés par les agents/collecteurs
Attributs ajoutés directement par votre instrumentation
Attributs OTLP standards (comme span_id, trace_id, severity.number)

Attributs indisponibles (ajoutés lors de l'enrichissement) :

entity.guid, entityGuid
appId, appName
host (dans la plupart des cas)
realAgentId
Divers attributs de métadonnées spécifiques à NR

Consultez le tableau de référence des attributs ci-dessous pour obtenir des détails complets.

Meilleures pratiques

Testez avec des données réelles : Utilisez les données de monitoring de votre gateway pour vérifier quels attributs existent dans votre télémétrie avant d'écrire des filtres complexes.

Utiliser les attributs disponibles :

# ✓ 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"'

Envisagez des règles cloud pour les attributs enrichis : Si votre logique de filtrage nécessite des attributs enrichis (comme appName ou entity.guid), utilisez des règles cloud plutôt que des processeurs de gateway.

Consultez le tableau de référence : Avant d'utiliser un attribut dans un filtre ou une transformation, vérifiez qu'il n'est pas indiqué comme "indisponible au niveau du gateway" dans le tableau ci-dessous.

Référence des attributs par type de données

Le tableau suivant indique les attributs indisponibles au niveau du gateway pour chaque type de données de télémétrie. Si vous devez filtrer ou transformer en fonction de ces attributs, envisagez plutôt d'utiliser les règles cloud.

Type de données	attribut indisponible à le gateway	Exemple d'expression de filtre (OTTL)
Transaction (APM)	`appId` , `appName` , `containerId` , `entity.guid` , `entityGuid` , `host` , `realAgentId` , `transactionSubType` , `transactionType`	`attributes["guid"] == "c2906c2e8b9f11ff"`
événement personnalisé	`appId` , `appName` , `containerId` , `entityGuid` , `host` , `realAgentId`	`attributes["myFloat"] == 0.603`
Trace d'erreur	`aggregateFacet` , `appId` , `appName` , `applicationIds` , `count` , `entity.guid` , `entityGuid` , `error.class` , `message` , `path` , `exceptionClass` , `fingerprint` , `id` , `message` , `realAgentId` , `storageId` , `timestamp` , `transactionName` , `transactionUiName`	`attributes["traceId"] == "b366efe772fa6d1c8e0852558026c40e"`
Erreur de transaction	`aggregateFacet` , `appId` , `appName` , `containerId` , `entity.guid` , `entityGuid` , `host` , `realAgentId` , `transactionUiName`	`attributes["error.message"] == "my expected error message"`
enregistrer	`entity.guids` , `messageId` , `newrelic.logPattern` , `newrelic.logs.batchIndex` , `newrelic.source`	`span_id == "8b583de97341d094"`
Métrique (tranche de temps)	`appId` , `appName` , `entity.guid` , `entityGuid` , `language` , `metricName` , `metricTimesliceName` , `newrelic.timeslice.value` , `scope` , `timestamp`	Utiliser des métriques dimensionnelles ou des règles cloud
Span (traçage distribué)	`appId` , `appName` , `containerId` , `duration.ms` , `entity.guid` , `entity.name` , `entityGuid` , `host` , `id` , `process.id` , `realAgentId` , `trace.id`	`name == "WebTransaction/Go/GET /log"`
SqlTrace	`applicationIds` , `callCount` , `databaseMetricName` , `entity.guid` , `id` , `maxCallTime` , `minCallTime` , `path` , `realAgentId` , `sql` , `sqlId` , `storageId` , `timestamp` , `totalCallTime` , `uri`	`attributes["uri"] == "Custom/Simple/sqlTransaction"`
Trace de transaction	`storageId` , `uri` , `path` , `agentRunId` , `applicationIds` , `duration` , `entity.guid` , `guid` , `id` , `protocolVersion` , `realAgentId` , `timestamp`	Utiliser les attributs disponibles dans les données de trace brutes
Métrique (jauge)	`newrelic.source` (valeur : `metricAPI` ), `metricName` : `{type, count, latest, max, min, sum}`	`name == "redis_aof_rewrite_in_progress" and value < 100`
Métrique (résumé)	`newrelic.source` (valeur : `metricAPI` ), `metricName` : `{type, count, max, min, sum}`	`attributes["scrapedTargetKind"] == "user_provided"`
Métrique (nombre)	`newrelic.source` (valeur : `metricAPI` ), `metricName` : `{type, count}`	`attributes["instrumentation.name"] == "nri-prometheus"`
SystemSample (Infrastructure)	Aucun	`attributes["entityKey"] == "vagrant"`
StorageSample (Infrastructure)	`entityAndMountPoint`	`attributes["inodesUsed"] == 161604`
NetworkSample (Infrastructure)	`entityAndInterface`	`attributes["entityKey"] == "vagrant"`
ProcessSample (Infrastructure)	`entityAndPid`	`attributes["entityKey"] == "vagrant"`
ContainerSample (Infrastructure)	`entityGuid` , `entityType` , `entityId`	`attributes["agentName"] == "ContainerSampleAgent"`

Scénarios courants

Filtrage par entité

Problème : Vous souhaitez filtrer les spans par entité, mais entity.guid n'existe pas sur le gateway.

Solution : Utilisez le nom du service ou d'autres attributs d'identification présents dans la télémétrie brute :

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

Filtrage par nom d'application

Problème : Les transactions APM n'ont pas de appName au niveau du gateway.

Solution : Utilisez les attributs définis directement par votre agent ou appliquez un filtrage après l'enrichissement avec les règles cloud.

Ajout d'informations sur l'entité

Problème : Vous souhaitez ajouter un contexte d'entité à la télémétrie au niveau du gateway.

Solution : Vous ne pouvez pas accéder à entity.guid au niveau du gateway, mais vous pouvez ajouter vos propres métadonnées d'identification :

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

Dépannage

Le filtre ne correspond pas aux données attendues

Si votre processeur de filtres ne correspond pas aux données attendues :

Vérifier la disponibilité de l'attribut - Vérifiez que l'attribut existe au niveau du gateway (pas uniquement dans la NRDB)
Inspectez la télémétrie réelle - Utilisez le monitoring du gateway pour voir quels attributs sont réellement présents

Tester l'accès à l'attribut - Essayez un filtre simple sur l'attribut pour voir s'il existe :

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

La transformation ne définit pas les valeurs attendues

Si les attributs ne sont pas ajoutés ou modifiés :

Vérifiez les noms d'attributs - Les noms d'attributs de pré-enrichissement peuvent différer de NRDB
Vérifiez le type de données - Assurez-vous d'accéder correctement aux attributs (par ex. attributes["key"] vs accès direct aux champs)
Vérifiez l'ordre des processeurs - Assurez-vous que les transformations s'exécutent avant les filtres qui en dépendent

Prochaines étapes

Référence du processeur de filtre - Découvrir la syntaxe de filtre OTTL
Référence du processeur de transformation - En savoir plus sur les instructions de transformation OTTL
Documentation sur les règles cloud - Utilisez le NRQL sur les données enrichies

Cette traduction automatique est fournie pour votre commodité.