# OpenTelemetry Collector
<a name="CloudWatch-OTLPSimplesetup"></a>

OpenTelemetry Collector は、テレメトリデータを受信、処理、エクスポートするオープンソースのベンダーに依存しないエージェントです。アプリケーションと Amazon CloudWatch 間の中央パイプラインとして機能し、複数のソースからメトリクス、ログ、トレースを収集し、OpenTelemetry Protocol (OTLP) を使用して CloudWatch に送信します。

CloudWatch で OpenTelemetry Collector を使用すると、次の利点があります:
+ 単一のエージェントを介して複数のアプリケーションとホストからテレメトリを収集し、CloudWatch への接続数を減らします。
+ 属性の追加または削除、データのバッチ処理、トレースのサンプリングなど、CloudWatch に送信する前にテレメトリを処理およびフィルタリングします。
+ AWS、オンプレミス、およびその他のクラウド環境全体で同じコレクター設定を使用し、アプリケーションの実行場所に関係なく一貫したテレメトリパイプラインを提供します。
+ CloudWatch Query Studio の Prometheus クエリ言語 (PromQL) を使用してクエリを実行できるリッチラベルを使用して、メトリクスを CloudWatch に送信します。

## サポートされているレシーバー
<a name="CloudWatch-OTLPSupportedReceivers"></a>

OpenTelemetry Collector は、テレメトリデータの取り込み用に幅広いレシーバーをサポートします。OpenTelemetry SDK で計測されたアプリケーションの OTLP レシーバーなどの OpenTelemetry レシーバー、または Prometheus レシーバーを使用して、既存の Prometheus エクスポーターからメトリクスをスクレイプできます。CloudWatch で使用される一般的な Prometheus レシーバーは次のとおりです:
+ Prometheus 互換エンドポイントをスクレイピングするための Prometheus レシーバー
+ ホストからシステムレベルのメトリクスを収集するためのホストメトリクスレシーバー
+ Kubernetes API サーバーからクラスターレベルのメトリクスを収集するための Kubernetes クラスターレシーバー

1 つのコレクターで複数のレシーバーを設定できるため、OpenTelemetry メトリクスと Prometheus メトリクスの両方を収集し、同じパイプラインを介して CloudWatch に送信できます。使用可能なレシーバーの完全なリストについては、OpenTelemetry Collector [リポジトリ](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver)を参照してください。

## 開始方法
<a name="CloudWatch-OTLPSimplesetupGettingStarted"></a>

前提条件 – トレースに OTLP エンドポイントを使用する場合は、トランザクション検索が有効になっていることを確認します。

手順:

1. OpenTelemetry Collector ディストリビューションの最新リリースをダウンロードします。詳細については、OpenTelemetry Collector の[リリース](https://github.com/open-telemetry/opentelemetry-collector-releases/releases)を参照してください。

1. ホストに OpenTelemetry Collector をインストールします。コレクターは、任意のオペレーティングシステムとプラットフォームで実行されます。詳細については、「[Install the Collector](https://opentelemetry.io/docs/collector/installation/)」を参照してください。

1. Amazon EC2 またはオンプレミスホストで AWS 認証情報を設定します。コレクターは、テレメトリデータの送信時にこれらの認証情報を使用して CloudWatch で認証します。詳細については以下を参照してください。

------
#### [ Setup IAM permissions for Amazon EC2 ]

**Amazon EC2 インスタンスの IAM ロールに `CloudWatchAgentServerPolicy` IAM ポリシーをアタッチするには、次の手順に従います。**

   1. IAM コンソール ([https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)) を開きます。

   1. **[ロール]** を選択し、Amazon EC2 インスタンスに使用しているロールを検索します。

   1. **[アクセス権限]** タブで、**[許可を追加]**、**[ポリシーをアタッチ]** の順に選択します。

   1. 検索ボックスで `CloudWatchAgentServerPolicy` ポリシーを検索します。

   1. **[CloudWatchAgentServerPolicy]** ポリシーを選択し、**[許可を追加]** を選択します。

------
#### [ Setup IAM permissions for on-premise hosts ]

**オンプレミスホストにアクセス許可を付与するために使用する IAM ユーザーを作成します。**

   1. IAM コンソール ([https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)) を開きます。

   1. **[ユーザー]**、**[ユーザーの作成]** の順に選択します。

   1. **[ユーザーの詳細]** で、**[ユーザー名]** に新しい IAM ユーザーの名前を入力します。これは、ホストの認証に使用される AWS のサインイン名です。

   1. [**次へ**] を選択します。

   1. **[アクセス許可の設定]** ページの **[権限オプション]** で、**[ポリシーを直接アタッチする]** を選択します。

   1. **[アクセス許可ポリシー]** リストから、**CloudWatchAgentServerPolicy** ポリシーを選択して、ユーザーに追加します。

   1. [**次へ**] を選択します。

   1. **[確認して作成]** ページで、ユーザー名に問題がなく、**[CloudWatchAgentServerPolicy]** ポリシーが **[許可の概要]** に含まれていることを確認します。

   1. **[ユーザーの作成]** を選択します。

   1. **AWS アクセスキーとシークレットキーを作成し取得する** - IAM コンソールのナビゲーションペインで、**[ユーザー]** を選択し、前のステップで作成したユーザーのユーザー名を選択します。

   1. ユーザーのページで、**[セキュリティ認証情報]** タブを選択します。

   1. **[アクセスキー]** セクションで、**[アクセスキーを作成]** を選択します。

   1. **[アクセスキーの作成ステップ 1]** で、**[コマンドラインインターフェイス (CLI)]** を選択します。

   1. **[アクセスキーの作成ステップ 2]** で、必要に応じてタグを入力して **[次へ]** を選択します。

   1. **[アクセスキーの作成ステップ 3]** で、**[.csv ファイルをダウンロード]** を選択し、.csv ファイルに IAM ユーザーのアクセスキーとシークレットアクセスキーを含めて保存します。この情報は、次のステップで必要になります。

   1. **[Done]** (完了) をクリックします。

   1. 次のコマンドを入力して、オンプレミスホストで AWS 認証情報を設定します。*ACCESS\$1KEY\$1ID* と *SECRET\$1ACCESS\$1ID* を、前のステップでダウンロードした .csv ファイルに新しく生成したアクセスキーとシークレットアクセスキーに置き換えます。

      ```
      $ aws configure
      AWS Access Key ID [None]: ACCESS_KEY_ID
      AWS Secret Access Key [None]: SECRET_ACCESS_ID
      Default region name [None]: MY_REGION
      Default output format [None]: json
      ```

------

1. Amazon EKS または Kubernetes クラスターの AWS 認証情報を設定します。Amazon EKS の使用を開始する最も簡単な方法は、EKS OTel Container Insights アドオンを使用することです。OpenTelemetry Collector を直接使用したい場合は、以下の手順に従って、Amazon EKS または Kubernetes クラスターの AWS 認証情報を設定してテレメトリを CloudWatch に送信します。

------
#### [ Setup IAM permissions for Amazon EKS ]

   1. 次のコマンドを使用して、クラスターの IAM OIDC ID プロバイダーを作成します。

      ```
      eksctl utils associate-iam-oidc-provider --cluster ${CLUSTER_NAME} --region ${REGION} --approve
      ```

   1. 次のコマンドを使用して、OTel Collector の Kubernetes サービスアカウントに IAM ロールを割り当てます。

      ```
      eksctl create iamserviceaccount \
      --name ${COLLECTOR_SERVICE_ACCOUNT}\
      --namespace ${NAMESPACE} \
      --cluster ${CLUSTER_NAME} \
      --region ${REGION} \
      --attach-policy-arn arn:aws:iam::aws:policy/CloudWatchAgentServerPolicy \
      --approve \
      --override-existing-serviceaccounts
      ```

------
#### [ Setup IAM permissions for Kubernetes ]

   1. 次のコマンドを入力して、オンプレミスホストで AWS 認証情報を設定します。*ACCESS\$1KEY\$1ID* と *SECRET\$1ACCESS\$1ID* を、前のステップでダウンロードした .csv ファイルに新しく生成したアクセスキーとシークレットアクセスキーに置き換えます。デフォルトでは、認証情報ファイルは */home/user/.aws/credentials* に保存されます。

      ```
      aws configure
      AWS Access Key ID [None]: ACCESS_KEY_ID 
      AWS Secret Access Key [None]: SECRET_ACCESS_ID 
      Default region name [None]: MY_REGION 
      Default output format [None]: json
      ```

   1. OpenTelemetry Collector リソースを編集して、`kubectl edit OpenTelemetryCollector otel_collector` コマンドを使用して新しく作成した AWS 認証情報シークレットを追加します。

   1. ファイルエディタを使用して、デプロイの上部に次の設定を追加して、OpenTelemetryCollector コンテナに AWS 認証情報を追加します。パス */home/user/.aws/credentials* をローカルの AWS 認証ファイルの場所に置き換えます。

      ```
                           spec:
                          volumeMounts:
                          - mountPath: /rootfs
                          volumeMounts:
                          - name: aws-credentials
                          mountPath: /root/.aws
                          readOnly: true
                          volumes:
                          - hostPath:
                          path: /home/user/.aws/credentials
                          name: aws-credentials
      ```

------

1. CloudWatch エンドポイントにテレメトリを送信するようにコレクター設定で OTLP エクスポーターを設定します。以下の例を参照してください。

## コレクター設定の例
<a name="CloudWatch-OTLPSimplesetupConfigureCollector"></a>

以下のコンテンツをコピーして貼り付け、OTLP エンドポイントにログとトレースを送信するようにコレクターを設定します。

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

exporters:
  otlphttp/logs:
    compression: gzip
    logs_endpoint: logs_otlp_endpoint
    headers: 
      x-aws-log-group: ency_log_group
      x-aws-log-stream: default
    auth:
      authenticator: sigv4auth/logs
      
  otlphttp/traces:
    compression: gzip
    traces_endpoint: traces_otlp_endpoint
    auth:
      authenticator: sigv4auth/traces

extensions:
  sigv4auth/logs:
    region: "region"
    service: "logs"
  sigv4auth/traces:
    region: "region"
    service: "xray"

service:
  telemetry:
  extensions: [sigv4auth/logs, sigv4auth/traces]
  pipelines:
    logs:
      receivers: [otlp]
      exporters: [otlphttp/logs]
    traces:
      receivers: [otlp]
      exporters: [otlphttp/traces]
```

sigv4 を使用してログとトレースを us-east-1 に送信する例を次に示します。

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

exporters:
  otlphttp/logs:
    compression: gzip
    logs_endpoint: https://logs.us-east-1.amazonaws.com/v1/logs
    headers: 
      x-aws-log-group: MyApplicationLogs
      x-aws-log-stream: default
    auth:
      authenticator: sigv4auth/logs
      
  otlphttp/traces:
    compression: gzip
    traces_endpoint: https://xray.us-east-1.amazonaws.com/v1/traces
    auth:
      authenticator: sigv4auth/traces

extensions:
  sigv4auth/logs:
    region: "us-east-1"
    service: "logs"
  sigv4auth/traces:
    region: "us-east-1"
    service: "xray"

service:
  telemetry:
  extensions: [sigv4auth/logs, sigv4auth/traces]
  pipelines:
    logs:
     receivers: [otlp]
      exporters: [otlphttp/logs]
    traces:
      receivers: [otlp]
      exporters: [otlphttp/traces]
```

**注記**  
OpenTelemetry SDK を *always\$1on* サンプリング設定に設定して、100% のスパンを確実に記録し、CloudWatch Application Signals を使用して重要なアプリケーションを完全に可視化します。詳細については、「[OpenTelemetry Java SDK sampler configuration](https://opentelemetry.io/docs/languages/java/sdk/#sampler)」の例を参照してください。X-Ray OTLP エンドポイントで OpenTelemetry Collector を設定する例については、「[application signals demo](https://github.com/aws-observability/application-signals-demo/blob/main/scripts/opentelemetry/otel_simple_setup/opentelemetry.yaml)」リポジトリを参照してください。

以下のコンテンツをコピーして貼り付け、OTLP エンドポイントにメトリクスを送信するようにコレクターを設定します。

```
receivers:
  otlp:
    protocols:
      http:
        endpoint: "0.0.0.0:4318"

processors:
  batch:
    send_batch_size: 200
    timeout: 10s

exporters:
  otlphttp:
    tls:
      insecure: false
    endpoint: metrics_otlp_endpoint
    auth:
      authenticator: sigv4auth

extensions:
  sigv4auth:
    service: "monitoring"
    region: "region"

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

sigv4 を使用してメトリクスを us-east-1 に送信する例を次に示します。

```
receivers:
  otlp:
    protocols:
      http:
        endpoint: "0.0.0.0:4318"

processors:
  batch:
    send_batch_size: 200
    timeout: 10s

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

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

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