Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Configurer la visibilité des points de terminaison HTTP

Cette page fournit des conseils aux clients d'Application Signals qui s'attendent à voir leurs opérations de service HTTP séparées par des noms de points de terminaison spécifiques, mais qui souhaitent voir plusieurs points de terminaison regroupés dans la même métrique. Par défaut, Application Signals tronque la dimension Operation métrique au premier segment de chemin d'URL pour les services HTTP (par exemple, /api/v1/users becomesGET /api) afin de préserver les métriques à faible cardinalité. Par conséquent, les utilisateurs peuvent constater que les services comportant plusieurs terminaux partageant le même préfixe ont une visibilité limitée sur l'état de fonctionnement de chaque point de terminaison. Vous pouvez suivre les étapes ci-dessous pour configurer les points de terminaison des opérations de service selon la granularité souhaitée.

AWS Distro pour la solution OpenTelemetry (ADOT)

Pour les clients qui utilisent AWS Distro for OpenTelemetry (ADOT), définissez la variable d'OTEL_AWS_HTTP_OPERATION_PATHSenvironnement avec une liste de modèles de chemin d'URL séparés par des virgules pour le service HTTP :

export OTEL_AWS_HTTP_OPERATION_PATHS="/path/to/endpoint, /another/{placeholder}/endpoint"

Cette variable utilise le plus long préfixe correspondant à l'url.pathattribut de l'étendue du serveur HTTP pour déterminer le nom de l'opération. Les caractères génériques correspondent à n'importe quel segment d'URL et peuvent être désignés par {placeholder}:placeholder, ou. * Après avoir défini la variable, redémarrez votre application pour que les nouveaux regroupements de terminaux prennent effet.

Cette variable est prise en charge dans ADOT pour Java Node.js, Python et .NET.

Exemple

Prenons l'exemple d'un service d'API qui reçoit le trafic suivant :

GET  /api/users
GET  /api/users/42
GET  /api/users/42/orders
POST /api/users/99/orders
POST /api/users/42/orders
GET  /api/users/42/orders/7/items
GET  /api/products

Par défaut, Application Signals regroupe tous ces éléments dans GET /api des mesures de POST /api service, ce qui rend impossible de distinguer les performances entre les terminaux.

Pour résoudre ce problème, définissez la variable d'environnement avec les modèles de chemin souhaités :

export OTEL_AWS_HTTP_OPERATION_PATHS="/api/users/{userId}/orders/{orderId}/items, /api/users/{userId}/orders, /api/users/{userId}, /api/users, /api/products"

Avec cette configuration, Application Signals affiche des opérations distinctes. Plusieurs demandes peuvent être résolues vers le même modèle configuré :

OpenTelemetry Solution native

Si vous utilisez le OpenTelemetry SDK natif (sans ADOT), vous pouvez soit remplacer le nom du span à l'aide du processeur de transformation de votre OpenTelemetry Collector, soit directement dans le code de l'application.

Option 1 (recommandée) : Collector-side transformation

Utilisez le processeur de transformation pour définir des noms de span en fonction de modèles d'URL. Le processeur de transformation utilise le langage OTTL (OpenTelemetry Transformation Language) et peut modifier directement le name champ de span.

Classez les règles de la plus superficielle à la plus profonde : les instructions s'exécutent de manière séquentielle, de sorte que les correspondances plus spécifiques situées plus loin dans la liste remplacent les correspondances générales définies plus tôt. Dans l'exemple suivant, la valeur de l'attribut span url.path est mise en correspondance et le nom de span qui en résulte est défini selon la méthode de demande suivie du modèle d'URL souhaité.

processors:
  transform/operation_names:
    trace_statements:
      - context: span
        conditions:
          - IsMatch(attributes["url.path"], "^/api/contests(/|$)")
        statements:
          - set(name, Concat([attributes["http.request.method"], "/api/contests"], " "))

      - context: span
        conditions:
          - IsMatch(attributes["url.path"], "^/api/contests/[^/]+$")
        statements:
          - set(name, Concat([attributes["http.request.method"], "/api/contests/{id}"], " "))

      - context: span
        conditions:
          - IsMatch(attributes["url.path"], "^/api/contests/[^/]+/leaderboard(/|$)")
        statements:
          - set(name, Concat([attributes["http.request.method"], "/api/contests/{id}/leaderboard"], " "))

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [resourcedetection, transform/operation_names, batch]
      exporters: [otlphttp/xray]

Option 2 : définir le nom du span dans le code de l'application

Vous pouvez définir manuellement le nom des étendues de serveurs dans le code de votre application à l'aide de l' OpenTelemetry API. Définissez le nom de l'{HTTP_METHOD} {route_template}endroit où le modèle d'itinéraire utilise des espaces réservés paramétrés. Notez qu'il s'agit d'une option de secours codée en dur et que vous devez mettre à jour manuellement le nom du span dans chaque gestionnaire de requêtes HTTP pour appliquer cette modification.

Java

import io.opentelemetry.api.trace.Span;

// Inside your request handler
Span.current().updateName("GET /api/contests/{id}/leaderboard");

Python

from opentelemetry import trace

# Inside your request handler
span = trace.get_current_span()
span.update_name("GET /api/contests/{id}/leaderboard")

Go

import "go.opentelemetry.io/otel/trace"

// Inside your request handler
span := trace.SpanFromContext(ctx)
span.SetName("GET /api/contests/{id}/leaderboard")

Node.js

import { trace } from '@opentelemetry/api';

// Inside your request handler
const span = trace.getActiveSpan();
if (span) {
  span.updateName('GET /api/contests/{id}/leaderboard');
}