This document contains instructions on how to set up OpenTelemetry instrumentation in your NGINX Web Servers and send Traces, Metrics and Logs to SigNoz.
Send traces to SigNoz Cloud
Based on your application environment, you can choose the setup below to send traces to SigNoz Cloud.
From VMs, there are two ways to send data to SigNoz Cloud.
Send traces directly to SigNoz cloud
Step 1 : Install NGINX module
apt-get update && apt-get install -y nginx-otel-module
apt-get update && apt-get install -y unzip
apt-get install nginx
systemctl start nginx
wget https://github.com/open-telemetry/opentelemetry-cpp-contrib/releases/download/webserver%2Fv1.1.0/opentelemetry-webserver-sdk-x64-linux.tgz -P /opt
cd /opt && tar xvfz opentelemetry-webserver-sdk-x64-linux.tgz
cd /opt/opentelemetry-webserver-sdk && ./install.sh
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/opentelemetry-webserver-sdk/sdk_lib/lib
echo "load_module /opt/opentelemetry-webserver-sdk/WebServerModule/Nginx/1.26.0/ngx_http_opentelemetry_module.so;\n$(cat /etc/nginx/nginx.conf)" > /etc/nginx/nginx.conf
Step 2: Configure NGINX
Add the following to top of your nginx.conf file, this will load the installed module.
load_module modules/ngx_http_opentelemetry_module.so;
http {
opentelemetry_config /etc/nginx/opentelemetry_config.yaml;
}
Step 3: Make OpenTelemetry configuration file
Modify the /etc/nginx/opentelemetry_config.yaml with following:
service_name: <service-name>
sampler:
type: always_on
exporter:
otlp:
endpoint: https://ingest.<region>.signoz.cloud:443/v1/traces
headers:
signoz-ingestion-key: <your-ingestion-key>
Verify these values:
<region>: Your SigNoz Cloud region<your-ingestion-key>: Your SigNoz ingestion key<service-name>: A descriptive name for your service (e.g.,my-nginx-app).
Step 4: Restart NGINX
Restart nginx using the below command:
systemctl restart nginx
The traces should start getting generated.
Send traces via OTel Collector binary
Step 1. Install OTel Collector binary
OTel Collector binary helps to collect logs, hostmetrics, resource and infra attributes.
You can find instructions to install OTel Collector binary here in your VM.
Step 2 : Install NGINX module
apt-get update && apt-get install -y nginx-otel-module
apt-get update && apt-get install -y unzip
apt-get install nginx
systemctl start nginx
wget https://github.com/open-telemetry/opentelemetry-cpp-contrib/releases/download/webserver%2Fv1.1.0/opentelemetry-webserver-sdk-x64-linux.tgz -P /opt
cd /opt && tar xvfz opentelemetry-webserver-sdk-x64-linux.tgz
cd /opt/opentelemetry-webserver-sdk && ./install.sh
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/opentelemetry-webserver-sdk/sdk_lib/lib
echo "load_module /opt/opentelemetry-webserver-sdk/WebServerModule/Nginx/1.26.0/ngx_http_opentelemetry_module.so;\n$(cat /etc/nginx/nginx.conf)" > /etc/nginx/nginx.conf
Step 3: Configure NGINX
Add the following to top of your nginx.conf file, this will load the installed module.
load_module modules/ngx_http_opentelemetry_module.so;
http {
opentelemetry_config /etc/nginx/opentelemetry_config.yaml;
}
Step 4: Make OpenTelemetry configuration file
Modify the /etc/nginx/opentelemetry_config.yaml with following:
service_name: <service-name>
sampler:
type: always_on
exporter:
otlp:
endpoint: http://localhost:4318/v1/traces
Verify these values:
<service-name>: A descriptive name for your service (e.g.,my-nginx-app).
Step 5: Restart NGINX
Restart nginx using the below command:
systemctl restart nginx
The traces should start getting generated.
Step 1: Create Dockerfile
Here is a sample Dockerfile that installs NGINX 1.26.0 with OpenTelemetry WebServer SDK:
FROM nginx:1.26.0
RUN apt-get update && apt-get install -y unzip
ADD https://github.com/open-telemetry/opentelemetry-cpp-contrib/releases/download/webserver%2Fv1.1.0/opentelemetry-webserver-sdk-x64-linux.tgz /opt
RUN cd /opt && \
unzip opentelemetry-webserver-sdk-x64-linux.tgz.zip && \
tar xvfz opentelemetry-webserver-sdk-x64-linux.tgz
RUN cd /opt/opentelemetry-webserver-sdk && ./install.sh
ENV LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/opentelemetry-webserver-sdk/sdk_lib/lib
RUN echo "load_module /opt/opentelemetry-webserver-sdk/WebServerModule/Nginx/1.26.0/ngx_http_opentelemetry_module.so;\n$(cat /etc/nginx/nginx.conf)" > /etc/nginx/nginx.conf
COPY opentelemetry_module.conf /etc/nginx/conf.d
Step 2: Create configuration file
Create the opentelemetry_module.conf file. This configuration enables OpenTelemetry and exports traces directly to SigNoz Cloud
NginxModuleEnabled ON;
NginxModuleOtelSpanExporter otlp;
NginxModuleOtelExporterEndpoint https://ingest.<region>.signoz.cloud:443;
NginxModuleOtelSpanProcessor batch;
NginxModuleOtelSampler AlwaysOn;
NginxModuleOtelExporterOtlpHeaders signoz-ingestion-key=<your-ingestion-key>;
NginxModuleServiceName <service-name>;
NginxModuleServiceNamespace <service-namespace>;
NginxModuleServiceInstanceId <service-instance-id>;
NginxModuleResolveBackends ON;
NginxModuleTrustIncomingSpans ON;
NginxModuleTraceAsError ON;
Verify these values:
<region>: Your SigNoz Cloud region<your-ingestion-key>: Your SigNoz ingestion key<service-name>: A descriptive name for your service (e.g.,my-nginx-app).<service-namespace>: A namespace for the service (e.g.,my-team).<service-instance-id>: A unique identifier for this instance (e.g.,nginx-prod-1).
Step 3: Build and run your Docker image
docker build -t nginx-otel .
docker run -p 8080:80 nginx-otel
You can access the application at http://localhost:8080 .
Send Traces to Self-Hosted SigNoz
Step 1 : Install NGINX module
apt-get update && apt-get install -y nginx-otel-module
apt-get update && apt-get install -y unzip
apt-get install nginx
systemctl start nginx
wget https://github.com/open-telemetry/opentelemetry-cpp-contrib/releases/download/webserver%2Fv1.1.0/opentelemetry-webserver-sdk-x64-linux.tgz -P /opt
cd /opt && tar xvfz opentelemetry-webserver-sdk-x64-linux.tgz
cd /opt/opentelemetry-webserver-sdk && ./install.sh
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/opentelemetry-webserver-sdk/sdk_lib/lib
echo "load_module /opt/opentelemetry-webserver-sdk/WebServerModule/Nginx/1.26.0/ngx_http_opentelemetry_module.so;\n$(cat /etc/nginx/nginx.conf)" > /etc/nginx/nginx.conf
Step 2: Configure NGINX
Add the following to top of your nginx.conf file, this will load the installed module.
load_module modules/ngx_http_opentelemetry_module.so;
http {
opentelemetry_config /etc/nginx/opentelemetry_config.yaml;
}
Step 3: Make OpenTelemetry configuration file
Modify the /etc/nginx/opentelemetry_config.yaml with following:
service_name: <service-name>
sampler:
type: always_on
exporter:
otlp:
endpoint: <SIGNOZ_URL>
Verify these values:
<SIGNOZ_URL>: Your self-hosted SigNoz endpoint (e.g.,http://localhost:4318/v1/traces).<service-name>: A descriptive name for your service (e.g.,my-nginx-app).
Step 4: Restart NGINX
Restart nginx using the below command:
systemctl restart nginx
The traces should start getting generated.
Send metrics to SigNoz Cloud
Step 1. Install OTel Collector binary
OTel Collector binary helps to collect logs, hostmetrics, resource and infra attributes.
You can find instructions to install OTel Collector binary here in your VM.
Step 2. Add /status route to nginx.conf
Add the following block to your nginx.conf, this adds /status route to the NGINX server. This will serve the metrics.
server {
location /status {
stub_status on;
}
Step 3. Modify config.yaml of Otel Collector
Add the following in config.yaml of otel-col.
receivers:
nginx:
endpoint: 'http://localhost:80/status'
collection_interval: 10s
service:
telemetry:
metrics:
level: basic
pipelines:
metrics:
receivers: [otlp, nginx]
processors: [batch]
exporters: [otlp]
logs:
receivers: [filelog]
processors: [attributes]
exporters: [otlp]
Step 4. Run the NGINX server
Execute the following command to run otel-col in background.
./otelcol-contrib --config ./config.yaml &> otelcol-output.log & echo "$\!" > otel-pid
Send logs to SigNoz Cloud
Logs for NGINX are enabled and stored on the path /var/log/nginx/access.log. We can export the logs to SigNoz as follows.
Step 1. Install OTel Collector binary
OTel Collector binary helps to collect logs, hostmetrics, resource and infra attributes.
You can find instructions to install OTel Collector binary here in your VM.
Step 2. Modify config.yaml of Otel Collector
Add the following in config.yaml of otel-col.
filelog:
include:
- /var/log/nginx/*.log
Step 3. Run the NGINX server
Execute the following command to run otel-col in background.
./otelcol-contrib --config ./config.yaml &> otelcol-output.log & echo "$\!" > otel-pid
Sample NGINX Application
We have included a sample NGINX Server at Sample NGINX Server Github Repo
Monitor NGINX Logs
Follow this documentation for monitoring NGINX logs.