Managed Service for OpenTelemetry:OpenTelemetry を使用した NGINX のトレーシング分析

NGINX のトレース分析機能を有効にするには、NGINX のメイン設定ファイル /etc/nginx/nginx.conf で ngx_otel_module をロードし、ngx_otel_module のパラメーターを設定する必要があります。 ngx_otel_module のパラメーターの詳細については、「ngx_otel_module の公式ドキュメント」をご参照ください。

• すべての HTTP リクエストのトレーシング分析を有効にする

  ngx_otel_module V0.1.2 以降

  load_module modules/ngx_otel_module.so; # ngx_otel_module をロードします
  ...
  http {
      ...
  
      otel_exporter {
          endpoint "${GRPC_ENDPOINT}"; # 前提条件で取得した gRPC エンドポイント
          header Authentication "${GRPC_TOKEN}"; # 前提条件で取得した認証トークン
      }
  
      otel_trace on;                     # トレーシング分析を有効にします
      otel_service_name ${SERVICE_NAME};  # アプリケーション名
      otel_trace_context propagate;         # トレースコンテキストをダウンストリームサービスに挿入します
      ...
  }

  ngx_otel_module V0.1.1 以前

  説明

  設定内の以下の変数を置き換えてください。

  • ${OTEL_COLLECTOR_GRPC_RECEIVER_ENDPOINT}: デプロイした OpenTelemetry Collector の gRPC エンドポイントです (例: localhost:4317)。 このエンドポイントは、前提条件で取得した Managed Service for OpenTelemetry のエンドポイントとは異なります。

  • ${SERVICE_NAME}: アプリケーション名です。この名前は、Managed Service for OpenTelemetry コンソールに NGINX アプリケーション名として表示されます。

  load_module modules/ngx_otel_module.so; # ngx_otel_module をロードします
  ...
  http {
      ...
  
      otel_exporter {
          endpoint ${OTEL_COLLECTOR_GRPC_RECEIVER_ENDPOINT}; # OpenTelemetry Collector のレポートアドレス (例: localhost:4317)
      }
  
      otel_trace on;                     # トレーシング分析を有効にします
      otel_service_name ${SERVICE_NAME};  # アプリケーション名
      otel_trace_context propagate;         # トレースコンテキストをダウンストリームサービスに挿入します
      ...
  }

• 特定のロケーションへの HTTP リクエストのトレーシング分析を有効にする

  ngx_otel_module V0.1.2 以降

  load_module modules/ngx_otel_module.so; # ngx_otel_module をロードします
  
  ...
  
  http {
  
      otel_exporter {
          endpoint "${GRPC_ENDPOINT}"; # 前提条件で取得した gRPC エンドポイント
          header Authentication "${GRPC_TOKEN}"; # 前提条件で取得した認証トークン
      }
  
      server {
          listen 127.0.0.1:80;
  
          location /hello {
              otel_trace         on;             # 127.0.0.1:80/hello のみトレーシング分析を有効にします
              otel_service_name ${SERVICE_NAME}  # アプリケーション名
              otel_trace_context propagate;         # トレースコンテキストをダウンストリームサービスに挿入します
  
              ...
          }
      }
  }

  ngx_otel_module V0.1.1 以前

  説明

  設定内の 2 つの変数を置き換えてください。

  • ${OTEL_COLLECTOR_GRPC_RECEIVER_ENDPOINT}: デプロイした OpenTelemetry Collector の gRPC エンドポイントです (例: localhost:4317)。このエンドポイントは、前提条件で取得した Managed Service for OpenTelemetry のエンドポイントとは異なります。

  • ${SERVICE_NAME}: アプリケーション名。この名前は、Managed Service for OpenTelemetry コンソールに NGINX アプリケーション名として表示されます。

  load_module modules/ngx_otel_module.so; # ngx_otel_module をロードします
  
  ...
  
  http {
  
      otel_exporter {
          endpoint ${OTEL_COLLECTOR_GRPC_RECEIVER_ENDPOINT}; # OpenTelemetry Collector のレポートアドレス (例: localhost:4317)
      }
  
      server {
          listen 127.0.0.1:80;
  
          location /hello {
              otel_trace         on;             # 127.0.0.1:80/hello のみトレーシング分析を有効にします
              otel_service_name ${SERVICE_NAME}  # アプリケーション名
              otel_trace_context propagate;         # トレースコンテキストをダウンストリームサービスに挿入します
  
              ...
          }
      }
  }

ステップ 3: (オプション) OpenTelemetry Collector のデプロイ

ステップ 4: NGINX トレースの表示

前述の手順を完了して NGINX を再起動した後、NGINX にリクエストを送信してトレースを生成します。その後、Managed Service for OpenTelemetry コンソールにログインし、OpenTelemetry によって生成された NGINX トレースを表示します。

• [アプリケーション] ページで、NGINX アプリケーションを見つけ、アプリケーション名をクリックします。

• [トレース詳細] タブでは、リクエスト期間、クライアント IP アドレス、HTTP ステータスコードなどのトレース詳細を表示できます。 バックエンドサービスも Managed Service for OpenTelemetry に接続されている場合、NGINX とバックエンドサービスのトレースは自動的に関連付けられ、統合ビューが提供されます。 [トレース詳細] ページでは、スパンウォーターフォールに、nginx と Node.js バックエンドサービス (ot-node-demo) を通過するリクエストの完全なトレースが表示されます。 nginx はまず /hello リクエスト (合計期間 6 ms、HTTP 200) を受信し、次にそれを ot-node-demo の GET /hello (5.76 ms) に転送します。これには、middleware-query、middleware-expressInit、request handler-/hello の 3 つの内部スパンが含まれています。 右側のスパン詳細パネルには、http.status_code=200、http.route=/hello、http.user_agent=curl/7.61.1 などの nginx アプリケーションの属性が表示されます。

ステップ 1: 準備

• Git、Docker、Docker Compose をインストールします。

• エンドポイントを取得します。

ステップ 2: プロジェクトディレクトリの作成

nginx-otel-demo
│
├── docker-compose.yml          # Docker Compose の設定ファイル
│
├── nginx_conf/                 # NGINX の設定ファイル
│   ├── default.conf
│   └── nginx.conf              
│
├── otel_conf/                  # OpenTelemetry Collector の設定ファイル
│   └── config.yaml           
│
└── backend/                    # Node.js を使用して開発されたバックエンドサービス
    ├── Dockerfile              
    ├── main.js
    ├── package.json
    └── package-lock.json

ディレクトリを作成します。

mkdir nginx-otel-demo && cd nginx-otel-demo

mkdir -p nginx_conf otel_conf backend

ステップ 3: NGINX の設定ファイルの作成

1. NGINX のメイン設定ファイル nginx.conf を作成します。

   ngx_otel_module V0.1.2 以降

   cat << 'EOF' > nginx_conf/nginx.conf
   load_module modules/ngx_otel_module.so;
   
   user  nginx;
   worker_processes  auto;
   
   error_log  /var/log/nginx/error.log notice;
   pid        /var/run/nginx.pid;
   
   
   events {
       worker_connections  1024;
   }
   
   
   http {
       include       /etc/nginx/mime.types;
       default_type  application/octet-stream;
   
       log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                         '$status $body_bytes_sent "$http_referer" '
                         '"$http_user_agent" "$http_x_forwarded_for"';
   
       access_log  /var/log/nginx/access.log  main;
   
       sendfile        on;
       #tcp_nopush     on;
   
       keepalive_timeout  65;
   
       #gzip  on;
   
       otel_exporter {
           endpoint "${GRPC_ENDPOINT}";
           header Authentication "${GRPC_TOKEN}";
       }
   
       otel_trace on;
   
       otel_trace_context propagate;
   
       otel_service_name nginx;
   
       include /etc/nginx/conf.d/*.conf;
   
   }
   EOF

   ngx_otel_module V0.1.1 以前

   load_module modules/ngx_otel_module.so;
   
   user  nginx;
   worker_processes  auto;
   
   error_log  /var/log/nginx/error.log notice;
   pid        /var/run/nginx.pid;
   
   
   events {
       worker_connections  1024;
   }
   
   
   http {
       include       /etc/nginx/mime.types;
       default_type  application/octet-stream;
   
       log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                         '$status $body_bytes_sent "$http_referer" '
                         '"$http_user_agent" "$http_x_forwarded_for"';
   
       access_log  /var/log/nginx/access.log  main;
   
       sendfile        on;
       #tcp_nopush     on;
   
       keepalive_timeout  65;
   
       #gzip  on;
   
       otel_exporter {
           endpoint otel-collector:4317;
       }
   
       otel_trace on;
   
       otel_trace_context propagate;
   
       otel_service_name nginx;
   
       include /etc/nginx/conf.d/*.conf;
   
   }
   EOF
   

2. NGINX の設定ファイル default.conf を作成します。

   cat << 'EOF' > nginx_conf/default.conf
   server {
       listen       80;
       server_name  localhost;
   
       location / {
           root   /usr/share/nginx/html;
           index  index.html index.htm;
       }
       
       # パラメーターを設定します
       location /hello {
           proxy_pass http://backend-api:7001/hello;
           proxy_http_version 1.1;
           proxy_set_header Host $host;
           proxy_set_header X-Real-IP $remote_addr;
       }
   
       # サーバーエラーページを静的ページ /50x.html にリダイレクトします
       #
       error_page   500 502 503 504  /50x.html;
       location = /50x.html {
           root   /usr/share/nginx/html;
       }
   }
   EOF

ステップ 4: (オプション) OpenTelemetry Collector の設定ファイルの作成

OpenTelemetry Collector の設定ファイルを作成します。この設定ファイルは、データの受信、処理、レポート方法を定義します。

cat << 'EOF' > otel_conf/config.yaml
receivers:
  otlp:
    protocols:
      grpc: 
        endpoint: 0.0.0.0:4317

exporters:
  otlp:
    endpoint: ${GRPC_ENDPOINT}
    tls:
      insecure: true
    headers:
      "Authentication": "${GRPC_ENDPOINT_TOKEN}"

processors:
  batch:
  
service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp]
EOF

ステップ 5: Node.js を使用したバックエンドサービスの作成

1. package.json ファイルを作成します。このファイルには、サービス名、サービスバージョン、依存関係など、バックエンドサービスの設定情報が含まれます。

   cat << 'EOF' > backend/package.json
   {
     "name": "backend",
     "version": "1.0.0",
     "main": "index.js",
     "scripts": {},
     "keywords": [],
     "author": "",
     "license": "ISC",
     "description": "",
     "dependencies": {
       "@opentelemetry/api": "^1.9.0",
       "@opentelemetry/auto-instrumentations-node": "^0.52.0",
       "axios": "^1.7.7",
       "express": "^4.21.1"
     }
   }
   EOF

2. 基本的な Express Web アプリケーションを定義する main.js ファイルを作成します。

   cat << 'EOF' > backend/main.js
   "use strict";
   const axios = require("axios").default;
   const express = require("express");
   const app = express();
   app.get("/", async (req, res) => {
     const result = await axios.get("http://localhost:7001/hello");
     return res.status(201).send(result.data);
   });
   app.get("/hello", async (req, res) => {
     console.log("hello world!")
     res.json({ code: 200, msg: "success" });
   });
   app.use(express.json());
   app.listen(7001, () => {
     console.log("Listening on http://localhost:7001");
   });
   EOF

3. Dockerfile を作成します。

   ngx_otel_module V0.1.2 以降

   cat << 'EOF' > backend/Dockerfile
   FROM node:20.16.0
   WORKDIR /app
   COPY package*.json ./
   RUN npm install
   COPY . .
   ENV OTEL_TRACES_EXPORTER="otlp"
   ENV OTEL_LOGS_EXPORTER=none
   ENV OTEL_METRICS_EXPORTER=none
   ENV OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=grpc
   ENV OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="${GRPC_ENDPOINT}"
   ENV OTEL_EXPORTER_OTLP_HEADERS="Authentication=${GRPC_TOKEN}"
   ENV OTEL_NODE_RESOURCE_DETECTORS="env,host,os"
   ENV OTEL_SERVICE_NAME="ot-nodejs-demo"
   ENV NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register"
   EXPOSE 7001
   CMD ["node", "main.js"]
   EOF

   ngx_otel_module V0.1.1 以前

   cat << 'EOF' > backend/Dockerfile
   FROM node:20.16.0
   WORKDIR /app
   COPY package*.json ./
   RUN npm install
   COPY . .
   ENV OTEL_TRACES_EXPORTER="otlp"
   ENV OTEL_LOGS_EXPORTER=none
   ENV OTEL_METRICS_EXPORTER=none
   ENV OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=grpc
   ENV OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="http://otel-collector:4317"
   ENV OTEL_NODE_RESOURCE_DETECTORS="env,host,os"
   ENV OTEL_SERVICE_NAME="ot-nodejs-demo"
   ENV NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register"
   EXPOSE 7001
   CMD ["node", "main.js"]
   EOF

ステップ 6: Docker Compose の設定ファイルの作成

Docker Compose の設定ファイルは、リバースプロキシとして機能する NGINX、OpenTelemetry Collector、Node.js バックエンドサービスを含むマルチコンテナアプリケーションの設定を定義します。このファイルは、コンポーネント間のネットワーク接続とポートマッピングも定義します。

cat << 'EOF' > docker-compose.yml
version: "3"

services:
  nginx:
    image: nginx:1.27.5-alpine-otel # ngx_otel_module V0.1.2 を含むデフォルトの NGINX イメージ
    volumes:
      - ./nginx_conf/nginx.conf:/etc/nginx/nginx.conf:ro 
      - ./nginx_conf/default.conf:/etc/nginx/conf.d/default.conf:ro 
    ports:
      - "80:80"
    networks:
      - nginx-otel-demo

  backend-api:
    build:
      context: ./backend
      dockerfile: Dockerfile
    environment:
      - NODE_ENV=production
    ports:
      - "7001:7001"
    networks:
      - nginx-otel-demo

networks:
  nginx-otel-demo:
    driver: bridge
EOF

cat << 'EOF' > docker-compose.yml
version: "3"

services:
  nginx:
    image: nginx:1.27.2-alpine-otel # OpenTelemetry モジュールを含むデフォルトの NGINX イメージ
    volumes:
      - ./nginx_conf/nginx.conf:/etc/nginx/nginx.conf:ro 
      - ./nginx_conf/default.conf:/etc/nginx/conf.d/default.conf:ro 
    ports:
      - "80:80"
    networks:
      - nginx-otel-demo

  otel-collector:
    image: otel/opentelemetry-collector-contrib:latest
    volumes:
      - ./otel_conf/config.yaml:/etc/otelcol-contrib/config.yaml # OpenTelemetry Collector の設定ファイルをマウントします
    ports:
      - "4317:4317" # OTLP gRPC レシーバー
    networks:
      - nginx-otel-demo

  backend-api:
    build:
      context: ./backend
      dockerfile: Dockerfile
    environment:
      - NODE_ENV=production
    ports:
      - "7001:7001"
    networks:
      - nginx-otel-demo

networks:
  nginx-otel-demo:
    driver: bridge
EOF

ステップ 7: サービスの起動

1. nginx-otel-demo ディレクトリで次のコマンドを実行します。

   docker compose up -d

   想定される出力：

   ngx_otel_module V0.1.2 以降

   [+] Running 4/4
    ✔ Network nginx-otel-demo_nginx-otel-demo       Created
    ✔ Container nginx-otel-demo-nginx-1             Started
    ✔ Container nginx-otel-demo-backend-api-1        Started

   ngx_otel_module V0.1.1 以前

   [+] Running 4/4
    ✔ Network nginx-otel-demo_nginx-otel-demo       Created
    ✔ Container nginx-otel-demo-nginx-1              Started
    ✔ Container nginx-otel-demo-backend-api-1         Started
    ✔ Container nginx-otel-demo-otel-collector-1      Started

2. バックエンドサービスにアクセスします。

   curl http://localhost:80/hello

   想定される出力：

   {"code":200,"msg":"success"}

3. Managed Service for OpenTelemetry コンソールにログインして、NGINX とバックエンドサービスのトレースを表示します。

   この例では、[Applications] ページで nginx が NGINX のアプリケーション名として表示され、バックエンドサービスの名前は ot-nodejs-demo です。