本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

設定 HTTP 端點可見性

此頁面提供 Application Signals 客戶指引，這些客戶希望看到其 HTTP 服務操作以特定端點名稱分隔，但改為看到多個端點分組為相同的指標。根據預設，Application Signals 會將指標維度截斷為 HTTP Operation 服務的第一個 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或 表示*。設定變數之後，請重新啟動應用程式，讓新的端點群組生效。

ADOT for Java、Python、Node.js 和 .NET 支援此變數。

範例

請考慮接收下列流量的 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 轉換語言），可以直接修改跨度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');
}