# HTTP 엔드포인트 가시성 구성
<a name="Application-Signals-EndpointVisibility"></a>

이 페이지에서는 HTTP 서비스 작업을 특정 엔드포인트 이름으로 구분하여 볼 수 있지만 대신 동일한 지표로 그룹화된 여러 엔드포인트를 볼 수 있는 Application Signals 고객을 위한 지침을 제공합니다. 기본적으로 Application Signals는 지표 `Operation` 차원을 HTTP 서비스의 첫 번째 URL 경로 세그먼트로 잘라내어(예:가 `/api/v1/users`가 `GET /api`가 됨) 낮은 카디널리티 지표를 유지합니다. 따라서 사용자는 동일한 접두사를 공유하는 여러 엔드포인트가 있는 서비스가 개별 엔드포인트의 운영 상태를 제한적으로 파악한다는 점을 알게 될 수 있습니다. 아래 단계에 따라 원하는 세부 수준으로 서비스 작업 엔드포인트를 구성할 수 있습니다.

**중요**  
엔드포인트 가시성 수정은 서비스 작업에 대한 Application Signals 지표 차원에 영향을 미치므로 중요한 변경 사항입니다. 이에 따라 SLO 임계값, 경보 및/또는 대시보드를 업데이트해야 합니다.

## AWS Distro for OpenTelemetry(ADOT) 솔루션
<a name="Application-Signals-EndpointVisibility-ADOT"></a>

AWS Distro for OpenTelemetry(ADOT)를 사용하는 고객의 경우 HTTP 서비스에 대한 URL 경로 템플릿 목록을 쉼표로 구분하여 `OTEL_AWS_HTTP_OPERATION_PATHS` 환경 변수를 설정합니다.

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

이 변수는 HTTP 서버 스팬의 `url.path` 속성과 가장 긴 일치 접두사를 사용하여 작업 이름을 결정합니다. 와일드카드 패턴은 단일 URL 세그먼트와 일치하며 `{placeholder}`, `:placeholder` 또는 `*`로 표시할 수 있습니다. 변수를 설정한 후 새 엔드포인트 그룹이 적용되도록 애플리케이션을 다시 시작합니다.

이 변수는 Java, Python, Node.js 및 .NET용 ADOT에서 지원됩니다.

**예제**

다음 트래픽을 수신하는 API 서비스를 생각해 보세요.

```
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
```

기본적으로 Application Signals는 이러한 모든 지표를 `GET /api` 또는 `POST /api` 서비스 지표로 그룹화하므로 엔드포인트 간에 성능을 구별할 수 없습니다.

이 문제를 해결하려면 환경 변수를 원하는 경로 템플릿으로 설정합니다.

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

이 구성을 사용하면 Application Signals에 고유한 작업이 표시됩니다. 여러 요청이 구성된 동일한 템플릿으로 확인될 수 있습니다.


**엔드포인트 가시성 구성 결과의 예**  

| 수신 요청 | 기본 작업 | 구성 사용 | 
| --- | --- | --- | 
| 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 | 

## 네이티브 OpenTelemetry 솔루션
<a name="Application-Signals-EndpointVisibility-NativeOTel"></a>

네이티브 OpenTelemetry SDK(ADOT 제외)를 사용하는 경우 OpenTelemetry Collector의 변환 프로세서를 사용하거나 애플리케이션 코드에서 직접 스팬 이름을 재정의할 수 있습니다.

**참고**  
CloudWatch가 Application Signals 작업 이름에 대해 구문 분석할 수 있게 OpenTelemetry 스팬 이름을 유지하도록 OTLP 내보내기로 수집기를 구성해야 합니다. 자세한 내용은 [CloudWatch로 OTLP 데이터 전송](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-OTLPSimplesetup.html) 섹션을 참조하세요.

**옵션 1(권장): 수집기 측 변환**

[변환 프로세서](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/transformprocessor)를 사용하여 URL 패턴을 기반으로 스팬 이름을 설정합니다. 변환 프로세서는 OTTL(OpenTelemetry Transformation Language)을 사용하며 스팬 `name` 필드를 직접 수정할 수 있습니다.

가장 얕은 규칙부터 가장 깊은 규칙으로 규칙 순서 지정 - 문은 순차적으로 실행되므로 목록의 뒷부분에 있는 보다 구체적인 일치 항목이 앞서 설정한 일반 일치 항목보다 우선합니다. 다음 예제에서는 스팬 속성 `url.path`의 값이 일치하고 결과 스팬 이름이 요청 메서드로 설정된 후 원하는 URL 패턴으로 설정됩니다.

```
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]
```

**옵션 2: 애플리케이션 코드에서 스팬 이름 설정**

OpenTelemetry API를 사용하여 애플리케이션 코드에서 서버 스팬의 스팬 이름을 수동으로 설정할 수 있습니다. 라우팅 템플릿이 파라미터화된 자리 표시자를 사용하는 `{HTTP_METHOD} {route_template}`로 이름을 설정합니다. 이 옵션은 하드 코딩된 대체 옵션이며, 이 변경 사항을 적용하려면 각 HTTP 요청 핸들러에서 스팬 이름을 수동으로 업데이트해야 합니다.

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