Configurar a visibilidade do endpoint HTTP

Esta página fornece orientação para clientes do Application Signals que esperam ver suas operações de serviço HTTP separadas por nomes de endpoints específicos, mas, em vez disso, veem vários endpoints agrupados na mesma métrica. Por padrão, o Application Signals trunca a dimensão métrica Operation para o primeiro segmento de caminho de URL para serviços HTTP (por exemplo, /api/v1/users torna-se GET /api) para preservar métricas de baixa cardinalidade. Como resultado, os usuários podem descobrir que serviços com vários endpoints compartilhando o mesmo prefixo têm visibilidade limitada da integridade operacional de endpoints individuais. Você pode seguir as etapas abaixo para configurar os endpoints de operação de serviço de acordo com a granularidade desejada.

Solução do AWS Distro para OpenTelemetry (ADOT)

Para clientes que usam o AWS Distro for OpenTelemetry (ADOT), defina a variável de ambiente OTEL_AWS_HTTP_OPERATION_PATHS com uma lista separada por vírgulas de modelos de caminho de URL para o serviço HTTP:

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

Essa variável usa o prefixo correspondente mais longo no atributo url.path do intervalo do servidor HTTP para determinar o nome da operação. Os padrões curinga correspondem a qualquer segmento de URL e podem ser indicados por {placeholder}, :placeholder ou *. Depois de definir a variável, reinicie sua aplicação para que os novos agrupamentos de endpoints entrem em vigor.

Esta variável é compatível em Java, Python, Node.js e .NET.

Exemplo

Considere um serviço de API que receba o seguinte tráfego:

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

Por padrão, o Application Signals agrupa tudo isso nas métricas de serviço GET /api ou POST /api, tornando impossível distinguir o desempenho entre endpoints.

Para corrigir isso, defina a variável de ambiente com os modelos de caminho desejados:

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

Com essa configuração, o Application Signals mostra operações distintas. Várias solicitações podem ser resolvidas com o mesmo modelo configurado:

Solução do OpenTelemetry nativo

Se você estiver usando o SDK nativo do OpenTelemetry (sem ADOT), poderá substituir o nome do intervalo usando o processador de transformação no seu OpenTelemetry Collector ou diretamente no código da aplicação.

Opção 1 (recomendada): transformação do lado do coletor

Use o processador de transformação para definir nomes de intervalos com base nos padrões de URL. O processador de transformação usa OTTL (OpenTelemetry Transformation Language) e pode modificar o campo span name diretamente.

Ordene as regras da mais superficial para a mais profunda — as instruções são executadas sequencialmente, para que correspondências mais específicas posteriormente na lista substituam as gerais definidas anteriormente. No exemplo apresentado a seguir, o valor do atributo span url.path é correspondido e o nome do intervalo resultante é definido como o método de solicitação seguido pelo padrão de URL desejado.

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]

Opção 2: definir o nome do intervalo no código da aplicação

Você pode definir manualmente o nome do intervalo para os intervalos do servidor no código da sua aplicação usando a API OpenTelemetry. Escolha o nome para {HTTP_METHOD} {route_template} onde o modelo de rota usa espaços reservados parametrizados. Observe que essa é uma opção alternativa codificada e você deve atualizar manualmente o nome do intervalo em cada manipulador de solicitação HTTP para aplicar essa alteração.

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');
}