Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

# CloudWatch keluaran aliran metrik dalam format OpenTelemetry 0.7.0
<a name="CloudWatch-metric-streams-formats-opentelemetry"></a>

OpenTelemetry adalah kumpulan alat, APIs, dan SDKs. Anda dapat menggunakannya untuk instrumen, menghasilkan, mengumpulkan, dan mengekspor data telemetri (metrik, log, dan jejak) untuk analisis. OpenTelemetry adalah bagian dari Cloud Native Computing Foundation. Untuk informasi selengkapnya, lihat [OpenTelemetry](https://opentelemetry.io/).

Untuk informasi tentang spesifikasi OpenTelemetry 0.7.0 lengkap, lihat rilis [v0.7.0](https://github.com/open-telemetry/opentelemetry-proto/releases/tag/v0.7.0).

Catatan Kinesis dapat berisi satu atau lebih struktur `ExportMetricsServiceRequest` OpenTelemetry data. Setiap struktur data dimulai dengan header dengan sebuah `UnsignedVarInt32` yang mengindikasikan panjang catatan dalam Byte. Setiap `ExportMetricsServiceRequest` dapat berisikan data dari beberapa metrik sekaligus.

Berikut ini adalah representasi string dari pesan struktur `ExportMetricsServiceRequest` OpenTelemetry data. OpenTelemetry membuat serial protokol biner Google Protocol Buffers, dan ini tidak dapat dibaca manusia.

```
resource_metrics {
  resource {
    attributes {
      key: "cloud.provider"
      value {
        string_value: "aws"
      }
    }
    attributes {
      key: "cloud.account.id"
      value {
        string_value: "2345678901"
      }
    }
    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"
      }
    }
  }
  instrumentation_library_metrics {
    metrics {
      name: "amazonaws.com/AWS/DynamoDB/ConsumedReadCapacityUnits"
      unit: "1"
      double_summary {
        data_points {
          labels {
            key: "Namespace"
            value: "AWS/DynamoDB"
          }
          labels {
            key: "MetricName"
            value: "ConsumedReadCapacityUnits"
          }
          labels {
            key: "TableName"
            value: "MyTable"
          }
          start_time_unix_nano: 1604948400000000000
          time_unix_nano: 1604948460000000000
          count: 1
          sum: 1.0
          quantile_values {
            quantile: 0.0
            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
          }
        }
        data_points {
          labels {
            key: "Namespace"
            value: "AWS/DynamoDB"
          }
          labels {
            key: "MetricName"
            value: "ConsumedReadCapacityUnits"
          }
          labels {
            key: "TableName"
            value: "MyTable"
          }
          start_time_unix_nano: 1604948460000000000
          time_unix_nano: 1604948520000000000
          count: 2
          sum: 5.0
          quantile_values {
            quantile: 0.0
            value: 2.0
          }
          quantile_values {
            quantile: 1.0
            value: 3.0
          }
        }
      }
    }
  }
}
```

**Objek tingkat atas untuk membuat serial data metrik OpenTelemetry **

`ExportMetricsServiceRequest`adalah pembungkus tingkat atas untuk membuat serial muatan eksportir. OpenTelemetry Itu berisikan satu atau beberapa `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`adalah objek tingkat atas untuk mewakili MetricData objek. 

```
// A collection of InstrumentationLibraryMetrics from a Resource.
message ResourceMetrics {
  // 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 InstrumentationLibraryMetrics instrumentation_library_metrics = 2;
}
```

**objek Sumber Daya**

Objek `Resource` adalah sebuah objek pasangan-nilai yang berisikan beberapa informasi tentang sumber daya yang dihasilkan metrik. Untuk metrik yang dibuat oleh AWS, struktur data yang berisikan Amazon Resource Name (ARN) dari sumber daya yang berkaitan dengan metrik, seperti instans EC2 atau bucket S3.

Objek `Resource` berisikan atribut yang disebut `attributes`, yang menyimpan daftar pasangan nilai-kunci.
+ `cloud.account.id` berisi ID akun
+ `cloud.region` berisi Wilayah
+ `aws.exporter.arn` berisi ARN stream metrik
+ `cloud.provider` selalu `aws`.

```
// Resource information.
message Resource {
  // Set of labels that describe the resource.
  repeated opentelemetry.proto.common.v1.KeyValue attributes = 1;
  
  // dropped_attributes_count is the number of dropped attributes. If the value is 0,
  // no attributes were dropped.
  uint32 dropped_attributes_count = 2;
}
```

** InstrumentationLibraryMetrics Objeknya**

Bidang instrumentation\$1library tidak akan diisi. Kami hanya akan mengisi bidang metrik yang kami ekspor.

```
// A collection of Metrics produced by an InstrumentationLibrary.
message InstrumentationLibraryMetrics {
  // The instrumentation library information for the metrics in this message.
  // If this field is not set then no library info is known.
  opentelemetry.proto.common.v1.InstrumentationLibrary instrumentation_library = 1;
  // A list of metrics that originate from an instrumentation library.
  repeated Metric metrics = 2;
}
```

**objek Metrik**

Objek metrik berisikan kolom data `DoubleSummary` yang berisi daftar `DoubleSummaryDataPoint`.

```
message Metric {
  // 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;

  oneof data {
    IntGauge int_gauge = 4;
    DoubleGauge double_gauge = 5;
    IntSum int_sum = 6;
    DoubleSum double_sum = 7;
    IntHistogram int_histogram = 8;
    DoubleHistogram double_histogram = 9;
    DoubleSummary double_summary = 11;
  }
}

message DoubleSummary {
  repeated DoubleSummaryDataPoint data_points = 1;
}
```

** MetricDescriptor Objeknya**

 MetricDescriptor Objek berisi metadata. Untuk informasi selengkapnya, lihat [metrics.proto](https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/metrics/v1/metrics.proto#L110) di. GitHub

Untuk aliran metrik, MetricDescriptor memiliki konten berikut:
+ `name` akan menjadi `amazonaws.com/metric_namespace/metric_name`
+ `description` akan menjadi kosong.
+ `unit` akan diisi dengan pemetaan unit datum metrik ke varian yang sensitif huruf besar-kecil dari kode Terpadu untuk Unit Ukur. Untuk informasi selengkapnya, silakan lihat [Terjemahan dengan format OpenTelemetry 0.7.0 di CloudWatch](CloudWatch-metric-streams-formats-opentelemetry-translation.md) dan [Kode Terpadu Untuk Unit Ukur](https://ucum.org/ucum.html).
+ `type` akan menjadi `SUMMARY`.

** DoubleSummaryDataPoint Objeknya**

 DoubleSummaryDataPoint Objek berisi nilai titik data tunggal dalam deret waktu dalam DoubleSummary metrik.

```
// DoubleSummaryDataPoint is a single data point in a timeseries that describes the
// time-varying values of a Summary metric.
message DoubleSummaryDataPoint {
  // The set of labels that uniquely identify this timeseries.
  repeated opentelemetry.proto.common.v1.StringKeyValue labels = 1;

  // start_time_unix_nano is the last time when the aggregation value was reset
  // to "zero". For some metric types this is ignored, see data types for more
  // details.
  //
  // The aggregation value is over the time interval (start_time_unix_nano,
  // time_unix_nano].
  //
  // Value is UNIX Epoch time in nanoseconds since 00:00:00 UTC on 1 January
  // 1970.
  //
  // Value of 0 indicates that the timestamp is unspecified. In that case the
  // timestamp may be decided by the backend.
  fixed64 start_time_unix_nano = 2;

  // time_unix_nano is the moment when this aggregation value was reported.
  //
  // 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.
  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.
  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.
    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;
}
```

Untuk informasi selengkapnya, lihat [Terjemahan dengan format OpenTelemetry 0.7.0 di CloudWatch](CloudWatch-metric-streams-formats-opentelemetry-translation.md).

# Terjemahan dengan format OpenTelemetry 0.7.0 di CloudWatch
<a name="CloudWatch-metric-streams-formats-opentelemetry-translation"></a>

CloudWatch melakukan beberapa transformasi untuk memasukkan CloudWatch data ke dalam OpenTelemetry format.

**Menerjemahkan namespace, nama metrik, dan dimensi**

Atribut ini adalah pasangan nilai-kunci yang dikodekan ke dalam pemetaan.
+ Satu pasangan berisikan namespace metrik
+ Satu pasangan berisikan name metrik
+ Untuk setiap dimensi, CloudWatch simpan pasangan berikut: `metricDatum.Dimensions[i].Name, metricDatum.Dimensions[i].Value`

**Menerjemahkan Rata-rata, Jumlah, SampleCount, Min dan Maks**

Titik data Ringkasan memungkinkan CloudWatch untuk mengekspor semua statistik ini menggunakan satu titik data.
+ `startTimeUnixNano`berisi CloudWatch `startTime`
+ `timeUnixNano`berisi CloudWatch `endTime`
+ `sum` berisi statistik Jumlah.
+ `count`berisi SampleCount statistik.
+ `quantile_values` berisi dua objek `valueAtQuantile.value`:
  + `valueAtQuantile.quantile = 0.0` dengan `valueAtQuantile.value = Min value`
  + `valueAtQuantile.quantile = 0.99` dengan `valueAtQuantile.value = p99 value`
  + `valueAtQuantile.quantile = 0.999` dengan `valueAtQuantile.value = p99.9 value`
  + `valueAtQuantile.quantile = 1.0` dengan `valueAtQuantile.value = Max value`

Sumber daya yang menggunakan aliran metrik dapat menghitung statistik Rata-rata sebagai **Jumlah/ SampleCount**.

**Menerjemahkan unit-unit**

CloudWatch unit dipetakan ke varian peka huruf besar/kecil dari kode Terpadu untuk Satuan Ukuran, seperti yang ditunjukkan pada tabel berikut. Untuk informasi selengkapnya, silakan lihat [Kode Terpadu Untuk Unit Ukur](https://ucum.org/ucum.html).


| CloudWatch | OpenTelemetry | 
| --- | --- | 
|  Detik |  d | 
|  Detik atau Detik |  d | 
|  Mikrodetik |  µs | 
|  Milidetik |  ms | 
|  Byte |  Oleh | 
|  Kilobyte |  kBy | 
|  Megabyte |  MBy | 
|  Gigabyte |  GBy | 
|  Terabyte |  TBy | 
|  Bit |  bit | 
|  Kilobit |  kbit | 
|  Megabit |  MBit | 
|  Gigabit |  GBit | 
|  Terabit |  TBit | 
|  Persen |  % | 
|  Hitungan |  \$1Count\$1 | 
|  Tidak ada |  1 | 

Unit yang digabungkan dengan garis miring dipetakan dengan menerapkan OpenTelemetry konversi kedua unit. Misalnya, Bytes/Second dipetakan ke BY/s.

# Cara mengurai pesan OpenTelemetry 0.7.0
<a name="CloudWatch-metric-streams-formats-opentelemetry-parse"></a>

Bagian ini memberikan informasi untuk membantu Anda memulai dengan parsing OpenTelemetry 0.7.0.

Pertama, Anda harus mendapatkan binding khusus bahasa, yang memungkinkan Anda mengurai pesan OpenTelemetry 0.7.0 dalam bahasa pilihan Anda.

**Untuk mendapatkan ikatan bahasa tertentu**
+ Langkah-langkahnya tergantung pada bahasa pilihan Anda.
  + [Untuk menggunakan Java, tambahkan dependensi Maven berikut ke proyek Java Anda: Java >> 0.14.1OpenTelemetry .](https://mvnrepository.com/artifact/io.opentelemetry/opentelemetry-proto/0.14.1)
  + Untuk menggunakan bahasa lain, ikuti langkah-langkah ini:

    1. Pastikan bahasa Anda didukung dengan memeriksa daftar di [Menghasilkan Kelas Anda](https://developers.google.com/protocol-buffers/docs/proto3#generating).

    1. Instal alat kompilasi Protobuf dengan mengikuti langkah-langkah di [Unduh Buffer Protokol](https://developers.google.com/protocol-buffers/docs/downloads).

    1. Unduh ProtoBuf definisi OpenTelemetry 0.7.0 pada rilis [v0.7.0](https://github.com/open-telemetry/opentelemetry-proto/releases/tag/v0.7.0). 

    1. Konfirmasikan bahwa Anda berada di folder root dari definisi OpenTelemetry 0.7.0 ProtoBuf yang diunduh. Kemudian buatlah folder `src` lalu jalankan perintah untuk menghasilkan ikatan bahasa khusus. Untuk informasi selengkapnya, silakan lihat [Menghasilkan Kelas Anda](https://developers.google.com/protocol-buffers/docs/proto3#generating). 

       Berikut ini adalah contoh untuk cara menghasilkan ikatan Javascript.

       ```
       protoc --proto_path=./ --js_out=import_style=commonjs,binary:src \
       opentelemetry/proto/common/v1/common.proto \
       opentelemetry/proto/resource/v1/resource.proto \
       opentelemetry/proto/metrics/v1/metrics.proto \
       opentelemetry/proto/collector/metrics/v1/metrics_service.proto
       ```

Bagian berikut mencakup contoh-contoh menggunakan ikatan bahasa khusus yang dapat Anda bangun dengan menggunakan petunjuk sebelumnya.

**Java**

```
package com.example;

import io.opentelemetry.proto.collector.metrics.v1.ExportMetricsServiceRequest;

import java.io.IOException;
import java.io.InputStream;
import java.util.ArrayList;
import java.util.List;

public class MyOpenTelemetryParser {

    public List<ExportMetricsServiceRequest> parse(InputStream inputStream) throws IOException {
        List<ExportMetricsServiceRequest> result = new ArrayList<>();

        ExportMetricsServiceRequest request;
        /* A Kinesis record can contain multiple `ExportMetricsServiceRequest`
           records, each of them starting with a header with an
           UnsignedVarInt32 indicating the record length in bytes:
            ------ --------------------------- ------ -----------------------
           |UINT32|ExportMetricsServiceRequest|UINT32|pExportMetricsService...
            ------ --------------------------- ------ -----------------------
         */
        while ((request = ExportMetricsServiceRequest.parseDelimitedFrom(inputStream)) != null) {
            // Do whatever we want with the parsed message
            result.add(request);
        }

        return result;
    }
}
```

**Javascript**

Contoh ini mengasumsikan bahwa folder akar dengan ikatan yang dihasilkan adalah `./`

Argumen data dari fungsi `parseRecord` dapat menjadi salah satu dari jenis berikut:
+ `Uint8Array` ini adalah optimal
+ `Buffer` menjadi optimal di bawah simpul
+ `Array.number` adalah bilangan bulat 8-bit

```
const pb = require('google-protobuf')
const pbMetrics =
    require('./opentelemetry/proto/collector/metrics/v1/metrics_service_pb')

function parseRecord(data) {
    const result = []

    // Loop until we've read all the data from the buffer
    while (data.length) {
        /* A Kinesis record can contain multiple `ExportMetricsServiceRequest`
           records, each of them starting with a header with an
           UnsignedVarInt32 indicating the record length in bytes:
            ------ --------------------------- ------ -----------------------
           |UINT32|ExportMetricsServiceRequest|UINT32|ExportMetricsService...
            ------ --------------------------- ------ -----------------------
         */
        const reader = new pb.BinaryReader(data)
        const messageLength = reader.decoder_.readUnsignedVarint32()
        const messageFrom = reader.decoder_.cursor_
        const messageTo = messageFrom + messageLength

        // Extract the current `ExportMetricsServiceRequest` message to parse
        const message = data.subarray(messageFrom, messageTo)

        // Parse the current message using the ProtoBuf library
        const parsed =
            pbMetrics.ExportMetricsServiceRequest.deserializeBinary(message)

        // Do whatever we want with the parsed message
        result.push(parsed.toObject())

        // Shrink the remaining buffer, removing the already parsed data
        data = data.subarray(messageTo)
    }

    return result
}
```

**Python**

Anda harus membaca anti pembatas `var-int` oleh Anda sendiri atau gunakan metode internal `_VarintBytes(size)` dan `_DecodeVarint32(buffer, position)`. Hal ini akan mengembalikan posisi dalam buffer langsung menyusul ukuran bita. Bagian baca akan mengonstruksi buffer baru yang terbatas pada pembacaan byte pesan saja. 

```
size = my_metric.ByteSize()
f.write(_VarintBytes(size))
f.write(my_metric.SerializeToString())
msg_len, new_pos = _DecodeVarint32(buf, 0)
msg_buf = buf[new_pos:new_pos+msg_len]
request = metrics_service_pb.ExportMetricsServiceRequest()
request.ParseFromString(msg_buf)
```

**Kunjungi**

Gunakan `Buffer.DecodeMessage()`.

**C\$1**

Gunakan `CodedInputStream`. Kelas ini dapat membaca pesan dengan ukuran tak terbatas.

**C\$1\$1**

Fungsi yang dijelaskan dalam `google/protobuf/util/delimited_message_util.h` dapat membaca pesan yang dibatasi ukuran.

**Bahasa lain**

Untuk bahasa lain, silakan lihat [Unduh Protokol Buffer](https://developers.google.com/protocol-buffers/docs/downloads).

Saat menerapkan alat pengurai, pertimbangkan bahwa sebuah catatan Kinesis dapat berisikan beberapa pesan Protokol Buffer `ExportMetricsServiceRequest` , masing-masing dimulai dengan sebuah header dengan sebuah `UnsignedVarInt32` yang menunjukkan panjang catatan dalam bita.