監視 NGINX

NGINX 的度量值

對於 NGINX 度量值集合， Instana 使用 ngx_http_stub_status_module 進行遠端度量值集合。 若要啟用此集合，請確定模組已啟用或可用，並在 NGINX 配置開頭新增下列 Snippet:

location /nginx_status {
  stub_status  on;
  access_log   off;
  allow 127.0.0.1; # Or the Remote IP of the Instana Host Agent
  deny  all;
}

依預設， Instana 代理程式會在任何可用的程序引數中搜尋配置檔的位置; 否則會撤回至 /etc/nginx/nginx.conf。

附註: 當 Instana 代理程式在 Kubernetes 叢集中執行時，請確保容許使用 allow <host-ip-address> 配置來執行代理程式的主機 IP 位址。

NGINX Plus 的度量值

若要啟用 NGINX Plus 度量監視，請確定 ngx_http_api_module (*) 已安裝或可用，並新增下列區塊以啟用模組:

location /api {
    api write=off;
    allow 127.0.0.1; # Or the Remote IP of the Instana Host Agent
    deny all;
}

Kubernetes Ingress NGINX 的度量值

從 Kubernetes Ingress NGINX 0.23.0 版開始，已停用在埠 18080 上接聽的伺服器。 若要讓 Instana 監視此 NGINX 實例，請將下列 Snippet 新增至 Configmap ，以還原伺服器:

http-snippet: |
  server {
    listen 18080;

    location /nginx_status {
      stub_status on;
      access_log  off;
      allow 127.0.0.1; # Or the Remote IP of the Instana Host Agent
      deny  all;
    }

    location / {
      return 404;
    }
  }

如需相關資訊，請參閱 NGINX Ingress 版本注意事項。

1. 下載二進位檔

NGINX HTTP 追蹤模組是以 nginx-opentracing v0.22.1 模組為基礎，具有可啟用更多功能及更容易使用的自訂作業。

NGINX 分散式追蹤二進位檔 頁面上提供受支援 NGINX 發行套件的 Instana 二進位檔下載鏈結。

2. 複製二進位檔

在前一個步驟中下載並解壓縮的兩個二進位檔必須放在 NGINX 處理程序可以存取的檔案系統上，包括位置和檔案許可權。

如果 NGINX 直接在作業系統上執行，而不是在儲存器中執行，通常最好將兩個 Instana 二進位檔複製到包含其他 NGINX 模組的資料夾中。 您可以執行 nginx -V 指令來尋找 NGINX 預期模組所在的位置，並尋找 --modules-path 配置選項，例如，請參閱 StackOverflow上的這個回應。

在容器化環境中，此作法可能表示將它們新增至容器映像檔，或將檔案以磁區形式裝載至容器; 例如，請參閱 Docker 的 連結裝載 文件，或如何 將磁區裝載至 Kubernetes中的 Pod。

3. 編輯 NGINX 配置

每個受支援的 NGINX 版本都有兩個分開的壓縮保存檔，一個用於 GLIBC ，另一個用於 MUSL。 GLIBC 適用於所有 Linux Distros ，但 Alpine除外，它需要 MUSL。

在如下配置 NGINX 之前，您需要將下載的模組重新命名為 modules/ngx_http_opentracing_module.so ，或根據下載的模組名稱來變更 nginx.conf 檔中的配置行 load_module modules/ngx_http_opentracing_module.so; 。 例如，將配置行 load_module modules/ngx_http_opentracing_module.so; 變更為 load_module modules/musl-nginx-1.23.3-ngx_http_ot_module.so;。

# The following line adds the basic module Instana uses to get tracing data.
# It is required that you use the version of this module built by Instana,
# rather than the one shipped in many NGINX distros, as there are some
# modifications in the Instana version that are required for tracing to work
load_module modules/ngx_http_opentracing_module.so;

# Whitelists environment variables used for tracer configuration to avoid
# that NGINX wipes them. This is only needed if instana-config.json
# should contain an empty configuration with "{}" inside to do the
# configuration via these environment variables instead.
env INSTANA_SERVICE_NAME;
env INSTANA_AGENT_HOST;
env INSTANA_AGENT_PORT;
env INSTANA_MAX_BUFFERED_SPANS;
env INSTANA_DEV;

events {}

error_log /dev/stdout info;

http {
  error_log /dev/stdout info;

  # The following line loads the Instana libsinstana_sensor library, that
  # gets the tracing data from ngx_http_opentracing_module.so and converts
  # them to Instana AutoTrace tracing data.
  # The content of instana-config.json is discussed as follows.
  opentracing_load_tracer /usr/local/lib/libinstana_sensor.so /etc/instana-config.json;

  # Propagates the active span context for upstream requests.
  # Without this configuration, the Instana trace will end at
  # NGINX, and the systems downstream (those to which NGINX
  # routes the requests) monitored by Instana will generate
  # new, unrelated traces
  opentracing_propagate_context;

  # Optional: This logs subrequests like e.g. created by the `auth_request`
  # directive so that authorization requests can be traced.
  log_subrequest on;

  # If you use upstreams, Instana will automatically use them as endpoints,
  # and it is really cool :-)
  upstream backend {
    server server-app:8080;
  }

  server {
    error_log /dev/stdout info;
    listen 8080;
    server_name localhost;

    location /static {
      root /www/html;
    }

    location ^~ /api {
      proxy_pass http://backend;
    }

    location ^~ /other_api {
      proxy_set_header X-AWESOME-HEADER "truly_is_awesome";

      # Using the `proxy_set_header` directive voids for this
      # location the `opentracing_propagate_context` defined
      # at the `http` level, so here it needs to be set again.
      # It needs to be set for every block where `proxy_set_header`
      # is found. This can also be the case at `server` level.
      opentracing_propagate_context;

      proxy_pass http://backend;
    }
  }
}

特殊案例 opentracing_propagate_context:

除了主要 (http) 層次之外，還需要針對每個設定 proxy_set_header 指引的區塊 (server 或 location) 新增 opentracing_propagate_context 指引。 原因是 OpenTracing 環境定義傳播在內部以 proxy_set_header 為基礎，否則它會被它作廢。 這是 NGINX 模組 API 的限制。

以下是 instana-config.json的範例:

{
  "service": "nginxtracing_nginx", # Change this line to give your NGINX service a different name in Instana
  "agent_host": <host_agent_address>, # Change this line with the IP address or DNS name of the Instana agent on the same host as your NGINX process
  "agent_port": 42699, # This is the default, and you should never change it unless instructed by the Instana support
  "max_buffered_spans": 1000
}

上述 Snippet 中的配置表示下列:

• service: 將在 Instana 後端中與此 NGINX 程序相關聯的名稱。 如果未指定，則會根據例如 HTTP 主機名稱或其他方法來計算服務名稱。
• agent_host: 本端主機代理程式的 IP 位址或 DNS 名稱。 您必須變更此配置，以符合與 NGINX 程序相同的主機上 Instana 代理程式的網路名稱。
• agent_port:NGINX 追蹤延伸將嘗試聯絡主機代理程式的埠。 請注意，此埠 不可配置 代理程式端。 NGINX 追蹤延伸可讓您在設定需要埠轉遞或埠對映時配置它。
• max_buffered_spans:NGINX 追蹤延伸將在本端保留的跨距數量上限 (每個要求一個) ，然後再將它們清除至代理程式; 預設值為 1000。 NGINX 追蹤延伸一律會清除每秒本端緩衝的跨距。 當 NGINX 伺服器每秒處理的要求數超過 1000 個時，此設定可讓您減少本端緩衝量，而且您想要透過更快清除追蹤資料來減少 NGINX 伺服器的記憶體覆蓋區。

替代方案是透過環境變數來配置追蹤程式。 這些優先，但仍需要檔案 instana-config.json 。 請執行下列動作:

• 將空的配置 {} 放入 instana-config.json
• 執行 NGINX 配置中環境變數的白名單，如上所示
• 在啟動 NGINX 之前設定環境變數

將 Instana 代理程式主機設為 Kubernetes 叢集中的主機 IP 時，此方法特別有用。

下列範例 Kubernetes 部署 YAML 組件顯示此方法:

        env:
        - name: INSTANA_SERVICE_NAME
          value: "nginxtracing_nginx"
        - name: INSTANA_AGENT_HOST
          valueFrom:
            fieldRef:
              fieldPath: status.hostIP

如需相關資訊，請參閱 環境變數參照。

4. 重新啟動或重新載入

透過傳送 reload 指令，重新啟動 NGINX 處理程序或 觸發配置重新載入 。

支援 W3C 追蹤環境定義

從 NGINX Tracer 1.8.0開始，支援傳播 W3C 追蹤環境定義標頭。

支援其他 NGINX OpenTracing 模組建置

不支援使用來自 3rd 的 NGINX OpenTracing 模組建置，包括 NGINX 本身支援的那些建置。 需要 NGINX OpenTracing 模組的 Instana 建置的原因是技術: 不支援自行編譯 (亦即，您建置自己的版本) ，因為這會過度地造成 Instana 支援的壓力，無法嘗試在完全不同且無法預期的設定中找出編譯程序中發生的錯誤; 同樣地，不支援 F5 所提供的模組， 因為那些缺乏 Instana 追蹤所需的功能，以及那些使用動態鏈結至標準 C++ 程式庫且在許多情況下會導致 segfault的功能。 實際上，為了避免 segfault ，已建置 Instana NGINX OpenTracing 模組，包括靜態鏈結的標準 C++ 程式庫，用於統一測試，而且即使在較舊的發行套件上，也適用於現代 C++ 程式碼。