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

# 使用 OpenTelemetry 傳送指標
<a name="metrics-otel-send"></a>

您可以使用 OpenTelemetry Protocol (OTLP) 將自訂指標發佈至 CloudWatch。您可以使用 OTel SDKs(Java、Python、Go、.NET、Node.js)、OTel Collector 或任何與 OTLP 相容的用戶端。

## CloudWatch OTLP 端點
<a name="metrics-otel-send-endpoint"></a>

將指標傳送至您區域中的 CloudWatch OTLP 端點：

```
https://monitoring.{{region}}.amazonaws.com/v1/metrics
```

身分驗證使用 standard AWS SigV4 簽署。服務名稱為 `monitoring`。如需端點、身分驗證選項和限制的詳細資訊，請參閱 [OTLP 端點](CloudWatch-OTLPEndpoint.md)。

## 快速入門：發佈您的第一個指標
<a name="metrics-otel-send-quickstart"></a>

### 選項 1：OTel 收集器 （建議用於生產）
<a name="metrics-otel-send-collector"></a>

使用 OTLP HTTP 匯出器和 SigV4 身分驗證設定 OTel 收集器：

```
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:
    send_batch_size: 200
    timeout: 10s

exporters:
  otlphttp:
    tls:
      insecure: false
    metrics_endpoint: "https://monitoring.{{us-east-1}}.amazonaws.com/v1/metrics"
    auth:
      authenticator: sigv4auth

extensions:
  sigv4auth:
    service: "monitoring"
    region: "{{us-east-1}}"

service:
  extensions: [sigv4auth]
  pipelines:
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp]
```

如需詳細的設定說明，請參閱 [開始使用](CloudWatch-OTLPGettingStarted.md)。

### 選項 2：OTel SDK (Python 範例）
<a name="metrics-otel-send-python"></a>

```
from opentelemetry import metrics
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
from opentelemetry.exporter.otlp.proto.http.metric_exporter import OTLPMetricExporter

# Point at the CloudWatch OTLP endpoint
exporter = OTLPMetricExporter(
    endpoint="https://monitoring.{{us-east-1}}.amazonaws.com:443/v1/metrics"
)
reader = PeriodicExportingMetricReader(exporter, export_interval_millis=60000)
provider = MeterProvider(metric_readers=[reader])
metrics.set_meter_provider(provider)

# Create and record a metric
meter = metrics.get_meter("my-app")
counter = meter.create_counter("http_requests_total", description="Total HTTP requests")
counter.add(1, {"method": "GET", "path": "/api/users", "status": "200"})
```

### 選項 3：OTel SDK (Java 範例）
<a name="metrics-otel-send-java"></a>

```
import io.opentelemetry.api.metrics.Meter;
import io.opentelemetry.api.metrics.LongCounter;

Meter meter = GlobalOpenTelemetry.getMeter("my-app");
LongCounter counter = meter.counterBuilder("http_requests_total")
    .setDescription("Total HTTP requests")
    .build();

counter.add(1, Attributes.of(
    AttributeKey.stringKey("method"), "GET",
    AttributeKey.stringKey("path"), "/api/users",
    AttributeKey.stringKey("status"), "200"
));
```

## 所需的 IAM 許可
<a name="metrics-otel-send-iam"></a>

身分傳送指標需要 `cloudwatch:PutMetricData`許可。對於 SigV4 身分驗證，請連接下列政策：

```
{
  "Effect": "Allow",
  "Action": [
    "cloudwatch:PutMetricData"
  ],
  "Resource": "*"
}
```

如需承載字符身分驗證，請參閱 [設定指標的承載字符身分驗證](CloudWatch-OTLP-MetricsBearerTokenAuth.md)。

## 驗證指標是否到達
<a name="metrics-otel-send-verify"></a>

開啟 CloudWatch 主控台，導覽至 **Query Studio**，然後執行：

```
http_requests_total
```

指標通常會在傳送第一個資料點的 1-2 分鐘內顯示。

## 支援的指標類型
<a name="metrics-otel-send-types"></a>

下表說明 CloudWatch 支援的 OTel 指標類型，以及如何使用 PromQL 查詢它們。


| OTel 指標類型 | PromQL 行為 | 
| --- | --- | 
| 計數器 | 使用 rate()或 increase() 查詢 | 
| 量測計 | 直接查詢 （目前值） | 
| 直方圖 | histogram\_quantile() 用於百分位數 | 

## 最佳實務
<a name="metrics-otel-send-best-practices"></a>

透過 OTLP 傳送指標時，請遵循下列建議：
+ **使用有意義的指標名稱** — 遵循 OTel 命名慣例 （例如 `http.server.request.duration`或 `http_request_duration_seconds`)。
+ **保持標籤基數合理** - 避免將請求 IDs或 UUIDs作為標籤值。
+ **設定適當的匯出間隔** — 標準為 60 秒。較短的間隔會增加成本。
+ **使用資源屬性** — 使用靜態中繼資料 （服務名稱、版本、環境） 的資源屬性，而非per-data-point標籤。