Remappage de service APM

Avant toute chose : Résolvez complètement toutes les variables dans ## Context to resolve before acting. Ne commencez pas l'Étape 0 tant que chaque variable n'a pas une valeur concrète.

How Service Remapping Works — Domain Knowledge

Lisez ceci avant de construire une règle. Cela vous donne le modèle mental pour construire le bon filtre et capturer les cas limites.

Ce que fait le remappage : Une règle intercepte la télémétrie au moment de l'ingestion et réécrit le nom du service avant l'indexation. Une règle dit : « pour toute entité correspondant à ce filtre, remplacez son nom de service par cette nouvelle valeur. »

Deux types d'entités — choisissez le bon :

Prérequis pour le remappage d'entité inférée — peer.service doit être défini :

Le remappage d'entité inférée ne fonctionne que lorsque le traceur définit peer.service sur les spans sortants. Sans cela, les entités sont clés par peer.hostname et les règles de remappage ne s'appliqueront pas.

Pour l'activer, définissez la variable d'environnement suivante sur le service instrumenté (pas la dépendance aval) :

DD_TRACE_PEER_SERVICE_DEFAULTS_ENABLED=true

Cela fait que le traceur ddtrace propage automatiquement peer.service de peer.hostname sur les appels HTTP, gRPC et base de données sortants. Sans cela, pup traces search affichera des spans avec peer.hostname mais pas peer.service, et aucune règle de remappage de service ne correspondra.

Pour vérifier que peer.service est défini avant de construire une règle :

pup traces search --query "@peer.service:<ENTITY_NAME>" --from 15m --limit 5

Si zéro résultats — le traceur ne définit pas peer.service. Demandez à l'utilisateur d'ajouter DD_TRACE_PEER_SERVICE_DEFAULTS_ENABLED=true à l'environnement de leur service et de redéployer avant de continuer.

Syntaxe du filtre — une chaîne de requête de grammaire d'événement Datadog standard :

Syntaxe du nouveau nom — le champ value dans rewrite_tag_rules :

Contraintes regex pour {{tag\|regex}} :

• Maximum 1 groupe de capture par expression
• Aucun quantificateur gourmand dans les groupes de capture — utilisez les variantes non-gourmandes : (.+?) pas (.+), (.*?) pas (.*)
• Les quantificateurs sur les groupes de capture eux-mêmes (ex. (foo)+) ne sont pas autorisés

Cinq motifs de remappage :

Triggers

Invoquez cette skill quand l'utilisateur veut :

• Renommer un service dans Datadog sans réinstrumenter
• Fusionner plusieurs noms de service inférés en un (ex. beaucoup de variantes api.shopify.com/* → shopify)
• Supprimer les suffixes d'environnement, les balises de version ou les métadonnées de déploiement intégrées aux noms de service
• Normaliser les noms peer.service en quelque chose de significatif
• Renommer un service après un changement organisationnel, un rebrand produit ou une migration
• Scinder un service unique en variantes par env (my-service + env:prod → my-service-prod)
• Lister, examiner ou supprimer les règles de remappage de service existantes

Ne invoquez PAS cette skill si :

• L'utilisateur veut renommer le service dans le code de son application — cela nécessite une modification de la configuration du traceur (DD_SERVICE), pas une règle de remappage
• L'utilisateur veut corréler la télémétrie entre les balises d'infrastructure — c'est le type d'action « Correlate telemetry » dans l'UI, pas le remappage

Prerequisites

pup-cli: check, install, and authenticate

Claude runs

pup --version

If not found:

Claude runs

brew tap datadog-labs/pack
brew install pup

Check auth:

pup auth status

If not authenticated:

Claude runs

pup auth login

Cela ouvre un onglet navigateur pour OAuth. Complétez la connexion là — Claude continuera une fois que la commande se termine.

Credentials for write operations

pup apm service-remapping list et get fonctionnent avec OAuth. Create, update et delete nécessitent des clés API (DD_API_KEY, DD_APP_KEY, DD_SITE) jusqu'à ce que apm_service_renaming_write soit ajouté aux scopes OAuth de pup.

Claude runs

echo "DD_API_KEY set: $([ -n "${DD_API_KEY:-}" ] && echo yes || echo no)"
echo "DD_APP_KEY set: $([ -n "${DD_APP_KEY:-}" ] && echo yes || echo no)"
echo "DD_SITE: ${DD_SITE:-not set (defaulting to datadoghq.com)}"

Si l'un d'eux est manquant et que vous avez besoin de créer/mettre à jour/supprimer des règles :

What you need to do in a terminal

export DD_API_KEY=<your-api-key>
export DD_APP_KEY=<your-app-key>
export DD_SITE=datadoghq.com   # adjust for your site

Sites courants : datadoghq.com (US1), datadoghq.eu (EU1), us3.datadoghq.com, us5.datadoghq.com, ap1.datadoghq.com

Attendez que l'utilisateur définisse les credentials, puis réexécutez la vérification ci-dessus avant de continuer.

Context to resolve before acting

Step 0: Discover Current Service Names

Si l'utilisateur n'a pas spécifié de noms exacts à remapper, découvrez d'abord ce qui existe :

Claude runs

pup apm services list --env <ENV> --from 1h
pup traces search --query "service:<PARTIAL_NAME>" --from 1h --limit 20

Utilisez la sortie pour aider l'utilisateur à identifier les noms de service exacts. Demandez à l'utilisateur de confirmer quels noms ils veulent remappés avant de continuer.

Step 1: Build the Rule

Travaillez sur chaque composant avant d'écrire du JSON.

1. Entity type

[DÉCISION : type d'entité — demandez à l'utilisateur si ce n'est pas clair]

• Le service apparaît-il parce qu'un traceur a explicitement défini sa balise service ? → rule_type: 0 (SERVICE)
• Apparaît-il sur la carte de service à partir d'appels sortants (ex. une base de données, queue ou API externe) ? → rule_type: 1 (INFERRED_ENTITY)

Si l'utilisateur veut remapper une entité inférée, vérifiez que peer.service est défini avant de continuer — voir le prérequis dans Domain Knowledge. S'il n'est pas défini, arrêtez et demandez à l'utilisateur d'activer d'abord DD_TRACE_PEER_SERVICE_DEFAULTS_ENABLED=true.

2. Filter

Écrivez une seule chaîne de requête de grammaire d'événement ciblant le(s) service(s) à remapper. Utilisez la syntaxe du filtre et le tableau de motifs dans Domain Knowledge pour choisir la bonne forme.

3. New name (value)

Utilisez la syntaxe du nouveau nom et le tableau regex dans Domain Knowledge pour choisir la bonne forme. Pour les valeurs regex, appliquez les contraintes énumérées là.

4. Rule name

Suggérez un nom descriptif. Exemples :

• collapse-shopify-inferred-services
• strip-tropos-suffix
• rename-old-auth-to-auth-service
• env-split-my-service-prod

Step 2: Preview Impact

Avant de construire le JSON, vérifiez ce qui sera affecté :

Claude runs

# Confirmez que la télémétrie existe pour le service ciblé (zéro spans = requête incorrecte ou env incorrect)
pup traces search --query "service:<ORIGINAL_SERVICE>" --from 15m --limit 5

# Vérifiez les moniteurs référençant l'ancien nom de service
pup monitors list | grep -i "<ORIGINAL_SERVICE>"

# Vérifiez les tableaux de bord référençant l'ancien nom de service
pup dashboards list | grep -i "<ORIGINAL_SERVICE>"

# Listez les règles de remappage de service existantes qui pourraient entrer en conflit
pup apm service-remapping list

Signalez à l'utilisateur :

Si les moniteurs référencent l'ancien nom de service, demandez :

« J'ai trouvé <N> moniteur(s) référençant <ORIGINAL_SERVICE>. Après remappage, ils devront être mis à jour pour utiliser <TARGET_NAME>. Vous voulez que je les mette à jour maintenant ? »

Step 3: Confirm the Rule

Montrez à l'utilisateur la règle prévue et confirmez avant de créer :

« Je vais créer une règle de remappage de service nommée <RULE_NAME> avec le filtre <FILTER> qui mappe <ORIGINAL_SERVICE> → <TARGET_NAME> (rule_type: <TYPE>). Prêt à procéder ? »

Attendez la confirmation avant de continuer.

Step 4: Create the Rule

Claude runs

pup apm service-remapping create \
  --name "<RULE_NAME>" \
  --filter "<FILTER>" \
  --rule-type <TYPE> \
  --value "<TARGET_NAME>"

Si la réponse contient un champ id — la création a réussi. Enregistrez les valeurs id et version de la réponse.

ERROR: 400 Bad Request avec « Filter expression has invalid syntax » — la requête de filtre est mal formée. Vérifiez la syntaxe glob et les opérateurs booléens.

ERROR: 400 Bad Request avec « Template value in target name is invalid » — la regex value est invalide. Vérifiez : max 1 groupe de capture, quantificateurs non-gourmands dans les groupes ((.+?) pas (.+)).

ERROR: 401 Unauthorized — les credentials sont invalides ou expirés. Révérifiez DD_API_KEY et DD_APP_KEY.

ERROR: 403 Forbidden — la clé API manque la permission apm_service_renaming_write.

Step 5: Verify

Attendez 2–5 minutes pour que la règle se propage, puis confirmez qu'elle est active.

For SERVICE rules (rule_type 0)

Claude runs

# Confirmez que le nouveau nom de service apparaît dans APM
pup apm services list --env <ENV> --from 5m

# Confirmez que les traces arrivent sous le nouveau nom
pup traces search --query "service:<TARGET_NAME>" --from 5m --limit 5

Si <TARGET_NAME> apparaît dans l'un ou l'autre — la règle est active.

For INFERRED_ENTITY rules (rule_type 1)

Les entités inférées ne produisent pas leurs propres spans, elles n'apparaîtront donc pas dans pup apm services list ou pup traces search. Vérifiez en deux étapes :

Step 5a — confirmez que la règle est stockée correctement :

Claude runs

pup apm service-remapping get <RULE_ID>

Confirmez que le filtre et la valeur correspondent à ce que vous aviez l'intention.

Step 5b — confirmez que le nom de l'entité a changé sur la carte de service :

Demandez à l'utilisateur de vérifier la Carte de service APM dans l'interface utilisateur Datadog et de chercher <TARGET_NAME> où <ORIGINAL_SERVICE> apparaissait avant. La carte de service est la vue autoritaire pour les noms d'entité inférée.

Sinon, confirmez que les nouvelles valeurs peer.service arrivent sur les spans du service instrumenté :

Claude runs

pup traces search --query "service:<INSTRUMENTED_SERVICE> @peer.service:<TARGET_NAME>" --from 5m --limit 5

Si les spans apparaissent avec peer.service:<TARGET_NAME> — la règle est active.

ERROR: Le nouveau nom n'apparaît pas après 5 minutes :

• Confirmez que l'ancien service envoie toujours des traces avec le peer.service d'origine : pup traces search --query "@peer.service:<ORIGINAL_SERVICE>" --from 5m
• Si l'ancien nom apparaît toujours, la propagation peut encore être en cours — attendez 2 minutes de plus et réessayez
• Si aucun nom n'apparaît, confirmez que DD_TRACE_PEER_SERVICE_DEFAULTS_ENABLED=true est défini sur le service instrumenté — sans cela peer.service n'est jamais défini et la règle ne sera jamais déclenchée

Managing Existing Rules

List all rules

Claude runs

pup apm service-remapping list

Get a single rule

Claude runs

pup apm service-remapping get <RULE_ID>

Update a rule

La mise à jour nécessite la version actuelle de la sortie list/get. Montrez les modifications proposées à l'utilisateur et confirmez avant d'exécuter :

Claude runs

pup apm service-remapping update <RULE_ID> \
  --name "<RULE_NAME>" \
  --filter "<FILTER>" \
  --rule-type <TYPE> \
  --value "<NEW_NAME>" \
  --version <VERSION>

ERROR: 409 Conflict — la règle a été modifiée depuis que vous l'avez récupérée. Refetchez avec get pour obtenir la version actuelle et réessayez.

Delete a rule

Montrez d'abord à l'utilisateur le nom et le filtre de la règle, puis demandez une confirmation. La suppression nécessite l'id et la version de la règle de la sortie list/get :

Claude runs

pup apm service-remapping delete <RULE_ID> <RULE_VERSION>

ERROR: 409 Conflict — la règle a été modifiée depuis que vous l'avez récupérée. Refetchez avec get pour obtenir la version actuelle et réessayez.

Done

Quittez quand TOUS les éléments suivants sont vrais :

• [ ] Règle affichée à l'utilisateur et confirmée avant création
• [ ] Règle créée et id retourné dans la réponse
• [ ] Nouveau nom de service visible dans pup apm services list
• [ ] Moniteurs affectés identifiés et offerts pour mise à jour
• [ ] Utilisateur confirmé que le remappage correspond à son intention

Security constraints

• Ne jamais écrire une clé API brute dans un fichier ou message de chat — toujours utiliser $DD_API_KEY et $DD_APP_KEY
• Ne jamais créer ou supprimer une règle sans confirmation explicite de l'utilisateur — afficher la règle complète avant création
• Ne jamais supposer prod comme environnement — toujours confirmer avec l'utilisateur
• Ne jamais exécuter DELETE sans afficher d'abord à l'utilisateur le nom et le filtre de la règle
• Ne jamais activer enabled_org_wide sans confirmation explicite de l'utilisateur — cela affecte l'organisation entière