NGINX

プラグインとコンフィギュレーションを組み合わせて使用することで、NGINX で Datadog APM に対応できます。 公式 Linux レポジトリの NGINX を使用して、プラグインのバイナリを事前構築する手順を以下に記載しました。

オープンソース NGINX

プラグインのインストール

注: このプラグインは、古いバージョンの libstdc++ を使用する Linux ディストリビューションでは機能しません。これには、RHEL/Centos 7 および AmazonLinux 1 が含まれます。 これの回避策は、Docker コンテナから NGINX を実行することです。Dockerfile の例がこちらにあります。

次のプラグインをインストールする必要があります。

次のコマンドを使用してモジュールをダウンロードしてインストールします。

# GitHub から最新のリリースバージョン番号を取得します。
get_latest_release() {
  wget -qO- "https://api.github.com/repos/$1/releases/latest" |
    grep '"tag_name":' |
    sed -E 's/.*"([^"]+)".*/\1/';
}
NGINX_VERSION=1.17.3
OPENTRACING_NGINX_VERSION="$(get_latest_release opentracing-contrib/nginx-opentracing)"
DD_OPENTRACING_CPP_VERSION="$(get_latest_release DataDog/dd-opentracing-cpp)"
# OpenTracing 用の NGINX プラグインをインストールします
wget https://github.com/opentracing-contrib/nginx-opentracing/releases/download/${OPENTRACING_NGINX_VERSION}/linux-amd64-nginx-${NGINX_VERSION}-ot16-ngx_http_module.so.tgz
tar zxf linux-amd64-nginx-${NGINX_VERSION}-ot16-ngx_http_module.so.tgz -C /usr/lib/nginx/modules
# Datadog Opentracing C++ プラグインをインストールします
wget https://github.com/DataDog/dd-opentracing-cpp/releases/download/${DD_OPENTRACING_CPP_VERSION}/linux-amd64-libdd_opentracing_plugin.so.gz
gunzip linux-amd64-libdd_opentracing_plugin.so.gz -c > /usr/local/lib/libdd_opentracing_plugin.so

NGINX コンフィギュレーション

OpenTracing モジュールを NGINX コンフィギュレーションに読み込む必要があります。

# OpenTracing モジュールを読み込む
load_module modules/ngx_http_opentracing_module.so;

http ブロックにより OpenTracing モジュールを有効化し、Datadog トレーサーを読み込みます。

    opentracing on; # OpenTracing を有効化
    opentracing_tag http_user_agent $http_user_agent; # 各トレースにタグを追加。
    opentracing_trace_locations off; # 各リクエストにつき 1 スパンのみ送信。

    # Datadog トレーシングの実装と既定のコンフィグファイルを読み込む。
    opentracing_load_tracer /usr/local/lib/libdd_opentracing_plugin.so /etc/nginx/dd-config.json;

トレーシングが必要なサーバー内の location ブロックに次の指示を追加します。

            opentracing_operation_name "$request_method $uri";
            opentracing_propagate_context;

Datadog トレーシングの実装コンフィグファイルには、次の指示も必要です。

{
  "environment": "prod",
  "service": "nginx",
  "operation_name_override": "nginx.handle",
  "agent_host": "localhost",
  "agent_port": 8126
}

service 値は NGINX の使用に合わせて意味のある値に変更できます。 NGINX をコンテナまたはオーケストレーション環境で使用している場合は、agent_host 値を変更する必要があります。

完成例

このコンフィギュレーションが完了すると、NGINX への HTTP リクエストが開始し Datadog トレースを伝達します。リクエストは APM UI に表示されます。

NGINX および FastCGI

場所が HTTP ではなく FastCGI バックエンドを提供している場合、location ブロックは opentracing_propagate_context ではなく opentracing_fastcgi_propagate_context を使用する必要があります。

Kubernetes 対応 NGINX Ingress コントローラー

Kubernetes ingress-nginx コントローラーのバージョン 0.23.0 以降には、OpenTracing 対応 NGINX プラグインが含まれています。

このプラグインを有効化するには、ConfigMap を作成または編集して enable-opentracing: "true" と、トレースの送信先となる datadog-collector-host に設定します。 ConfigMap 名は nginx-ingress コントローラーコンテナのコマンドライン引数により明示的に引用し、--configmap=$(POD_NAMESPACE)/nginx-configuration をデフォルトに設定します。 ingress-nginx が Helm チャートからインストールされた場合は、この ConfigMap の名前は Release-Name-nginx-ingress-controller となります。

Ingress コントローラーは nginx.conf と /etc/nginx/opentracing.json 双方のファイルを管理します。すべての location ブロックでトレーシングが有効化されます。

kind: ConfigMap
apiVersion: v1
metadata:
  name: nginx-configuration
  namespace: ingress-nginx
  labels:
    app.kubernetes.io/name: ingress-nginx
    app.kubernetes.io/part-of: ingress-nginx
data:
  enable-opentracing: "true"
  datadog-collector-host: $HOST_IP
  # デフォルト
  # datadog-service-name: "nginx"
  # datadog-collector-port: "8126"
  # datadog-operation-name-override: "nginx.handle"

また、nginx-ingress コントローラーのポッド仕様に HOST_IP 環境変数セットが含まれていることを確認してください。環境変数 POD_NAME と POD_NAMESPACE を含む env: ブロックに下記のエントリを追加します。

- name: HOST_IP
  valueFrom:
    fieldRef:
      fieldPath: status.hostIP

アノテーションを使用して Ingress ごとに異なるサービス名を設定するには

  nginx.ingress.kubernetes.io/configuration-snippet: |
            opentracing_tag "service.name" "custom-service-name";

上記はデフォルトの nginx-ingress-controller.ingress-nginx サービス名をオーバーライドします。

その他の参考資料

お役に立つドキュメント、リンクや記事:

サービス、リソース、トレースを調査するAPM の UI を利用する more more NGINX ウェブサイトDOCUMENTATION more more NGINX Ingress Controller OpenTracingDOCUMENTATION more more OpenTracing 対応 NGINX プラグインソースコード more more Datadog OpenTracing C++ クライアントソースコード more more