Imagizer Documentation

Appearance

Logging ​

The access log and the application log are the two main logs. The access log has one line per request. The application log records what Imagizer did to serve each request, at a configurable level (debug, info, warn, or error; the default is info and above). Imagizer runs several other log services, listed under Log services.

You can send logs to Syslog, Datadog, or CloudWatch. To read them on the instance, turn on local logging and open http://IMAGIZER_HOST:17006/logs.

Access log ​

The access log records one line per request in an extended combined format.

Nginx Log Format

log_format  main  '$remote_addr - $remote_user [$time_local] '
                  '"$request" $status $body_bytes_sent "$http_referer" '
                  '"$http_user_agent" "$http_x_forwarded_for" '
                  '$host $request_time '
                  '$upstream_http_x_original_filesize $upstream_http_x_original_resolution '
                  '$upstream_http_x_origin_fetch_time $upstream_http_x_original_response_code '
                  '$upstream_http_x_imagizer_server '
                  '$imagizer_request_id';

Example Log Entry

127.0.0.1 user-identifier user [05/Aug/2021:17:44:17 +0000] "GET /image.jpg?width=200 HTTP/1.1" 200 24000 "https://example.com" "Mozilla/5.0..." "127.0.0.1, 127.0.0.2, 127.0.0.3" xxxxx.imagizer.com 0.320 988376 2000x2000 292 200 10.0.1.42 b0395187a1475b96465c0c329c308d8f

A - in a field means the value was missing.

  • 127.0.0.1 is the IP address of the client (remote host) that made the request.
  • user-identifier is the RFC 1413 identity of the client. Usually -.
  • user is the userid of the person requesting the document. Usually - unless the request used HTTP basic authentication.
  • [05/Aug/2021:17:44:17 +0000] is the date, time, and time zone when the server received the request, by default in strftime format %d/%b/%Y:%H:%M:%S %z.
  • "GET /image.jpg?width=200 HTTP/1.1" is the request line from the client. The method GET, /image.jpg?width=200 the resource requested, and HTTP/1.1 the HTTP protocol.
  • 200 is the HTTP status code returned to the client. 2xx is a successful response, 3xx a redirection, 4xx a client error, and 5xx a server error.
  • 24000 is the size of the object returned to the client, in bytes.
  • https://example.com is the HTTP Referrer URL.
  • "Mozilla/5.0..." is the user agent from the client.
  • "127.0.0.1, 127.0.0.2, 127.0.0.3" is the X-Forwarded-For header chain of IP addresses.
  • xxxxx.imagizer.com is the hostname of the request.
  • 0.320 is the total request processing time in seconds.
  • 988376 is the file size in bytes of the origin image before processing.
  • 2000x2000 is the resolution of the origin image before processing.
  • 292 is the fetch time in milliseconds from the origin image storage.
  • 200 is the HTTP status code from the image origin fetch.
  • 10.0.1.42 is the IP of the backend node that processed the request (the X-Imagizer-Server value), stamped by the load balancer. It is - only when no backend was involved: health checks, errors, and responses served directly by the front node (for example a 503 when all backends are down). In a cluster it links the access line to the application log on that node.
  • b0395187a1475b96465c0c329c308d8f is the request trace ID, shared with the application log, where it appears as rid=.

Request trace ID ​

Every request gets a trace ID. It appears as the last field of each access log line, and as rid=<id> on every application log line. If the request arrives with an X-Request-Id header (set by a CDN or an upstream proxy), Imagizer reuses it so the same ID stays with the request through each hop. If there is no such header, Imagizer generates one. Imagizer also returns the ID to the client in the X-Request-Id response header.

The same ID is on the access line and on every application log line for the request, including on cache hits and 404s. Searching your logs for one ID gives you the full history of a single request. In a cluster the ID also lets you line up the access and application logs even if they were written on different nodes.

Origin fetch failures ​

When Imagizer cannot fetch an image from the origin, the application log records a WARNING with curl's full view of the attempt: the origin URL, the failure status, the transfer timings, and whatever the origin sent back.

Example: S3 returned a 503

10.0.1.42 2026-06-12T04:49:24.404778+00:00 WARNING /images/photo.png?width=200 origin fetch fail: http://s3.amazonaws.com/my-bucket/images/photo.png http_code: 503 curl_error: 0   curl_info: {"url":"http:\/\/s3.amazonaws.com\/my-bucket\/images\/photo.png","content_type":"application\/xml","http_code":503,"header_size":336,"request_size":284,"filetime":-1,"ssl_verify_result":0,"redirect_count":0,"total_time":0.001072,"namelookup_time":1.4e-5,"connect_time":0.000504,"pretransfer_time":0.000531,"size_upload":0,"size_download":0,"speed_download":0,"speed_upload":0,"download_content_length":0,"upload_content_length":-1,"starttransfer_time":0.001001,"redirect_time":0,"redirect_url":"","primary_ip":"52.216.0.10","certinfo":[],"primary_port":80,"local_ip":"10.0.1.42","local_port":51924,"http_version":2,"protocol":1,"ssl_verifyresult":0,"scheme":"HTTP","appconnect_time_us":0,"connect_time_us":504,"namelookup_time_us":14,"pretransfer_time_us":531,"redirect_time_us":0,"starttransfer_time_us":1001,"total_time_us":1072} response_headers: {"status":["HTTP\/1.1 503 Service Unavailable"],"headers":{"Date":"Fri, 12 Jun 2026 04:49:24 GMT","Connection":"close","x-amz-id-2":"EXAMPLEid2aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789EXAMPLE","x-amz-request-id":"EXAMPLE0123456789","Content-Type":"application\/xml","Server":"AmazonS3","Content-Length":"0"}} rid=7f3a9c2b1d4e5f60718293a4b5c6d7e8

Example: the transfer timed out mid-download

10.0.1.43 2026-06-12T04:49:42.671837+00:00 WARNING /images/large-photo.png?width=200 origin fetch fail: http://s3.amazonaws.com/my-bucket/images/large-photo.png http_code: 504 curl_error: 28 Operation timed out after 15000 milliseconds with 1148511 out of 6015162 bytes received  curl_info: {"url":"http:\/\/s3.amazonaws.com\/my-bucket\/images\/large-photo.png","content_type":"image\/png","http_code":200,"header_size":417,"request_size":284,"filetime":-1,"ssl_verify_result":0,"redirect_count":0,"total_time":15.000675,"namelookup_time":1.5e-5,"connect_time":0.000692,"pretransfer_time":0.000719,"size_upload":0,"size_download":1148511,"speed_download":76567,"speed_upload":0,"download_content_length":6015162,"upload_content_length":-1,"starttransfer_time":1.499749,"redirect_time":0,"redirect_url":"","primary_ip":"52.216.0.11","certinfo":[],"primary_port":80,"local_ip":"10.0.1.43","local_port":44432,"http_version":2,"protocol":1,"ssl_verifyresult":0,"scheme":"HTTP","appconnect_time_us":0,"connect_time_us":692,"namelookup_time_us":15,"pretransfer_time_us":719,"redirect_time_us":0,"starttransfer_time_us":1499749,"total_time_us":15000675} response_headers: {"status":["HTTP\/1.1 200 OK"],"headers":{"x-amz-id-2":"EXAMPLEid2aBcDeFgHiJkLmNoPqRsTuVwXyZ9876543210EXAMPLE","x-amz-request-id":"EXAMPLE9876543210","Date":"Fri, 12 Jun 2026 04:49:28 GMT","Last-Modified":"Thu, 04 Jun 2026 04:09:42 GMT","ETag":"\"a1b2c3d4e5f67890a1b2c3d4e5f67890\"","x-amz-server-side-encryption":"AES256","Accept-Ranges":"bytes","Content-Type":"image\/png","Content-Length":"6015162","Server":"AmazonS3","Connection":"close"}} rid=0a1b2c3d4e5f60718293a4b5c6d7e8f9

TIP

Imagizer returns a 504 to the client when the origin fetch times out, as in the second example.

The line starts with the node's IP, the timestamp, the log level, and the requested path, then:

  • origin fetch fail: is the exact origin URL Imagizer fetched.
  • http_code is the status Imagizer assigned to the failure. For a transport failure (timeout, DNS, connect) this is a mapped code; the status the origin actually returned, if any, is inside curl_info.
  • curl_error is the curl error number and message. 0 means there was no transport error and the origin's HTTP status itself was the failure. In the timeout example, 28 shows the origin answered 200 OK and the download started, but did not finish within the limit.
  • curl_info is curl's transfer report. It is always present, so a fetch that never got an HTTP response still records the DNS, connect, and TLS timings and the resolved origin IP. The useful keys:
    • http_code — what the origin actually returned.
    • namelookup_time, connect_time, pretransfer_time, starttransfer_time, total_time — seconds from the start of the fetch until DNS resolved, TCP connected, the request was ready to send, the first byte arrived, and the transfer ended. The *_time_us keys repeat them in microseconds.
    • size_download and download_content_length — bytes received vs. what the origin advertised. Received short of advertised means the transfer was cut off.
    • speed_download — average download speed in bytes per second.
    • primary_ip and primary_port — the origin server the node connected to.
    • local_ip and local_port — the node's side of the connection.
    • redirect_count and redirect_url — how many redirects curl followed, and where the last one pointed.
    • ssl_verify_result — 0 means the origin's TLS certificate verified (plain HTTP fetches also log 0).
  • response_headers New (v14.5-90.15) is the origin's status line and headers. For S3, send x-amz-request-id and x-amz-id-2 to AWS support to trace the request on their side; the status distinguishes S3 throttling (503) from an outage (500).
  • response_body is the origin's error body, when it sent one (S3 returns an XML error document).
  • rid= is the request trace ID.

Logging in a cluster ​

In a cluster a request first reaches a front node, which load balances it to a backend node that processes the image. That backend may be a different machine than the front, or it may be the same one. When it is a different machine, the request's two log lines land in different places: the access line on the front node, the application line on the backend node.

ClientrequestFront node10.0.1.5load balanceBackend node10.0.1.42writes the access lineimagizer_access… 10.0.1.42 <id>writes the application lineimagizer_app… rid=<id>same <id>

To pair the two lines, read the last field of the access line. That X-Imagizer-Server value (10.0.1.42 above) is the backend node that processed the request and wrote the application log. Find that node, then search its application log for the shared rid= request trace ID. The field is - only for responses the front node serves itself (health checks, errors, all-backends-down 503s).

If one node both receives and processes the request, both lines are on that node.

Log services ​

  • imagizer_access The access logs in the combined format.
  • imagizer_access_err The access error log. Formatted as a standard Nginx error log.
  • imagizer_app The Imagizer application log.
  • imagizer_system The Imagizer system log.
  • imagizer_stats_collector The Imagizer stats collection log.
  • imagizer_vision The Imagizer computer vision service log (face/eye detection and red-eye).
  • nginx_varn An internal access log. Used for debugging. (default: disabled)
  • nginx_varn_err An internal access error log. Used for debugging. (default: disabled)
  • imagizer_admin_access The admin access logs (from port 17006) in the combined format.
  • imagizer_admin_access_err The admin access error log. Formatted as a standard Nginx error log.
  • imagizer_health The health check agent logs. Its warnings and errors also appear in the imagizer_system log, so health problems are visible even if you do not follow this log.
  • imagizer_health_access The access logs for /health checks. (default: disabled)
  • imagizer_haproxy The load balancer (HAProxy) request log, in the standard HAProxy HTTP log format plus the request trace ID (rid=). One line per request as the load balancer saw it: the timing breakdown (queue wait vs. backend response time), the backend node selected, the retry count, and the termination state flags. Useful for debugging 502/503/530 responses, latency the application log cannot account for, retries, and cluster nodes dropping out of rotation. The access log records only the final status and total time, and a request that no backend processed leaves no application log line at all. (default: disabled)

Configuration ​

See the logging config reference for the full list of options, including log levels, local logging, and the Syslog, Datadog, and CloudWatch destinations.

© Copyright 2025 Nventify, Inc.