HTTP 엔드포인트 가시성 구성

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

AWS Distro for OpenTelemetry(ADOT) 솔루션

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에 고유한 작업이 표시됩니다. 여러 요청이 구성된 동일한 템플릿으로 확인될 수 있습니다.

네이티브 OpenTelemetry 솔루션

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

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

변환 프로세서를 사용하여 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');
}