Managed Service for OpenTelemetry:OpenTelemetry を使用して NGINX のトレース分析を実行する

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

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

  NGINX OTel モジュールバージョン ≥ 0.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;         # トレースコンテキストをダウンストリームサービスに挿入
      ...
  }

  NGINX OTel モジュールバージョン ≤ 0.1.1

  説明

  NGINX の構成ファイルで次の 2 つの変数を置き換えます:

  • ${OTEL_COLLECTOR_GRPC_RECEIVER_ENDPOINT}: OpenTelemetry Collector が gRPC 経由でレポートされたデータを受信するために使用するエンドポイント。例: localhost:4317。このエンドポイントは、このトピックの「前提条件」セクションで Managed Service for OpenTelemetry コンソールから取得した gRPC エンドポイントではありません。

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

  load_module modules/ngx_otel_module.so; # ngx_otel_module をロード
  ...
  http {
      ...
  
      otel_exporter {
          endpoint ${OTEL_COLLECTOR_GRPC_RECEIVER_ENDPOINT}; # OpenTelemetry Collector が gRPC 経由でレポートされたデータを受信するために使用するエンドポイント。例: localhost:4317
      }
  
      otel_trace on;                     # トレースを有効化
      otel_service_name ${SERVICE_NAME};  # アプリケーション名
      otel_trace_context propagate;         # トレースコンテキストをダウンストリームサービスに挿入
      ...
  }

• 単一のロケーションに送信される HTTP リクエストのトレース分析を有効にする

  NGINX OTel モジュールバージョン ≥ 0.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;         # トレースコンテキストをダウンストリームサービスに挿入
  
              ...
          }
      }
  }

  NGINX OTel モジュールバージョン ≤ 0.1.1

  説明

  NGINX の構成ファイルで次の 2 つの変数を置き換えます:

  • ${OTEL_COLLECTOR_GRPC_RECEIVER_ENDPOINT}: OpenTelemetry Collector が gRPC 経由でレポートされたデータを受信するために使用するエンドポイント。例: localhost:4317。このエンドポイントは、このトピックの「前提条件」セクションで Managed Service for OpenTelemetry コンソールから取得した gRPC エンドポイントではありません。

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

  load_module modules/ngx_otel_module.so; # ngx_otel_module をロード
  
  ...
  
  http {
  
      otel_exporter {
          endpoint ${OTEL_COLLECTOR_GRPC_RECEIVER_ENDPOINT}; # OpenTelemetry Collector が gRPC 経由でレポートされたデータを受信するために使用するエンドポイント。例: 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 とバックエンドサービスのトレースは自動的に関連付けられ、統合されたビューが提供されます。

ステップ 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 を作成します。

   NGINX OTel モジュールバージョン ≥ 0.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

   NGINX OTel モジュールバージョン ≤ 0.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 を作成します。

   NGINX OTel モジュールバージョン ≥ 0.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}"
     export 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

   NGINX OTel モジュールバージョン ≤ 0.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 # NGINX OTel モジュールバージョン 0.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

   期待される出力:

   NGINX OTel モジュールバージョン ≥ 0.1.2

   

   NGINX OTel モジュールバージョン ≤ 0.1.1

   

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

   curl http://localhost:80/hello

   期待される出力:

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

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

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