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

# 新增自訂屬性
<a name="CloudWatch-Transaction-Search-add-custom-attributes"></a>

 CloudWatch Application Signals 利用 OpenTelemetry 自動檢測您的應用程式，並從 Java、Python 等不同語言的熱門程式庫收集範圍。

 自動檢測會擷取資訊，例如資料庫查詢、HTTP 請求、快取存取和外部服務呼叫，以協助您排解應用程式效能問題。

 可以新增自訂檢測，以使用業務特定資料或您想要擷取的其他資訊來擴大範圍。此資料可記錄為自訂屬性或範圍事件，提供針對您的疑難排解需求量身打造的洞察。

**注意**  
 如需以不同語言新增自訂屬性或範圍事件的資訊，請參閱 *OpenTelemetry 網站*中的[語言 API 和 SDKS](https://opentelemetry.io/docs/languages/)。

## 自訂屬性
<a name="w2aac28c21c19c11"></a>

 可以透過所有語言 OpenTelemetry 支援，將業務相關屬性或任何其他屬性新增至您的範圍。以下是 Java 程式碼片段，可將訂單 ID 和客戶詳細資訊新增至範圍。

```
import io.opentelemetry.api.trace.Span;

public class OrderProcessor {

    public void processOrder() {
        Span span = Span.current();
        span.setAttribute("order.id", "123456");
        span.setAttribute("customer.name", "John Doe");
        span.setAttribute("customer.id", "4343dfdd");

        // Your order processing logic here
        System.out.println("Order processed with custom attributes");
    }
}
```

 這些屬性新增至範圍後，即可在 [Transaction Search 視覺化編輯器](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Transaction-Search-search-analyze-spans.html)中進行搜尋和分析。

## 範圍事件
<a name="w2aac28c21c19c13"></a>

 範圍事件通常用於標示持續時間範圍內一個有意義的單獨時間點。例外情況會透過自動檢測功能自動擷取為範圍事件，您也可以新增自訂業務事件，例如付款狀態或購物車放棄。如需詳細資訊，請參閱 OpenTelemetry 網站上的[範圍事件](https://opentelemetry.io/docs/concepts/signals/traces/#span-events)。

 可以使用 CloudWatch Application Signals 和 OpenTelemetry 支援的所有語言，將範圍事件嵌入您的範圍。以下是將自訂事件新增至範圍的 Java 程式碼片段。

```
import io.opentelemetry.api.trace.Span;

public class OrderProcessor {

    public void bookOrder() {
        Span span = Span.current();

        // Add a booking started event
        span.addEvent("booking started");
        
        // Add a payment succeeded event or failed event 
        span.addEvent("booking failed");
    }
}
```

### CloudWatch 代理程式的先決條件
<a name="w2aac28c21c19c13b9"></a>

 使用 CloudWatch 代理程式向 X-Ray 發送範圍事件時，必須在組態中開啟 ``transit_spans_in_otlp_format`` 旗標。

```
{
  "traces": {
    ...
    "transit_spans_in_otlp_format": true
    ...
  }
}
```

 新增這些事件後，它們將在 [Transaction Search 視覺化編輯器](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Transaction-Search-search-analyze-spans.html)中變為可用。

## CloudWatch Logs 查詢
<a name="w2aac28c21c19c15"></a>

 可以在 CloudWatch Logs 中查詢範圍事件，以檢視進階洞察。下列查詢命令範例示範如何分析應用程式拋出的例外狀況：

```
fields jsonparse(@message) as js
| unnest js.events into event 
| filter event.name = "exception"
| display event.attributes.`exception.stacktrace`
```

```
fields jsonparse(@message) as js
| unnest js.events into event 
| filter event.name = "exception"
| stats count() by event.attributes.`exception.type`
```