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

# 使用 Application Signals 自訂指標
<a name="AppSignals-CustomMetrics"></a>

為監控應用程式效能和可見性，Application Signals 會在您啟用發現的應用程式之後，從應用程式收集標準指標 (故障、錯誤和延遲) 和執行時期指標。

自訂指標可為應用程式監控新增重要內容，協助加速疑難排解。您可以使用它們來：
+ 自訂遙測資料的分析
+  識別問題發生的根本原因
+ 迅速做出精確的業務和營運決策

藉助 Application Signals，您可以檢視來自服務的自訂指標，並將其與標準指標和執行時期指標建立關聯。例如，應用程式可能發出請求大小和快取遺漏計數指標。這些自訂指標可協助更細緻地了解效能問題，更快地診斷並解決可用性下降與延遲飆升的問題。

**Topics**
+ [設定 Application Signals 的自訂指標](#AppSignals-CustomMetrics-Adding)
+ [在 Application Signals 中檢視自訂指標](#AppSignals-CustomMetrics-Viewing)
+ [常見問答集 (FAQ)](#AppSignals-CustomMetrics-FAQ)

## 設定 Application Signals 的自訂指標
<a name="AppSignals-CustomMetrics-Adding"></a>

可以透過兩種方法從應用程式產生自訂指標：*OpenTelemetry 指標*和*範圍指標*。

**Topics**
+ [OpenTelemetry 指標](#AppSignals-CustomMetrics-OpenTelemetry)
+ [範圍指標](#AppSignals-CustomMetrics-SpanMetrics)

### OpenTelemetry 指標
<a name="AppSignals-CustomMetrics-OpenTelemetry"></a>

若要搭配 Application Signals 使用自訂 OpenTelemetry 指標，必須使用 CloudWatch 代理程式或 OpenTelemetry Collector。透過自訂 OpenTelemetry 指標，您可以使用 OpenTelemetry 指標 SDK 直接從應用程式程式碼建立和匯出指標。

1. 加入服務至 Application Signals。

1. 設定代理程式或收集器。
   + 使用 CloudWatch 代理程式時，必須使用 `otlp` [設定](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-OpenTelemetry-metrics.html) `metrics_collected`。例如 `cloudwatch-config.json`

     ```
     {
       "traces": {
         "traces_collected": {
           "application_signals": {}
         }
       },
       "logs": {
         "metrics_collected": {
           "application_signals": {},
           "otlp": {
             "grpc_endpoint": "0.0.0.0:4317",
             "http_endpoint": "0.0.0.0:4318"
           }
         }
       }
     }
     ```
   + 使用 OpenTelemetry Collector 時，請設定指標管道。必須使用[適用於 OpenTelemetry Collector 的 CloudWatch EMF Exporter](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/awsemfexporter)，並啟用[指標標籤的資源屬性](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/awsemfexporter#resource-attributes-to-metric-labels)。建議設定 ` dimension_rollup_option: NoDimensionRollup` 以避免發出過多指標彙總。例如 `config.yaml`：

     ```
     receivers:
       otlp:
         protocols:
           grpc:
             endpoint: 0.0.0.0:4317
           http:
             endpoint: 0.0.0.0:4318
     
     exporters:
       awsemf:
         region: $REGION
         namespace: $NAMESPACE
         log_group_name:$LOG_GROUP_NAME
         resource_to_telemetry_conversion:
           enabled: true
         dimension_rollup_option: "NoDimensionRollup"
         
       otlphttp/traces:
         compression: gzip
         traces_endpoint: https://xray.$REGION.amazonaws.com/v1/traces
         auth:
           authenticator: sigv4auth/traces
     
     extensions:
       sigv4auth/logs:
         region: "$REGION"
         service: "logs"
       sigv4auth/traces:
         region: "$REGION"
         service: "xray"
     
     processors:
       batch:
     
     service:
       telemetry:
       extensions: [sigv4auth/logs, sigv4auth/traces]
       pipelines:
         metrics:
           receivers: [otlp]
           processors: [batch]
           exporters: [awsemf]
         traces:
           receivers: [otlp]
           processors: [batch]
           exporters: [otlphttp/traces]
     ```

1. 設定環境。當有多個服務同名，並且要準確將 Application Signals 指標與正確的服務名稱關聯時，建議設定資源屬性 `deployment.environment.name`。設定此資源屬性通常透過環境變數完成。

   ```
   OTEL_RESOURCE_ATTRIBUTES="service.name=$YOUR_SVC_NAME,deployment.environment.name=$YOUR_ENV_NAME"
   ```

1. 設定指標匯出至 CloudWatch 代理程式或 OpenTelemetry Collector。可以使用下列選項之一：
   + (建議) 自訂匯出管道 – 在應用程式程式碼中，建立專用 [MeterProvider](https://opentelemetry.io/docs/specs/otel/metrics/sdk/#meterprovider) 匯出至設定的代理程式或收集器端點。例如：

     ```
     Resource resource = Resource.getDefault().toBuilder()
             .put(AttributeKey.stringKey("service.name"), serviceName)
             .put(AttributeKey.stringKey("deployment.environment.name"), environment)
             .build();
     
     MetricExporter metricExporter = OtlpHttpMetricExporter.builder()
             .setEndpoint("http://localhost:4318/v1/metrics")
             .build();
     
     MetricReader metricReader = PeriodicMetricReader.builder(metricExporter)
             .setInterval(Duration.ofSeconds(10))
             .build()
     
     SdkMeterProvider meterProvider = SdkMeterProvider.builder()
         .setResource(resource)
         .registerMetricReader()
         .build();
         
     Meter meter = meterProvider.get("myMeter");
     ```
   + 代理程式型匯出 – 設定代理程式環境變數 [OTEL\$1METRICS\$1EXPORTER](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#exporter-selection) 和 [OTEL\$1EXPORTER\$1OTLP\$1METRICS\$1ENDPOINT](https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/#otel_exporter_otlp_metrics_endpoint)。例如：

     ```
     OTEL_METRICS_EXPORTER=otlp
     OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://localhost:4318/v1/metrics
     ```

     在應用程式程式碼中，依賴代理程式建立的全域 MeterProvider。例如：

     ```
     Meter meter = GlobalOpenTelemetry.getMeter("myMeter");
     ```

1. 使用應用程式程式碼中的 [OTEL 指標 SDK](https://opentelemetry.io/docs/specs/otel/metrics/sdk/)，新增 OTEL 指標。例如，若要在 Python 中新增 OTEL 指標：

   ```
   counter = meter.counterBuilder("myCounter").build();
   counter.add(value);
   counter.add(value, Attributes.of(AttributeKey.stringKey("Operation"), "myOperation"));
   ```

   新增操作屬性並非必要，但有助於將 Application Signals 服務操作關聯至自訂 OpenTelemetry 指標。

### 範圍指標
<a name="AppSignals-CustomMetrics-SpanMetrics"></a>

自訂範圍指標目前僅適用於 Transaction Search。使用自訂範圍指標，您可以：
+ 使用指標篩選條件建立指標
+ 處理在應用程式程式碼中新增的範圍屬性
+ 使用 OpenTelemetry 追蹤 SDK 進行實作

1. 使用 Transaction Search 啟用 Application Signals 監控。如需詳細資訊，請參閱 [Transaction Search](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Transaction-Search-getting-started.html)。

   為確保 100% 指標取樣，建議將 100% 的範圍傳送至端點。

1. 使用 [OTEL 追蹤 SDK](https://opentelemetry.io/docs/specs/otel/trace/sdk/) 新增範圍屬性。有兩種方式：
   + [建議] 新增屬性至自動產生的範圍。例如：

     ```
     Span.current().setAttribute("myattribute", value);
     ```
   + 將屬性新增至手動產生的範圍。例如：

     ```
     Span span = tracer.spanBuilder("myspan").startSpan();
     try (Scope scope = span.makeCurrent()) {
        span.setAttribute("myattribute",  value);
     }
     ```

1. 使用下列值建立指標篩選條件。如需如何建立指標篩選條件的資訊，請參閱[為日誌群組建立指標篩選條件](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CreateMetricFilterProcedure.html)。
   + 日誌群組 – aws/spans
   + 篩選模式 – \$1 \$1.attributes.['myattribute'] = \$1 \$1
   + 指標名稱 – myattribute (The values must be an exact match or span correlation will not work
   + 指標值 – \$1.attributes.['myattribute']
   + 維度 – Field Name: Service, Field Value: \$1.attributes.['aws.local.service'], Field Name: Environment, Field Value: \$1.attributes.['aws.local.environment'], and Field Name: Operation, Field Value: \$1.attributes.['aws.local.operation']
**注意**  
當您將屬性新增至手動產生的範圍時，無法設定 `Operation`，因為 `aws.local.operation` 不會出現在範圍資料中。

## 在 Application Signals 中檢視自訂指標
<a name="AppSignals-CustomMetrics-Viewing"></a>

現在可以在 Application Signals 主控台中檢視服務和操作的自訂指標：
+ 從**服務**清單中選擇服務，以檢視新的**相關指標**索引標籤
+  檢視所選服務的標準指標、執行時期指標和相關指標
+ 從清單中篩選並選取多個指標
+ 繪製選定指標的圖表，以識別相關性並找出問題的根本原因

如需相關指標的詳細資訊，請參閱 [檢視相關指標](ServiceDetail.md#ServiceDetail-relatedmetrics)。

## 常見問答集 (FAQ)
<a name="AppSignals-CustomMetrics-FAQ"></a>

### 不為自訂指標的環境新增組態會有何影響？
<a name="AppSignals-CustomMetrics-FAQ-Environment"></a>

Application Signals 會設定 `deployment.environment.name` 資源屬性，以消除應用程式的歧義。Application Signals 無法在未經消歧處理的情況下，將來自兩個不同服務但同名的自訂指標，正確關聯至對應的服務。

若要將環境組態新增至您的應用程式，請參閱 [OpenTelemetry 指標](#AppSignals-CustomMetrics-OpenTelemetry)。

### 指標篩選條件是否有任何限制？
<a name="AppSignals-CustomMetrics-FAQ-Limits"></a>

每個 CloudWatch Logs 日誌群組最多只能建立 100 個指標篩選條件。每個指標最多可以定義 3 個維度。可以在此檢視指標篩選條件的限制 [OpenTelemetry 指標](#AppSignals-CustomMetrics-OpenTelemetry)。

### 為何指標圖表未顯示於指標資料表中？
<a name="AppSignals-CustomMetrics-FAQ-Graph"></a>

解決方案取決於您的指標類型：
+ 自訂指標 – 請參閱 [設定 Application Signals 的自訂指標](#AppSignals-CustomMetrics-Adding) 以驗證指標組態
+ 標準或執行時期指標 – 請參閱[Application Signals 安裝疑難排解](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals-Enable-Troubleshoot.html)