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

# OpenTelemetry 1.0.0 格式的 CloudWatch 指標串流輸出
<a name="CloudWatch-metric-streams-formats-opentelemetry-100"></a>

**注意**  
使用 OpenTelemetry 1.0.0 格式時，指標屬性會編碼為 `KeyValue` 物件清單，而非 0.7.0 格式中使用的 `StringKeyValue` 類型。作為消費者，這是 0.7.0 和 1.0.0 格式之間唯一的重大變化。從 0.7.0 proto 檔案產生的剖析器不會剖析以 1.0.0 格式編碼的指標屬性。反之亦然，從 1.0.0 proto 檔案產生的剖析器不會剖析以 0.7.0 格式編碼的指標屬性。

OpenTelemetry 是工具、API 和開發套件的集合。您可以使用它來檢測、產生、收集和匯出遙測資料 (指標、日誌和追蹤) 以進行分析。OpenTelemetry 隸屬於雲端原生運算基金會 (Cloud Native Computing Foundation)。如需詳細資訊，請參閱 [OpenTelemetry](https://opentelemetry.io/)。

如需完整的 OpenTelemetry 1.0.0 規格的資訊，請參閱 [1.0.0 發行版](https://github.com/open-telemetry/opentelemetry-proto/releases/tag/v1.0.0)。

Kinesis 記錄可包含一個或多個 `ExportMetricsServiceRequest` OpenTelemetry 資料結構。每個資料結構都以具有 `UnsignedVarInt32` 的標題為開頭，該標題可指示記錄長度 (以位元組為單位)。每個 `ExportMetricsServiceRequest` 可能一次包含來自多個指標的資料。

以下是 `ExportMetricsServiceRequest` OpenTelemetry 資料結構的訊息的字串表示法。OpenRelemetry 會序列化 Google 協定緩衝區二進位協定，且此結果人類不可讀取。

```
resource_metrics {
  resource {
    attributes {
      key: "cloud.provider"
      value {
        string_value: "aws"
      }
    }
    attributes {
      key: "cloud.account.id"
      value {
        string_value: "123456789012"
      }
    }
    attributes {
      key: "cloud.region"
      value {
        string_value: "us-east-1"
      }
    }
    attributes {
      key: "aws.exporter.arn"
      value {
        string_value: "arn:aws:cloudwatch:us-east-1:123456789012:metric-stream/MyMetricStream"
      }
    }
  }
  scope_metrics {
    metrics {
      name: "amazonaws.com/AWS/DynamoDB/ConsumedReadCapacityUnits"
      unit: "NoneTranslated"
      summary {
        data_points {
          start_time_unix_nano: 60000000000
          time_unix_nano: 120000000000
          count: 1
          sum: 1.0
          quantile_values {
            value: 1.0
          }
          quantile_values {
            quantile: 0.95
            value: 1.0
          }
          quantile_values {
            quantile: 0.99
            value: 1.0
          }
          quantile_values {
            quantile: 1.0
            value: 1.0
          }
          attributes {
            key: "Namespace"
            value {
              string_value: "AWS/DynamoDB"
            }
          }
          attributes {
            key: "MetricName"
            value {
              string_value: "ConsumedReadCapacityUnits"
            }
          }
          attributes {
            key: "Dimensions"
            value {
              kvlist_value {
                values {
                  key: "TableName"
                  value {
                    string_value: "MyTable"
                  }
                }
              }
            }
          }
        }
        data_points {
          start_time_unix_nano: 70000000000
          time_unix_nano: 130000000000
          count: 2
          sum: 5.0
          quantile_values {
            value: 2.0
          }
          quantile_values {
            quantile: 1.0
            value: 3.0
          }
          attributes {
            key: "Namespace"
            value {
              string_value: "AWS/DynamoDB"
            }
          }
          attributes {
            key: "MetricName"
            value {
              string_value: "ConsumedReadCapacityUnits"
            }
          }
          attributes {
            key: "Dimensions"
            value {
              kvlist_value {
                values {
                  key: "TableName"
                  value {
                    string_value: "MyTable"
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```

**序列化 OpenTelemetry 指標資料的最上層物件**

`ExportMetricsServiceRequest` 是用於序列化 OpenTelemetry 匯出工具酬載的最上層包裝函式。它包含一個或多個 `ResourceMetrics`。

```
message ExportMetricsServiceRequest {
  // An array of ResourceMetrics.
  // For data coming from a single resource this array will typically contain one
  // element. Intermediary nodes (such as OpenTelemetry Collector) that receive
  // data from multiple origins typically batch the data before forwarding further and
  // in that case this array will contain multiple elements.
  repeated opentelemetry.proto.metrics.v1.ResourceMetrics resource_metrics = 1;
}
```

`ResourceMetrics` 是表示 MetricData 物件的最上層物件。

```
// A collection of ScopeMetrics from a Resource.
message ResourceMetrics {
  reserved 1000;

  // The resource for the metrics in this message.
  // If this field is not set then no resource info is known.
  opentelemetry.proto.resource.v1.Resource resource = 1;

  // A list of metrics that originate from a resource.
  repeated ScopeMetrics scope_metrics = 2;

  // This schema_url applies to the data in the "resource" field. It does not apply
  // to the data in the "scope_metrics" field which have their own schema_url field.
  string schema_url = 3;
}
```

**資源物件**

`Resource` 物件是值對物件，其中包含有關產生指標之資源的一些資訊。對於由 AWS建立的指標，資料結構包含與指標相關的資源的 Amazon Resource Name (ARN)，例如 EC2 執行個體或 S3 儲存貯體。

`Resource` 物件包含稱為 `attributes` 的屬性，其中會存放鍵/值對的清單。
+ `cloud.account.id` 包含帳戶 ID
+ `cloud.region` 包含區域
+ `aws.exporter.arn` 包含指標串流 ARN
+ `cloud.provider` 始終是 `aws`。

```
// Resource information.
message Resource {
  // Set of attributes that describe the resource.
  // Attribute keys MUST be unique (it is not allowed to have more than one
  // attribute with the same key).
  repeated opentelemetry.proto.common.v1.KeyValue attributes = 1;

  // dropped_attributes_count is the number of dropped attributes. If the value is 0, then
  // no attributes were dropped.
  uint32 dropped_attributes_count = 2;
}
```

**ScopeMetrics 物件**

將不會填充 `scope` 欄位。我們只填寫我們正在匯出的指標欄位。

```
// A collection of Metrics produced by an Scope.
message ScopeMetrics {
  // The instrumentation scope information for the metrics in this message.
  // Semantically when InstrumentationScope isn't set, it is equivalent with
  // an empty instrumentation scope name (unknown).
  opentelemetry.proto.common.v1.InstrumentationScope scope = 1;

  // A list of metrics that originate from an instrumentation library.
  repeated Metric metrics = 2;

  // This schema_url applies to all metrics in the "metrics" field.
  string schema_url = 3;
}
```

**指標物件**

指標物件包含一些中繼資料，以及包含 `SummaryDataPoint` 清單的 `Summary` 資料欄位。

對於指標串流，中繼資料如下：
+ `name` 將為 `amazonaws.com/{{metric_namespace}}/{{metric_name}}`
+ `description` 將為空白
+ `unit` 可藉由將指標基準的單位映射至統一計量單位代碼的變體 (區分大小寫) 來進行填充。如需詳細資訊，請參閱 [CloudWatch 中 OpenTelemetry 1.0.0 格式的轉換](CloudWatch-metric-streams-formats-opentelemetry-translation-100.md) 和[統一計量單位代碼](https://ucum.org/ucum.html)。
+ `type` 將為 `SUMMARY`

```
message Metric {
  reserved 4, 6, 8;

  // name of the metric, including its DNS name prefix. It must be unique.
  string name = 1;

  // description of the metric, which can be used in documentation.
  string description = 2;

  // unit in which the metric value is reported. Follows the format
  // described by http://unitsofmeasure.org/ucum.html.
  string unit = 3;

  // Data determines the aggregation type (if any) of the metric, what is the
  // reported value type for the data points, as well as the relatationship to
  // the time interval over which they are reported.
  oneof data {
    Gauge gauge = 5;
    Sum sum = 7;
    Histogram histogram = 9;
    ExponentialHistogram exponential_histogram = 10;
    Summary summary = 11;
  }
}

message Summary {
  repeated SummaryDataPoint data_points = 1;
}
```

**SummaryDataPoint 物件**

SummaryDataPoint 物件包含 DoubleSummary 指標中的時間序列的單一資料點的值。

```
// SummaryDataPoint is a single data point in a timeseries that describes the
// time-varying values of a Summary metric.
message SummaryDataPoint {
  reserved 1;

  // The set of key/value pairs that uniquely identify the timeseries from
  // where this point belongs. The list may be empty (may contain 0 elements).
  // Attribute keys MUST be unique (it is not allowed to have more than one
  // attribute with the same key).
  repeated opentelemetry.proto.common.v1.KeyValue attributes = 7;

  // StartTimeUnixNano is optional but strongly encouraged, see the
  // the detailed comments above Metric.
  //
  // Value is UNIX Epoch time in nanoseconds since 00:00:00 UTC on 1 January
  // 1970.
  fixed64 start_time_unix_nano = 2;

  // TimeUnixNano is required, see the detailed comments above Metric.
  //
  // Value is UNIX Epoch time in nanoseconds since 00:00:00 UTC on 1 January
  // 1970.
  fixed64 time_unix_nano = 3;

  // count is the number of values in the population. Must be non-negative.
  fixed64 count = 4;

  // sum of the values in the population. If count is zero then this field
  // must be zero.
  //
  // Note: Sum should only be filled out when measuring non-negative discrete
  // events, and is assumed to be monotonic over the values of these events.
  // Negative events *can* be recorded, but sum should not be filled out when
  // doing so.  This is specifically to enforce compatibility w/ OpenMetrics,
  // see: https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#summary
  double sum = 5;

  // Represents the value at a given quantile of a distribution.
  //
  // To record Min and Max values following conventions are used:
  // - The 1.0 quantile is equivalent to the maximum value observed.
  // - The 0.0 quantile is equivalent to the minimum value observed.
  //
  // See the following issue for more context:
  // https://github.com/open-telemetry/opentelemetry-proto/issues/125
  message ValueAtQuantile {
    // The quantile of a distribution. Must be in the interval
    // [0.0, 1.0].
    double quantile = 1;

    // The value at the given quantile of a distribution.
    //
    // Quantile values must NOT be negative.
    double value = 2;
  }

  // (Optional) list of values at different quantiles of the distribution calculated
  // from the current snapshot. The quantiles must be strictly increasing.
  repeated ValueAtQuantile quantile_values = 6;

  // Flags that apply to this specific data point.  See DataPointFlags
  // for the available flags and their meaning.
  uint32 flags = 8;
}
```

如需詳細資訊，請參閱[CloudWatch 中 OpenTelemetry 1.0.0 格式的轉換](CloudWatch-metric-streams-formats-opentelemetry-translation-100.md)。