opentracing/nginx-opentracing

NGINX OpenTracing 插件 Docker 镜像

镜像概述与主要用途

本镜像为集成了OpenTracing插件的NGINX Docker镜像，旨在使NGINX服务器能够基于OpenTracing标准对其处理的HTTP请求实施分布式追踪。通过该镜像，用户可轻松为NGINX服务添加分布式追踪能力，实现跨服务请求的追踪与监控。

核心功能与特性

• OpenTracing标准支持：遵循OpenTracing规范，兼容各类OpenTracing实现（如Jaeger、Zipkin等）
• 分布式追踪能力：为NGINX处理的请求生成、传播追踪上下文（包含trace ID、span ID等关键信息）
• 请求追踪集成：自动或配置式地为流经NGINX的HTTP请求创建追踪span，记录请求处理详情
• 上下文传播：支持通过HTTP头（如Traceparent）在服务间传递追踪上下文，实现端到端追踪

使用场景与适用范围

• 微服务架构：作为反向代理或API网关时，追踪跨服务的请求流转路径
• 分布式系统监控：监控请求在NGINX节点的处理延迟、错误率等关键指标
• 问题排查与调试：通过追踪数据定位跨服务请求中的性能瓶颈或异常点
• OpenTracing生态集成：需与现有基于OpenTracing构建的分布式追踪系统对接的环境

使用方法与配置说明

基本运行

使用以下命令启动容器（需替换[镜像名称]为实际镜像标签）：

bash
docker run -d --name nginx-opentracing -p 80:80 [镜像名称]

配置OpenTracing插件

需通过自定义NGINX配置文件启用并配置OpenTracing功能，建议通过-v参数挂载配置文件：

1. 准备配置文件

创建nginx.conf（示例）：

nginx
worker_processes auto;

events {
    worker_connections 1024;
}

http {
    include /etc/nginx/mime.types;
    default_type application/octet-stream;

    # 加载OpenTracing模块
    load_module modules/ngx_http_opentracing_module.so;

    # 全局OpenTracing配置
    opentracing on;
    # 指定追踪器配置文件路径（需挂载到容器内）
    opentracing_tracer_config /etc/nginx/opentracing-config.json;
    # 为所有请求创建追踪span
    opentracing_trace_locations on;
    # 传播追踪上下文（通过HTTP头）
    opentracing_propagate_context;

    server {
        listen 80;
        server_name localhost;

        location / {
            # 可选：为特定路径覆盖追踪配置
            # opentracing_trace_locations on;
            proxy_pass http://backend-service;
        }
    }
}

创建追踪器配置文件（以Jaeger为例，opentracing-config.json）：

json
{
    "service_name": "nginx-proxy",
    "sampler_type": "const",
    "sampler_param": 1,
    "local_agent": {
        "reporting_host": "jaeger-agent",
        "reporting_port": 6831
    }
}

2. 启动容器并挂载配置

bash
docker run -d --name nginx-opentracing \
  -p 80:80 \
  -v $(pwd)/nginx.conf:/etc/nginx/nginx.conf:ro \
  -v $(pwd)/opentracing-config.json:/etc/nginx/opentracing-config.json:ro \
  [镜像名称]

关键配置参数说明

• opentracing on|off：全局启用/禁用OpenTracing（默认off）
• opentracing_tracer_config <path>：指定追踪器配置文件路径（JSON格式）
• opentracing_trace_locations on|off：是否为所有请求自动创建span（默认off，需显式启用）
• opentracing_propagate_context：启用追踪上下文传播（通过HTTP头传递trace ID等）
• 追踪器配置文件：根据使用的追踪系统（Jaeger、Zipkin等）调整，具体参数参考对应追踪器文档

与追踪系统集成

需确保NGINX容器可访问追踪系统的agent或collector（如Jaeger Agent、Zipkin Server），可通过--link或Docker网络实现容器间通信。