# Configurar a visibilidade do endpoint HTTP
<a name="Application-Signals-EndpointVisibility"></a>

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.

**Importante**  
Modificar a visibilidade do endpoint é uma mudança importante, pois afeta as dimensões métricas do Application Signals para operações de serviço. Lembre-se de atualizar seus limites de SLO, alarmes e/ou painéis adequadamente.

## Solução do AWS Distro para OpenTelemetry (ADOT)
<a name="Application-Signals-EndpointVisibility-ADOT"></a>

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:


**Exemplo de resultados da configuração de visibilidade do endpoint**  

| Solicitação de entrada | Operação padrão | Com config | 
| --- | --- | --- | 
| GET /api/users | GET /api | GET /api/users | 
| GET /api/users/42 | GET /api | GET /api/users/{userId} | 
| GET /api/users/42/orders | GET /api | GET /api/users/{userId}/orders | 
| POST /api/users/99/orders | POST /api | POST /api/users/{userId}/orders | 
| POST /api/users/42/orders | POST /api | POST /api/users/{userId}/orders | 
| GET /api/users/42/orders/7/items | GET /api | GET /api/users/{userId}/orders/{orderId}/items | 
| GET /api/products | GET /api | GET /api/products | 

## Solução do OpenTelemetry nativo
<a name="Application-Signals-EndpointVisibility-NativeOTel"></a>

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.

**nota**  
Você deve configurar seu coletor com um exportador OTLP para preservar o nome do intervalo OpenTelemetry para que o CloudWatch possa analisá-lo para o nome da operação do Application Signals. Para obter mais informações, consulte [Como enviar dados OTLP para o CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-OTLPSimplesetup.html).

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

Use o [processador de transformação](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/transformprocessor) 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');
}
```