diff --git a/README.md b/README.md
index 723e544..043f0cc 100644
--- a/README.md
+++ b/README.md
@@ -30,7 +30,9 @@ Since we are using [Open Policy Agent](https://www.openpolicyagent.org/) (aka `O
 
 ### Log Format
 
-The docker image provides default log format (`/etc/nginx/log_format`). It's not possible to extend the log format, so if you'd want to add/remove certain fields you have to override it.
+The docker image provides a default JSON log format (`/etc/nginx/log_format.conf`). It can't be extended in place, so adding or removing fields means overriding the whole file.
+
+When the Fluent Bit sidecar is enabled, the chart renders a second, human-readable format alongside it: `kubectl logs` gets the readable one while the JSON format goes to the sidecar. Controlled by `fluentbit.accessLog.stdoutReadable`.
 
 ## Helm Chart
 
@@ -46,6 +48,8 @@ There's an option to dynamically add annotations to the pod. You might find it u
 
 There's support for instrumenting NGINX with OpenTelemetry (currently only for tracing). Simply the relevant parameters in the `values.yaml` file.
 
+There's also an optional Fluent Bit log-processing sidecar, off by default. When enabled it forwards only the selected access-log statuses and error-log severities to a central OTLP/HTTP endpoint instead of shipping every line, and derives Prometheus metrics from the access log — merged with the NGINX exporter's series onto one `/metrics` endpoint. See the `fluentbit` parameters in [values.md](./helm/values.md).
+
 #### Overriding NGINX configuration files
 
 If you wish to override the default configuration files, you can do it by providing an external ConfigMap and supplying Volumes & VolumeMounts that'll be added to the Deployment.
diff --git a/helm/config/fluent-bit.yaml b/helm/config/fluent-bit.yaml
new file mode 100644
index 0000000..13869a6
--- /dev/null
+++ b/helm/config/fluent-bit.yaml
@@ -0,0 +1,180 @@
+# Fluent Bit configuration, rendered through Helm `tpl` from the chart ConfigMap.
+#
+# YAML, not classic `.conf`: only YAML config supports `processors`, the one way to reach an
+# outgoing record's OTLP resource attributes. Classic config can set log attributes but never
+# resource ones, so every forwarded record would arrive at Loki as `unknown_service`.
+#
+# Fluent Bit's own `fluentbit_metrics` input is deliberately not collected — too noisy.
+{{- $debug := .Values.fluentbit.debug }}
+{{- $stages := ternary $debug.stages (dict) $debug.enabled }}
+
+service:
+  flush: 1
+  daemon: off
+  log_level: {{ $debug.enabled | ternary $debug.logLevel "info" }}
+  # Relative to this file, i.e. the image's own /fluent-bit/etc/parsers.conf (json, syslog, …).
+  parsers_file: parsers.conf
+{{- if .Values.fluentbit.errorLog.enabled }}
+
+# Parses the standard open-source nginx error-log line into structured fields. Format:
+#   2024/01/15 10:23:45 [error] 1234#5678: *90 <message>, client: …, server: …, request: "…"
+# The leading timestamp is optional (some syslog paths strip it), the connection id (*cid) is
+# optional (worker/startup messages omit it), and the client/server/request tail is optional
+# and matched as a unit so a comma inside <message> does not truncate it.
+parsers:
+  - name: nginx_error
+    format: regex
+    regex: '^(?:(?<time>\d{4}/\d{2}/\d{2} \d{2}:\d{2}:\d{2}) )?\[(?<level>\w+)\] (?<pid>\d+)#\d+:(?: \*\d+)? (?<message>.*?)(?:, client: (?<client>[^,]+), server: (?<server>[^,]*), request: "(?<request>[^"]*)".*)?$'
+    time_key: time
+    time_format: '%Y/%m/%d %H:%M:%S'
+    time_keep: off
+{{- end }}
+
+pipeline:
+  inputs:
+    # nginx `access_log syslog:server=127.0.0.1:<port>` delivers the JSON `main` format here.
+    # Parser is mandatory: nginx frames its datagrams as RFC3164 (`<PRI>Mmm dd hh:mm:ss host
+    # tag: msg`), while Fluent Bit's syslog input defaults to syslog-rfc5424 — that mismatch
+    # fails to parse and silently drops every record before any filter runs.
+    - name: syslog
+      tag: nginx.access
+      mode: udp
+      listen: 127.0.0.1
+      port: {{ .Values.fluentbit.accessLog.syslogPort }}
+      parser: syslog-rfc3164
+      buffer_chunk_size: 32k
+      buffer_max_size: 64k
+{{- if .Values.fluentbit.errorLog.enabled }}
+    # Same RFC3164 framing as the access log, so the same explicit parser is required.
+    - name: syslog
+      tag: nginx.error
+      mode: udp
+      listen: 127.0.0.1
+      port: {{ .Values.fluentbit.errorLog.syslogPort }}
+      parser: syslog-rfc3164
+      buffer_chunk_size: 32k
+      buffer_max_size: 64k
+{{- end }}
+{{- if and .Values.fluentbit.accessLog.metrics.enabled .Values.fluentbit.accessLog.metrics.scrapeExporter }}
+    # Scrape the existing nginx-prometheus-exporter so its stub_status gauges merge into the
+    # single /metrics endpoint below (port = the exporter's own mclabels.prometheus.port).
+    - name: prometheus_scrape
+      tag: nginx.metrics.exporter
+      host: 127.0.0.1
+      port: {{ .Values.mclabels.prometheus.port }}
+      metrics_path: /metrics
+{{- end }}
+
+  filters:
+{{- if $stages.received }}
+    # Debug stage `received`: both pipelines straight off the syslog input, before any decoding.
+    # `stdout` is a filter, so it prints the records as they are at this point and passes them on.
+    - name: stdout
+      match_regex: ^nginx\.(access|error)$
+{{- end }}
+    # The syslog message body is the nginx JSON line; decode it so the OTel-shaped fields
+    # (including the nested http.response.status_code) become queryable by the grep filter.
+    - name: parser
+      match: nginx.access
+      key_name: message
+      parser: json
+      reserve_data: off
+{{- if $stages.parsed }}
+    # Debug stage `parsed`: access records after JSON decode. Deliberately ahead of the guard
+    # below, so lines the decode failed on are still visible here (they keep a raw `message`).
+    - name: stdout
+      match: nginx.access
+{{- end }}
+    # Drop records the JSON parser could not decode. log_to_metrics segfaults on a record whose
+    # value_field is missing, so an unparseable line would otherwise crash-loop the sidecar.
+    - name: grep
+      match: nginx.access
+      regex: "$Attributes['http.response.status_code'] ."
+{{- if .Values.fluentbit.accessLog.exclude.enabled }}
+    # Drop health-check / probe traffic before anything downstream sees it, so it neither
+    # inflates the derived metrics nor reaches Loki. Placed after the JSON parser (the matched
+    # field only exists once decoded) and before log_to_metrics.
+    - name: grep
+      match: nginx.access
+      exclude: {{ printf "%s %s" .Values.fluentbit.accessLog.exclude.key .Values.fluentbit.accessLog.exclude.regex | quote }}
+{{- end }}
+{{- if .Values.fluentbit.accessLog.metrics.enabled }}
+    # Derive metrics from the full stream, before grep drops the non-forwarded records, so the
+    # counters cover every request. Overridable via fluentbit.accessLog.metrics.filters (tpl).
+{{- tpl (toYaml .Values.fluentbit.accessLog.metrics.filters) . | nindent 4 }}
+{{- end }}
+    # Keep only the status codes selected by fluentbit.accessLog.forward; drop everything else.
+    # When no forwarding rule is active the regex matches nothing, so all records are dropped.
+    - name: grep
+      match: nginx.access
+      regex: {{ printf "$Attributes['http.response.status_code'] %s" (include "nginx.fluentbit.accessLogRegex" .) | quote }}
+{{- if .Values.fluentbit.maskQueryParams }}
+    # Mask fluentbit.maskQueryParams in the fields that carry the query string: url.query,
+    # url.full and the request line in `Body`. Only the forwarded records need it, and it has to
+    # precede both filters below: the hook would see the raw token, flatten puts Attributes out of
+    # reach. The error pipeline is masked in envelope_error, once its request line is parsed.
+    - name: lua
+      match: nginx.access
+      script: /fluent-bit/etc/metadata.lua
+      call: mask_query_params
+{{- end }}
+{{- if .Values.fluentbit.lua.enabled }}
+    # Operator hook (fluentbit.lua): after the forwarding grep, so the script only sees records
+    # already selected for shipping, and before the flatten filter below, which is what keeps
+    # `record["Attributes"]` reachable from the script.
+    - name: lua
+      match: nginx.access
+      script: /fluent-bit/scripts/custom.lua
+      call: {{ .Values.fluentbit.lua.call }}
+{{- end }}
+{{- if .Values.fluentbit.errorLog.enabled }}
+    # Parse the plaintext nginx error line into structured fields, using the nginx_error parser
+    # defined above. Severity is already filtered at nginx, so no grep.
+    - name: parser
+      match: nginx.error
+      key_name: message
+      parser: nginx_error
+      reserve_data: off
+{{- if $stages.parsed }}
+    # Debug stage `parsed`, error pipeline.
+    - name: stdout
+      match: nginx.error
+{{- end }}
+{{- end }}
+    # Last filter, deliberately: it moves the decoded fields out of the record body into the
+    # record's metadata, after which `$Attributes['…']` accessors (the greps and log_to_metrics
+    # above, and anything supplied through fluentbit.accessLog.metrics.filters) no longer resolve.
+    - name: lua
+      match: nginx.access
+      script: /fluent-bit/etc/metadata.lua
+      call: flatten_attributes
+{{- if .Values.fluentbit.errorLog.enabled }}
+    # Same treatment for the error pipeline, whose records reach here with the nginx_error
+    # parser's field names: rewritten to semconv attributes in metadata + an OTel envelope, so
+    # both outputs below are identical apart from the tag they match.
+    - name: lua
+      match: nginx.error
+      script: /fluent-bit/etc/metadata.lua
+      call: envelope_error
+{{- end }}
+
+  outputs:
+    {{- include "nginx.fluentbit.logsOutput" (dict "ctx" . "match" "nginx.access") | nindent 4 }}
+{{- if .Values.fluentbit.errorLog.enabled }}
+    {{- include "nginx.fluentbit.logsOutput" (dict "ctx" . "match" "nginx.error") | nindent 4 }}
+{{- end }}
+{{- if $debug.enabled }}
+    # Debug: the records handed to the OTLP outputs above, i.e. what actually reaches Alloy once
+    # every filter has run. Always printed while debug is on — out_stdout flushes the process's
+    # stdout buffer, which is what makes the `stdout` filter dumps above appear promptly too.
+    - name: stdout
+      match_regex: ^nginx\.(access|error)$
+{{- end }}
+{{- if .Values.fluentbit.accessLog.metrics.enabled }}
+    # Serve the merged /metrics (log-derived + scraped exporter) on metrics.port.
+    # `match: '*'` is safe — prometheus_exporter only handles metric events.
+    - name: prometheus_exporter
+      match: '*'
+      host: 0.0.0.0
+      port: {{ .Values.fluentbit.accessLog.metrics.port }}
+{{- end }}
diff --git a/helm/config/log_format.conf b/helm/config/log_format.conf
index 8dc82ee..7ad4d74 100644
--- a/helm/config/log_format.conf
+++ b/helm/config/log_format.conf
@@ -28,8 +28,11 @@ log_format main escape=json
         '"mapcolonies.http.upstream_connect_time":"$upstream_connect_time",'
         '"mapcolonies.http.upstream_response_time":"$upstream_response_time",'
         '"mapcolonies.http.upstream_response_length":"$upstream_response_length",'
-        '"mapcolonies.http.upstream_bytes_sent": $upstream_bytes_sent,'
-        '"mapcolonies.http.upstream_bytes_received": $upstream_bytes_received,'
+        # Quoted, unlike the other size fields: nginx writes a bare `-` for these when the
+        # request had no upstream, which is invalid JSON as a number. The record then fails
+        # Fluent Bit's JSON parser and is dropped by the guard grep in config/fluent-bit.yaml.
+        '"mapcolonies.http.upstream_bytes_sent":"$upstream_bytes_sent",'
+        '"mapcolonies.http.upstream_bytes_received":"$upstream_bytes_received",'
         '"mapcolonies.http.upstream_cache_status":"$upstream_cache_status",'
         '"server.address":"$host",'
         '"server.port":"$server_port",'
@@ -53,3 +56,15 @@ log_format main escape=json
     '"InstrumentationScope":"access.log",'
     '"Body":"$request"'
 '}';
+{{- if .Values.fluentbit.enabled }}
+
+# Human-readable (combined-style) access log for `kubectl logs`, augmented with the
+# authenticated client name, request time and upstream status. Written to stdout when
+# fluentbit.accessLog.stdoutReadable is true; the JSON `main` format always goes to
+# Fluent Bit over syslog.
+log_format readable
+'$remote_addr {{ if .Values.authorization.enabled }}$jwt_payload_sub {{ end }}[$time_local] '
+'"$request" $status $body_bytes_sent '
+'"$http_referer" "$http_user_agent" '
+'rt=$request_time upstream_status=$upstream_status';
+{{- end }}
diff --git a/helm/config/metadata.lua b/helm/config/metadata.lua
new file mode 100644
index 0000000..eeea857
--- /dev/null
+++ b/helm/config/metadata.lua
@@ -0,0 +1,148 @@
+-- Rendered through Helm `tpl` for the parameter list below, so no Go-template braces in Lua code.
+-- Parameters carrying credentials (the OPA check reads the client's JWT from a token arg), from
+-- fluentbit.maskQueryParams; an empty list makes mask() a no-op.
+local MASKED_PARAMS = { {{ range $i, $param := .Values.fluentbit.maskQueryParams }}{{ if $i }}, {{ end }}{{ $param | quote }}{{ end }} }
+local MASK = "[MASKED]"
+local MASKED_FIELDS = { "url.query", "url.full" }
+
+-- Mask in a bare query ("a=1&token=x"), a target ("/p?token=x") or a request line alike. Lua
+-- patterns have no alternation or word boundaries, so each name is matched with its `?`/`&`
+-- delimiter (else `token` also matches `access_token=`) and the leading "&" gives the first
+-- parameter one too. Stopping the value at `&` or whitespace keeps the trailing " HTTP/1.1".
+local function mask(value)
+    if type(value) ~= "string" then
+        return value
+    end
+
+    local masked, total = "&" .. value, 0
+    for _, param in ipairs(MASKED_PARAMS) do
+        -- %W escapes the name's non-alphanumerics into pattern literals.
+        local pattern = "([?&]" .. param:gsub("(%W)", "%%%1") .. "=)[^&%s]*"
+        local count
+        masked, count = masked:gsub(pattern, "%1" .. MASK)
+        total = total + count
+    end
+
+    if total == 0 then
+        return value
+    end
+    return masked:sub(2)
+end
+
+-- Its own filter rather than part of flatten_attributes below, so it can run ahead of the
+-- operator's Lua hook while `record["Attributes"]` is still reachable.
+function mask_query_params(tag, timestamp, group, metadata, record)
+    local modified = false
+
+    local attributes = record["Attributes"]
+    if type(attributes) == "table" then
+        for _, field in ipairs(MASKED_FIELDS) do
+            local masked = mask(attributes[field])
+            if masked ~= attributes[field] then
+                attributes[field] = masked
+                modified = true
+            end
+        end
+    end
+
+    -- `Body` is nginx's $request: the whole request line, query included.
+    local body = mask(record["Body"])
+    if body ~= record["Body"] then
+        record["Body"] = body
+        modified = true
+    end
+
+    -- Code 0 keeps the record as it arrived, discarding the edits above.
+    if modified then
+        return 1, timestamp, metadata, record
+    else
+        return 0, timestamp, metadata, record
+    end
+end
+
+-- Lift the decoded access-log `Attributes` into the record's OTLP metadata, which the
+-- opentelemetry output maps to the log record's attributes. No filter can write metadata, so
+-- this has to be Lua: returning 4 values marks the 3rd as metadata. `Resource` is dropped —
+-- resource attributes are set by the output's processors instead.
+function flatten_attributes(tag, timestamp, group, metadata, record)
+    local metadata = {}
+    local modified = false
+
+    if type(record["Attributes"]) == "table" then
+        for k, v in pairs(record["Attributes"]) do
+            -- nginx writes "" for variables with no value on this request; skip those.
+            if v ~= "" then
+                metadata[k] = v
+            end
+        end
+        record["Attributes"] = nil
+        modified = true
+    end
+
+    if record["Resource"] ~= nil then
+        record["Resource"] = nil
+        modified = true
+    end
+
+    if modified then
+        return 1, timestamp, metadata, record
+    else
+        return 0, timestamp, metadata, record
+    end
+end
+
+-- nginx severity -> OTel SeverityNumber (INFO 9-12, WARN 13-16, ERROR 17-20, FATAL 21-24).
+local SEVERITY_NUMBERS = {
+    debug = 5, info = 9, notice = 10, warn = 13,
+    error = 17, crit = 18, alert = 21, emerg = 22,
+}
+
+-- Rewrite the error-log record the nginx_error parser produced into the same envelope the access
+-- log arrives in: semantic-convention attributes in metadata, the message as `Body`, the nginx
+-- level as OTel severity. Without this its fields keep the parser's own names (client, pid,
+-- request, …) and land in Loki as attributes no dashboard shares with the access log.
+function envelope_error(tag, timestamp, group, metadata, record)
+    local attributes = {}
+
+    if record["client"] ~= nil and record["client"] ~= "" then
+        attributes["client.address"] = record["client"]
+    end
+    if record["server"] ~= nil and record["server"] ~= "" then
+        attributes["server.address"] = record["server"]
+    end
+    if record["pid"] ~= nil then
+        attributes["process.pid"] = tonumber(record["pid"]) or record["pid"]
+    end
+
+    -- The request line ("GET /path?q=1 HTTP/1.1") only appears on messages tied to a request.
+    local request = record["request"]
+    if request ~= nil and request ~= "" then
+        local method, target, version = string.match(request, "^(%S+) (%S+) HTTP/(%S+)$")
+        if method ~= nil then
+            attributes["http.request.method"] = method
+            attributes["network.protocol.name"] = "http"
+            attributes["network.protocol.version"] = version
+            local path, query = string.match(target, "^([^?]*)%??(.*)$")
+            attributes["url.path"] = path
+            if query ~= "" then
+                -- The error line quotes the same request line as the access log, token and all.
+                attributes["url.query"] = mask(query)
+            end
+        else
+            -- Not a well-formed request line (a malformed request is itself a common error).
+            attributes["mapcolonies.request"] = request
+        end
+    end
+
+    local envelope = {
+        Body = record["message"],
+        InstrumentationScope = "error.log",
+    }
+    local level = record["level"]
+    if level ~= nil then
+        envelope["SeverityText"] = level
+        envelope["SeverityNumber"] = SEVERITY_NUMBERS[string.lower(level)] or 9
+    end
+
+    return 1, timestamp, attributes, envelope
+end
diff --git a/helm/config/nginx.conf b/helm/config/nginx.conf
index 08623b6..7e180b6 100644
--- a/helm/config/nginx.conf
+++ b/helm/config/nginx.conf
@@ -4,6 +4,11 @@ load_module modules/ngx_http_js_module.so;
 worker_processes  4;
 
 error_log  /var/log/nginx/error.log warn;
+{{- if and .Values.fluentbit.enabled .Values.fluentbit.errorLog.enabled }}
+# Second error-log destination for the Fluent Bit sidecar (the stderr/file output stays).
+# minLevel is filtered here at the source rather than in Fluent Bit.
+error_log  syslog:server=127.0.0.1:{{ .Values.fluentbit.errorLog.syslogPort }} {{ .Values.fluentbit.errorLog.minLevel }};
+{{- end }}
 pid        /tmp/nginx.pid;
 
 
@@ -43,7 +48,12 @@ http {
 
     include /etc/nginx/log_format.conf;
     
-    access_log  /var/log/nginx/access.log  main;
+    # With the sidecar on there are two destinations: stdout gets the human-readable format
+    # (or JSON, when stdoutReadable is false) for `kubectl logs`, and a second access_log ships
+    # the JSON `main` format to Fluent Bit over syslog. Without it, stdout keeps JSON and there
+    # is no syslog destination — which is why the `if` spans both directives.
+    access_log  /var/log/nginx/access.log  {{ if .Values.fluentbit.enabled }}{{ if .Values.fluentbit.accessLog.stdoutReadable }}readable{{ else }}main{{ end }};
+    access_log  syslog:server=127.0.0.1:{{ .Values.fluentbit.accessLog.syslogPort }} main{{ else }}main{{ end }};
 
     sendfile        on;
     #tcp_nopush     on;
diff --git a/helm/templates/_fluentbit.tpl b/helm/templates/_fluentbit.tpl
new file mode 100644
index 0000000..e11a86b
--- /dev/null
+++ b/helm/templates/_fluentbit.tpl
@@ -0,0 +1,135 @@
+{{/*
+Fluent Bit sidecar container. The merged /metrics port is declared only when
+accessLog.metrics.enabled — the prometheus_exporter output is gated on the same value, so
+declaring it unconditionally would advertise a port with nothing serving it.
+*/}}
+{{- define "nginx.fluentbit.container" -}}
+- name: fluent-bit
+  {{- with .Values.fluentbit.image }}
+  image: {{ include "nginx.cloudProviderDockerRegistryUrl" $ }}{{ .repository }}:{{ .tag }}
+  {{- end }}
+  imagePullPolicy: {{ .Values.fluentbit.image.pullPolicy }}
+  # The image's default command points at the classic /fluent-bit/etc/fluent-bit.conf, so the
+  # YAML config has to be named explicitly. Mounted next to the image's parsers.conf, which the
+  # config loads by relative path.
+  args: ["-c", "/fluent-bit/etc/fluent-bit.yaml"]
+  volumeMounts:
+    - name: fluentbit-config
+      mountPath: /fluent-bit/etc/fluent-bit.yaml
+      subPath: fluent-bit.yaml
+    - name: fluentbit-config
+      mountPath: /fluent-bit/etc/metadata.lua
+      subPath: metadata.lua
+    {{- if .Values.fluentbit.lua.enabled }}
+    - name: fluentbit-config
+      mountPath: /fluent-bit/scripts/custom.lua
+      subPath: fluent-bit.lua
+    {{- end }}
+  # Read as the k8s.pod.uid resource attribute by the OTLP output.
+  env:
+    - name: POD_UID
+      valueFrom:
+        fieldRef:
+          fieldPath: metadata.uid
+  {{- if .Values.fluentbit.accessLog.metrics.enabled }}
+  ports:
+    - name: metrics
+      containerPort: {{ .Values.fluentbit.accessLog.metrics.port }}
+      protocol: TCP
+  {{- end }}
+  {{- if .Values.fluentbit.resources.enabled }}
+  resources:
+    {{- toYaml .Values.fluentbit.resources.value | nindent 4 }}
+  {{- end }}
+{{- end -}}
+
+{{/*
+`processors` block for an OTLP logs output: the only place a record's resource attributes can be
+set (filters can never reach them, so without this everything arrives as `unknown_service`).
+`opentelemetry_envelope` must come first — it puts the record in the OTLP shape that gives
+content_modifier an `otel_resource_attributes` context. Values mirror the `Resource` block of
+config/log_format.conf, which the Lua filter strips from the body. `${VAR}` is left unquoted so
+Fluent Bit's parser expands it.
+*/}}
+{{- define "nginx.fluentbit.logsProcessors" -}}
+processors:
+  logs:
+    - name: opentelemetry_envelope
+    - name: content_modifier
+      context: otel_resource_attributes
+      action: upsert
+      key: service.name
+      value: {{ .Values.nameOverride | default "nginx" | quote }}
+    - name: content_modifier
+      context: otel_resource_attributes
+      action: upsert
+      key: service.version
+      value: {{ include "nginx.tag" . | quote }}
+    - name: content_modifier
+      context: otel_resource_attributes
+      action: upsert
+      key: host.name
+      value: ${HOSTNAME}
+    - name: content_modifier
+      context: otel_resource_attributes
+      action: upsert
+      key: k8s.pod.uid
+      value: ${POD_UID}
+{{- end -}}
+
+{{/*
+One OTLP/HTTP logs output, parameterised by the tag it matches (dict: ctx, match). Both
+pipelines ship to the same dedicated central Alloy logs endpoint (fluentbit.output.logs.*,
+deliberately NOT the traces-only opentelemetry.exporterHost), and the Lua filters put access
+and error records in the same envelope — so the two outputs differ only in that tag.
+*/}}
+{{- define "nginx.fluentbit.logsOutput" -}}
+{{- $ := .ctx -}}
+- name: opentelemetry
+  match: {{ .match }}
+  host: {{ include "nginx.fluentbit.logsHost" $ | quote }}
+  port: {{ $.Values.fluentbit.output.logs.port }}
+  logs_uri: /v1/logs
+  # The Lua filter leaves the nginx `Body` field as the only body candidate; naming it keeps the
+  # output from shipping the whole record as the log body.
+  logs_body_key: $Body
+  {{- if eq $.Values.fluentbit.output.logs.protocol "https" }}
+  tls: on
+  {{- end }}
+  {{- include "nginx.fluentbit.logsProcessors" $ | nindent 2 }}
+{{- end -}}
+
+{{/*
+Compile the access-log forwarding rules (fluentbit.accessLog.forward) into a single regex
+for Fluent Bit's grep filter, matched against the HTTP status code. serverErrors adds 5xx
+(`5`), clientErrors adds 4xx (`4`), and each explicit statusCodes entry is added verbatim; a
+status matches when it starts with any alternative (e.g. `^(5|429)`). When no rule is active
+the regex is `^$`, which matches only an empty string — so every real (non-empty) status is
+dropped and nothing is forwarded.
+*/}}
+{{- define "nginx.fluentbit.accessLogRegex" -}}
+{{- $parts := list -}}
+{{- if .Values.fluentbit.accessLog.forward.serverErrors -}}
+{{- $parts = append $parts "5" -}}
+{{- end -}}
+{{- if .Values.fluentbit.accessLog.forward.clientErrors -}}
+{{- $parts = append $parts "4" -}}
+{{- end -}}
+{{- range .Values.fluentbit.accessLog.forward.statusCodes -}}
+{{- $parts = append $parts (toString .) -}}
+{{- end -}}
+{{- if $parts -}}
+^({{ join "|" $parts }})
+{{- else -}}
+^$
+{{- end -}}
+{{- end -}}
+
+{{/*
+The central Alloy OTLP logs host. Required whenever the sidecar is enabled — an empty
+value renders a Fluent Bit config that crash-loops on startup, so fail the release
+instead with a message that names the value to set.
+*/}}
+{{- define "nginx.fluentbit.logsHost" -}}
+{{- required "fluentbit.output.logs.host is required when fluentbit.enabled is true — set it to the central Alloy OTLP logs endpoint" .Values.fluentbit.output.logs.host -}}
+{{- end -}}
diff --git a/helm/templates/_helpers.tpl b/helm/templates/_helpers.tpl
index cb74c7b..74e5725 100644
--- a/helm/templates/_helpers.tpl
+++ b/helm/templates/_helpers.tpl
@@ -30,6 +30,36 @@ Create chart name and version as used by the chart label.
 {{- printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" }}
 {{- end }}
 
+{{/*
+mclabels labels. When Fluent Bit is enabled, force the log-scraping label off so the
+central k8s-API collector stops ingesting the firehose. Override is set on a deep copy,
+so the shared .Values is never mutated. (`merge` can't be used here: mergo treats the
+`false` override as empty and keeps the original value.)
+*/}}
+{{- define "nginx.mclabels.labels" -}}
+{{- $mclabels := .Values.mclabels -}}
+{{- if .Values.fluentbit.enabled -}}
+{{- $mclabels = set (deepCopy .Values.mclabels) "logScraping" false -}}
+{{- end -}}
+{{- include "mclabels.labels" (dict "Values" (dict "mclabels" $mclabels "global" .Values.global)) -}}
+{{- end -}}
+
+{{/*
+mclabels annotations. When Fluent Bit serves metrics, point the advertised Prometheus port at
+its merged /metrics endpoint. Gated on accessLog.metrics.enabled too: with metrics off nothing
+listens on that port, and the exporter's own port must stay advertised. The override is set on a
+deep copy, so the exporter container and Service keep using the exporter's own port. Unlike the
+labels helper, no `global` is threaded through — mclabels.annotations reads only .Values.mclabels.
+*/}}
+{{- define "nginx.mclabels.annotations" -}}
+{{- $mclabels := .Values.mclabels -}}
+{{- if and .Values.fluentbit.enabled .Values.fluentbit.accessLog.metrics.enabled -}}
+{{- $prometheus := set (deepCopy .Values.mclabels.prometheus) "port" .Values.fluentbit.accessLog.metrics.port -}}
+{{- $mclabels = set (deepCopy .Values.mclabels) "prometheus" $prometheus -}}
+{{- end -}}
+{{- include "mclabels.annotations" (dict "Values" (dict "mclabels" $mclabels)) -}}
+{{- end -}}
+
 {{/*
 Common labels
 */}}
@@ -40,7 +70,7 @@ helm.sh/chart: {{ include "nginx.chart" . }}
 app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
 {{- end }}
 app.kubernetes.io/managed-by: {{ .Release.Service }}
-{{ include "mclabels.labels" . }}
+{{ include "nginx.mclabels.labels" . }}
 {{- end }}
 
 {{/*
diff --git a/helm/templates/deployment.yaml b/helm/templates/deployment.yaml
index 7c77bbb..886cc4c 100644
--- a/helm/templates/deployment.yaml
+++ b/helm/templates/deployment.yaml
@@ -35,7 +35,16 @@ spec:
         {{- if .Values.additionalPodAnnotations }}
         {{- toYaml .Values.additionalPodAnnotations | nindent 8 }}
         {{- end }}
-        {{- include "mclabels.annotations" . | nindent 8 }}
+        {{- if .Values.resetOnConfigChange }}
+        # Roll the pods when any mounted config changes. ConfigMap updates are not picked
+        # up by a running nginx or Fluent Bit, so without this an upgrade that only edits
+        # config leaves the old config live until something else restarts the pod.
+        checksum/base-config: {{ include (print $.Template.BasePath "/configmap.yaml") . | sha256sum }}
+        {{- if .Values.fluentbit.enabled }}
+        checksum/fluentbit-config: {{ include (print $.Template.BasePath "/fluentbit-configmap.yaml") . | sha256sum }}
+        {{- end }}
+        {{- end }}
+        {{- include "nginx.mclabels.annotations" . | nindent 8 }}
     spec:
     {{- if $cloudProviderImagePullSecretName }}
       imagePullSecrets:
@@ -43,11 +52,16 @@ spec:
     {{- end }}
       volumes:
         - name: nginx-base-config
-          configMap:	
+          configMap:
             name: {{ printf "%s-base-configmap" (include "nginx.fullname" .) }}
           {{- if .Values.extraVolumes }}
             {{ tpl (toYaml .Values.extraVolumes) . | nindent 8 }}
           {{- end }}
+        {{- if .Values.fluentbit.enabled }}
+        - name: fluentbit-config
+          configMap:
+            name: {{ printf "%s-fluentbit-configmap" (include "nginx.fullname" .) }}
+        {{- end }}
       containers:
         - name: nginx
           {{- with .Values.image }}
@@ -97,8 +111,8 @@ spec:
             - name: http
               containerPort: {{ $prometheusExporterPort }}
               protocol: TCP
-          # Note: if the Prometheus Exporter container isn't live the entire Pod
-          # (including the NGINX container) will restart
+          # Note: a livenessProbe failure restarts only this container, not the whole
+          # Pod — the NGINX container keeps serving traffic while the exporter restarts.
           livenessProbe:
             initialDelaySeconds: {{ .Values.initialDelaySeconds }}
             httpGet:
@@ -109,6 +123,9 @@ spec:
             {{- toYaml .Values.prometheusExporter.resources.value | nindent 12 }}
           {{- end }}
           {{- end }}
+        {{- if .Values.fluentbit.enabled }}
+        {{- include "nginx.fluentbit.container" . | nindent 8 }}
+        {{- end }}
         {{- if .Values.sidecars }}
         {{ tpl (.Values.sidecars) . | nindent 8 }}
         {{- end }}
diff --git a/helm/templates/fluentbit-configmap.yaml b/helm/templates/fluentbit-configmap.yaml
new file mode 100644
index 0000000..0892c9c
--- /dev/null
+++ b/helm/templates/fluentbit-configmap.yaml
@@ -0,0 +1,15 @@
+{{- if .Values.fluentbit.enabled }}
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: {{ printf "%s-fluentbit-configmap" (include "nginx.fullname" .) }}
+  labels:
+    {{- include "nginx.labels" . | nindent 4 }}
+data:
+  fluent-bit.yaml: {{ tpl (.Files.Get "config/fluent-bit.yaml") . | quote }}
+  # Chart-owned Lua; fluent-bit.lua below is the operator's, on its own key and mount.
+  metadata.lua: {{ tpl (.Files.Get "config/metadata.lua") . | quote }}
+  {{- if .Values.fluentbit.lua.enabled }}
+  fluent-bit.lua: {{ tpl .Values.fluentbit.lua.script . | quote }}
+  {{- end }}
+{{- end }}
diff --git a/helm/values.md b/helm/values.md
index c3f0e5b..afd1882 100644
--- a/helm/values.md
+++ b/helm/values.md
@@ -32,13 +32,48 @@ A Helm chart for nginx
 | environment | string | `"development"` | Specify the environment for this deployment |
 | extraVolumeMounts | list | `[]` | List of extra volumeMounts that are added to the NGINX container |
 | extraVolumes | list | `[]` | List of extra volumes that are added to the Deployment |
+| fluentbit.accessLog.exclude.enabled | bool | `false` | Drop matching access-log records before metrics are derived and before forwarding, so probe traffic neither skews the metrics nor reaches Loki. For probes that hit the main server — the kubelet's `/nginx_status` is already unlogged by the image. |
+| fluentbit.accessLog.exclude.key | string | `"$Attributes['url.path']"` | Fluent Bit record accessor the exclude regex is matched against. Must be a field of the decoded JSON access log. |
+| fluentbit.accessLog.exclude.regex | string | `"^/(health|healthz|live|livez|liveness|ready|readyz|readiness|nginx_status)$"` | Regex matched against `key`; records that match are dropped. Covers the common liveness/readiness path spellings. Only used when enabled. |
+| fluentbit.accessLog.forward.clientErrors | bool | `true` | Forward client errors (4xx) to central Alloy. On by default: 4xx is usually the first sign of a broken client integration or a bad route. |
+| fluentbit.accessLog.forward.serverErrors | bool | `true` | Forward server errors (5xx) to central Alloy. On by default so incident-relevant logs reach Loki with no configuration. |
+| fluentbit.accessLog.forward.statusCodes | list | `[]` | Extra explicit status codes to forward beyond the error classes, e.g. [429, 499]. Everything not matched by any rule is dropped. |
+| fluentbit.accessLog.metrics.enabled | bool | `true` | Derive Prometheus metrics from the access log and serve them on the merged /metrics endpoint. When false, no metrics blocks are rendered. |
+| fluentbit.accessLog.metrics.filters | list | per-status-code counter + request_time histogram (see values.yaml) | Fluent Bit filter entries (tpl-rendered) that derive metrics from the access log, spliced into the sidecar's `pipeline.filters`. Replacing this replaces both defaults. WARNING: never label by high-cardinality fields (path, query, client IP, user-agent) — it can OOM the sidecar. |
+| fluentbit.accessLog.metrics.port | int | `2021` | Port on which Fluent Bit serves the merged /metrics endpoint. When enabled, this becomes the pod's advertised scrape port (mclabels.prometheus.port). |
+| fluentbit.accessLog.metrics.scrapeExporter | bool | `true` | Scrape the existing nginx-prometheus-exporter and merge its series into the endpoint, preserving the stub_status gauges. |
+| fluentbit.accessLog.stdoutReadable | bool | `true` | When true, nginx writes a human-readable (combined-style) access log to stdout for kubectl logs; the JSON log always goes to Fluent Bit over syslog. When false, stdout also receives the JSON format. |
+| fluentbit.accessLog.syslogPort | int | `5514` | UDP port on loopback where Fluent Bit's syslog input listens and to which nginx forwards its JSON-formatted access log. |
+| fluentbit.debug.enabled | bool | `false` | Print the log stream to the sidecar's own stdout (`kubectl logs <pod> -c fluent-bit`). Prints the records handed to the OTLP output; `stages` add earlier snapshots. Off by default — it prints every record the sidecar handles. |
+| fluentbit.debug.logLevel | string | `"info"` | Fluent Bit's service log level while debug is enabled. `debug` reports plugin-level decisions, `trace` is extremely verbose. When debug is disabled the level is always `info`. |
+| fluentbit.debug.stages.parsed | bool | `true` | Dump records once the body is decoded, before the metrics and forwarding filters. Shows the fields the rest of the pipeline sees; a record still holding a raw `message` means the decode failed. |
+| fluentbit.debug.stages.received | bool | `false` | Dump records as they arrive from nginx, before the body is decoded. Answers "is nginx delivering anything, and is the syslog envelope what Fluent Bit expects" — the only stage that shows lines the parser later rejects. |
+| fluentbit.enabled | bool | `false` | Enable the optional Fluent Bit log-processing sidecar (off by default). When on, the central log-scraping label is forced off, and the pod's advertised Prometheus port moves to Fluent Bit's merged /metrics endpoint if accessLog.metrics is also on. |
+| fluentbit.errorLog.enabled | bool | `true` | Ship nginx error logs through a separate Fluent Bit pipeline (syslog input, plaintext parser, severity filter, OTLP output). Independent of the access-log pipeline. Only takes effect when fluentbit.enabled is also true. |
+| fluentbit.errorLog.minLevel | string | `"warn"` | Forward error-log records at or above this severity, applied natively by nginx's error_log directive (records below never leave nginx). Ordering: debug < info < notice < warn < error < crit < alert < emerg. The OSS image cannot emit `debug` (needs a debug-enabled build). |
+| fluentbit.errorLog.syslogPort | int | `5515` | UDP port on loopback where Fluent Bit's error-log syslog input listens and to which nginx forwards its error log. Distinct from accessLog.syslogPort. |
+| fluentbit.image.pullPolicy | string | `"IfNotPresent"` | Image pull policy for the Fluent Bit sidecar |
+| fluentbit.image.repository | string | `"common/fluent-bit"` | Docker image name for the Fluent Bit sidecar |
+| fluentbit.image.tag | string | `"5.0.7"` | Docker image tag for the Fluent Bit sidecar |
+| fluentbit.lua.call | string | `"filter"` | Name of the function in `script` that the filter invokes. Must be a global function defined by the script. |
+| fluentbit.lua.enabled | bool | `false` | Run a custom Lua script over the access-log records selected for forwarding — anything the chart's own values cannot express. Mounted at /fluent-bit/scripts/custom.lua and invoked by a `lua` filter placed after the forwarding grep. Off by default. |
+| fluentbit.lua.script | string | `""` | Inline Lua script (tpl-rendered, so it can reference `.Release.Name`, chart values, etc.) mounted at /fluent-bit/scripts/custom.lua. Only used when enabled. |
+| fluentbit.maskQueryParams | list | `["token"]` | Query parameters whose value is replaced with `[MASKED]` before a record leaves the sidecar. nginx logs the query verbatim in `url.query`, `url.full` and the request line in `Body` (and in the error log's request line), so a credential passed as `?token=` would otherwise reach Loki. Empty list disables masking. |
+| fluentbit.output.logs.host | string | `""` | Host of the dedicated central Alloy OTLP logs endpoint Fluent Bit forwards to. Deliberately NOT reused from opentelemetry.exporterHost (that is the traces-only endpoint). Required when the sidecar is enabled. |
+| fluentbit.output.logs.port | int | `4318` | Port of the central Alloy OTLP/HTTP logs endpoint. |
+| fluentbit.output.logs.protocol | string | `"http"` | Protocol used to reach the OTLP logs endpoint (http or https). |
+| fluentbit.resources.enabled | bool | `true` | Enable or disable resource limits and requests for the Fluent Bit sidecar |
+| fluentbit.resources.value.limits.cpu | string | `"100m"` | CPU limit for the Fluent Bit sidecar |
+| fluentbit.resources.value.limits.memory | string | `"128Mi"` | Memory limit for the Fluent Bit sidecar |
+| fluentbit.resources.value.requests.cpu | string | `"100m"` | CPU request for the Fluent Bit sidecar |
+| fluentbit.resources.value.requests.memory | string | `"128Mi"` | Memory request for the Fluent Bit sidecar |
 | fullnameOverride | string | `""` | String to fully override fullname template |
 | global.cloudProvider | object | `{}` | Global cloud provider configuration. |
 | global.environment | string | `""` | Global environment setting. |
 | global.ingress.domain | string | `""` | Domain name for the ingress. |
 | global.metrics | object | `{}` | Configuration for metrics collection. |
 | global.tracing | object | `{}` | Configuration for distributed tracing. |
-| image.repository | string | `"nginx"` | Docker image name |
+| image.repository | string | `"common/nginx"` | Docker image name |
 | image.tag | string | `""` | Docker image tag. If no value is specified, appVersion will be taken. |
 | imagePullPolicy | string | `"Always"` | Image pull policy for all containers in the deployment |
 | ingress.additionalAnnotations | string | `nil` | Additional annotations for ingress |
diff --git a/helm/values.yaml b/helm/values.yaml
index c5e549e..0635879 100644
--- a/helm/values.yaml
+++ b/helm/values.yaml
@@ -57,9 +57,9 @@ caKey: "ca.crt"
 
 image:
   # -- Docker image name
-  repository: nginx
+  repository: common/nginx
   # -- Docker image tag. If no value is specified, appVersion will be taken.
-  tag: ''
+  tag: ""
 # -- Port on which the application will listen
 port: 8080
 # -- Port to which the service will forward traffic
@@ -119,7 +119,7 @@ backend:
   # -- Enable or disable the backend service
   enabled: true
   # -- Backend service name for proxy_pass
-  host: ''
+  host: ""
   # -- Backend service port
   port: 8080
 
@@ -185,6 +185,119 @@ prometheusExporter:
         # -- Memory request for the main container
         memory: 128Mi
 
+  # @section -- Fluent Bit Log-Processing Sidecar
+fluentbit:
+  # -- Enable the optional Fluent Bit log-processing sidecar (off by default). When on, the central log-scraping label is forced off, and the pod's advertised Prometheus port moves to Fluent Bit's merged /metrics endpoint if accessLog.metrics is also on.
+  enabled: false
+  image:
+    # -- Docker image name for the Fluent Bit sidecar
+    repository: common/fluent-bit
+    # -- Docker image tag for the Fluent Bit sidecar
+    tag: "5.0.7"
+    # -- Image pull policy for the Fluent Bit sidecar
+    pullPolicy: IfNotPresent
+  resources:
+    # -- Enable or disable resource limits and requests for the Fluent Bit sidecar
+    enabled: true
+    value:
+      limits:
+        # -- CPU limit for the Fluent Bit sidecar
+        cpu: 100m
+        # -- Memory limit for the Fluent Bit sidecar
+        memory: 128Mi
+      requests:
+        # -- CPU request for the Fluent Bit sidecar
+        cpu: 100m
+        # -- Memory request for the Fluent Bit sidecar
+        memory: 128Mi
+  output:
+    logs:
+      # -- Host of the dedicated central Alloy OTLP logs endpoint Fluent Bit forwards to. Deliberately NOT reused from opentelemetry.exporterHost (that is the traces-only endpoint). Required when the sidecar is enabled.
+      host: ""
+      # -- Port of the central Alloy OTLP/HTTP logs endpoint.
+      port: 4318
+      # -- Protocol used to reach the OTLP logs endpoint (http or https).
+      protocol: http
+  # -- Query parameters whose value is replaced with `[MASKED]` before a record leaves the sidecar. nginx logs the query verbatim in `url.query`, `url.full` and the request line in `Body` (and in the error log's request line), so a credential passed as `?token=` would otherwise reach Loki. Empty list disables masking.
+  maskQueryParams:
+    - token
+  accessLog:
+    # -- UDP port on loopback where Fluent Bit's syslog input listens and to which nginx forwards its JSON-formatted access log.
+    syslogPort: 5514
+    # -- When true, nginx writes a human-readable (combined-style) access log to stdout for kubectl logs; the JSON log always goes to Fluent Bit over syslog. When false, stdout also receives the JSON format.
+    stdoutReadable: true
+    exclude:
+      # -- Drop matching access-log records before metrics are derived and before forwarding, so probe traffic neither skews the metrics nor reaches Loki. For probes that hit the main server — the kubelet's `/nginx_status` is already unlogged by the image.
+      enabled: false
+      # -- Fluent Bit record accessor the exclude regex is matched against. Must be a field of the decoded JSON access log.
+      key: $Attributes['url.path']
+      # -- Regex matched against `key`; records that match are dropped. Covers the common liveness/readiness path spellings. Only used when enabled.
+      regex: ^/(health|healthz|live|livez|liveness|ready|readyz|readiness|nginx_status)$
+    forward:
+      # -- Forward server errors (5xx) to central Alloy. On by default so incident-relevant logs reach Loki with no configuration.
+      serverErrors: true
+      # -- Forward client errors (4xx) to central Alloy. On by default: 4xx is usually the first sign of a broken client integration or a bad route.
+      clientErrors: true
+      # -- Extra explicit status codes to forward beyond the error classes, e.g. [429, 499]. Everything not matched by any rule is dropped.
+      statusCodes: []
+    metrics:
+      # -- Derive Prometheus metrics from the access log and serve them on the merged /metrics endpoint. When false, no metrics blocks are rendered.
+      enabled: true
+      # -- Scrape the existing nginx-prometheus-exporter and merge its series into the endpoint, preserving the stub_status gauges.
+      scrapeExporter: true
+      # -- Port on which Fluent Bit serves the merged /metrics endpoint. When enabled, this becomes the pod's advertised scrape port (mclabels.prometheus.port).
+      port: 2021
+      # -- Fluent Bit filter entries (tpl-rendered) that derive metrics from the access log, spliced into the sidecar's `pipeline.filters`. Replacing this replaces both defaults. WARNING: never label by high-cardinality fields (path, query, client IP, user-agent) — it can OOM the sidecar.
+      # @default -- per-status-code counter + request_time histogram (see values.yaml)
+      filters:
+        # Per-status-code response counter (status_code is bounded, safe to label). Named
+        # responses_total, not requests_total: the scraped exporter already publishes an
+        # unlabelled nginx_http_requests_total, and two same-named families on one endpoint
+        # make Prometheus reject the whole scrape.
+        - name: log_to_metrics
+          match: nginx.access
+          tag: nginx.metrics
+          metric_mode: counter
+          metric_namespace: nginx
+          metric_subsystem: http
+          metric_name: responses_total
+          metric_description: Total nginx HTTP responses by status code
+          add_label: status_code $Attributes['http.response.status_code']
+        # Buckets default to Prometheus's standard set.
+        - name: log_to_metrics
+          match: nginx.access
+          tag: nginx.metrics
+          metric_mode: histogram
+          metric_namespace: nginx
+          metric_subsystem: http
+          metric_name: request_duration_seconds
+          metric_description: nginx request processing time in seconds
+          value_field: $Attributes['mapcolonies.request_time']
+  errorLog:
+    # -- Ship nginx error logs through a separate Fluent Bit pipeline (syslog input, plaintext parser, severity filter, OTLP output). Independent of the access-log pipeline. Only takes effect when fluentbit.enabled is also true.
+    enabled: true
+    # -- UDP port on loopback where Fluent Bit's error-log syslog input listens and to which nginx forwards its error log. Distinct from accessLog.syslogPort.
+    syslogPort: 5515
+    # -- Forward error-log records at or above this severity, applied natively by nginx's error_log directive (records below never leave nginx). Ordering: debug < info < notice < warn < error < crit < alert < emerg. The OSS image cannot emit `debug` (needs a debug-enabled build).
+    minLevel: warn
+  lua:
+    # -- Run a custom Lua script over the access-log records selected for forwarding — anything the chart's own values cannot express. Mounted at /fluent-bit/scripts/custom.lua and invoked by a `lua` filter placed after the forwarding grep. Off by default.
+    enabled: false
+    # -- Inline Lua script (tpl-rendered, so it can reference `.Release.Name`, chart values, etc.) mounted at /fluent-bit/scripts/custom.lua. Only used when enabled.
+    script: ""
+    # -- Name of the function in `script` that the filter invokes. Must be a global function defined by the script.
+    call: filter
+  debug:
+    # -- Print the log stream to the sidecar's own stdout (`kubectl logs <pod> -c fluent-bit`). Prints the records handed to the OTLP output; `stages` add earlier snapshots. Off by default — it prints every record the sidecar handles.
+    enabled: false
+    # -- Fluent Bit's service log level while debug is enabled. `debug` reports plugin-level decisions, `trace` is extremely verbose. When debug is disabled the level is always `info`.
+    logLevel: info
+    stages:
+      # -- Dump records as they arrive from nginx, before the body is decoded. Answers "is nginx delivering anything, and is the syslog envelope what Fluent Bit expects" — the only stage that shows lines the parser later rejects.
+      received: false
+      # -- Dump records once the body is decoded, before the metrics and forwarding filters. Shows the fields the rest of the pipeline sees; a record still holding a raw `message` means the decode failed.
+      parsed: true
+
 authorization:
   # -- Use authroization mechanism
   enabled: true
diff --git a/test/local/.gitignore b/test/local/.gitignore
new file mode 100644
index 0000000..21be27c
--- /dev/null
+++ b/test/local/.gitignore
@@ -0,0 +1,3 @@
+rendered/
+__pycache__/
+logs/*.json
diff --git a/test/local/README.md b/test/local/README.md
new file mode 100644
index 0000000..5861c72
--- /dev/null
+++ b/test/local/README.md
@@ -0,0 +1,119 @@
+# Local Fluent Bit sidecar harness
+
+Runs the log-processing sidecar outside Kubernetes so the pipeline can be exercised in seconds
+instead of through a deploy.
+
+`fluent-bit` and `nginx-prometheus-exporter` join nginx's network namespace
+(`network_mode: service:nginx`), which is what makes this faithful: `Listen 127.0.0.1`,
+`access_log syslog:server=127.0.0.1` and the exporter scrape all behave exactly as they do in a
+pod. nginx is built from `docker-image/`, so it is the real image.
+
+Configs are not copied here — `render.py` runs `helm template` and writes the ConfigMap contents
+into `rendered/`, so the harness can never drift from the chart.
+
+Records take the production path out of the sidecar (OTLP/HTTP), to one of two backends:
+
+- **`otel-collector`** (the default) stands in for central Alloy. It prints every record fully
+  decoded and dumps it as OTLP JSON into `logs/out.json` — the fast loop, no query language.
+- **`lgtm`** is a real Loki/Prometheus/Grafana stack, for when you want to browse the data the
+  way a person would in production.
+
+## Requirements
+
+`docker compose`, `helm`, and `python3` with `pyyaml`. First run pulls `grafana/otel-lgtm`
+(~1.5 GB) and builds the nginx image.
+
+## Run it
+
+```sh
+cd test/local
+./render.py                    # chart -> rendered/
+docker compose up -d --build
+```
+
+## Send logs
+
+Anything nginx answers produces an access record, and a 404 produces an error record too:
+
+```sh
+curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8080/            # 200
+curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8080/nope        # 404 + error log
+```
+
+Only the status codes selected by `fluentbit.accessLog.forward` are forwarded —
+`lab-values.yaml` turns on 4xx and 5xx, so the 404 arrives at the backend and the 200 does not.
+Every request feeds the derived metrics regardless.
+
+## View them
+
+```sh
+tail -f logs/out.json                            # what was forwarded, as OTLP JSON
+docker compose logs -f otel-collector            # the same records decoded field by field
+curl -s http://localhost:2021/metrics | grep '^nginx_'   # merged /metrics
+docker compose logs fluent-bit                   # per-filter record dumps, parse errors, crashes
+docker compose logs nginx                        # access + error log
+```
+
+`logs/out.json` answers "did it get there"; the collector's `debug` exporter answers "in what
+shape" — resource attributes, log attributes, severity and body, which is the only way to tell a
+properly mapped OTLP record from one whose whole envelope was stuffed into the body.
+
+`logs/out.json` is append-only and gitignored; `rm logs/out.json` between runs when a clean
+slate matters (the collector recreates it).
+
+### In Grafana instead
+
+Point the sidecar at lgtm and query Loki on <http://localhost:3000>:
+
+```sh
+./render.py --set fluentbit.output.logs.host=lgtm
+docker compose restart fluent-bit
+```
+
+## Iterating
+
+Changing chart values or `helm/config/fluent-bit.yaml` means re-rendering and restarting the
+container that reads it:
+
+```sh
+./render.py --set fluentbit.accessLog.exclude.enabled=true
+docker compose restart fluent-bit   # nginx.conf / log_format.conf changes: restart nginx
+```
+
+Any arguments to `render.py` are passed through to `helm template`. Persistent overrides go in
+`lab-values.yaml`, which already disables authorization and the route, points the sidecar at
+`otel-collector`, states the 4xx/5xx forwarding selection explicitly and enables
+`fluentbit.debug`, whose `stdout` filters are what make `docker compose logs fluent-bit` show
+each record at its position in the filter chain — a record appearing at `parsed` but not in the
+output dump was removed by a filter in between.
+
+The sidecar config is YAML, so Fluent Bit can check a render without running it — worth doing
+before a restart, since a bad config crash-loops:
+
+```sh
+docker run --rm -v "$PWD/rendered/fluent-bit.yaml:/fluent-bit/etc/fluent-bit.yaml:ro" \
+  fluent/fluent-bit:5.0.7 /fluent-bit/bin/fluent-bit --dry-run -c /fluent-bit/etc/fluent-bit.yaml
+```
+
+Tear down with `docker compose down`.
+
+## Worth knowing
+
+- **To produce 5xx**, point nginx at a dead upstream:
+  `./render.py --set backend.enabled=true --set backend.host=127.0.0.1 --set backend.port=9999`
+  and restart both containers.
+- **The kubelet liveness path is not logged at all** — `docker-image/nginx-config/status_site.conf`
+  sets `access_log off` on `/nginx_status`, so it never reaches Fluent Bit and never appears in
+  the derived metrics. `fluentbit.accessLog.exclude` is for probes that hit the main server.
+- **Timestamps are UTC end to end.** RFC3164 syslog framing carries no timezone and Fluent Bit
+  reads it as UTC, so a record stamped in a non-UTC local time lands in the future and Loki
+  silently drops it (more than 10m ahead). The containers run UTC.
+- **The merged /metrics carries two families**, log-derived and scraped, so it is worth checking
+  that Prometheus would accept it — two families sharing a name make it reject the whole scrape:
+  `curl -s http://localhost:2021/metrics | docker run --rm -i --entrypoint promtool
+  prom/prometheus:v3.1.0 check metrics`. Ignore `should have "_total" suffix` lint on
+  `nginx_connections_*` (an upstream name, not ours); a `parsing error` is real.
+- `POD_UID` stands in for the downward API and defaults to all zeroes; set it per-run to see a
+  real `k8s.pod.uid` resource attribute.
+- The `fluent/fluent-bit` tag in `docker-compose.yml` should track `fluentbit.image.tag` in
+  `helm/values.yaml`; override per-run with `FLUENT_BIT_TAG=5.0.9 docker compose up -d`.
diff --git a/test/local/docker-compose.yml b/test/local/docker-compose.yml
new file mode 100644
index 0000000..1440ca0
--- /dev/null
+++ b/test/local/docker-compose.yml
@@ -0,0 +1,67 @@
+# Reproduces the sidecar pod outside Kubernetes, shipping into a real OTel backend.
+#
+# fluent-bit joins nginx's network namespace, so `Listen 127.0.0.1` and
+# `access_log syslog:server=127.0.0.1` behave exactly as they do in a pod. nginx owns the
+# namespace and therefore publishes the ports for both containers.
+#
+# The forwarding path mirrors production -- sidecar -> OTLP/HTTP -> collector: otel-collector
+# stands in for central Alloy and prints every record it receives fully decoded. Repoint the
+# sidecar at lgtm (see README.md) to browse the same records in Grafana instead.
+#
+# Configs come from ./rendered/, produced by ./render.py -- see README.md.
+
+services:
+  nginx:
+    build: ../../docker-image
+    ports:
+      - "8080:8080" # site
+      - "8081:8081" # nginx_status
+      - "2021:2021" # fluent-bit's merged /metrics, served inside this namespace
+    volumes:
+      - ./rendered/nginx.conf:/etc/nginx/nginx.conf:ro
+      - ./rendered/default.conf:/etc/nginx/conf.d/default.conf:ro
+      - ./rendered/log_format.conf:/etc/nginx/log_format.conf:ro
+
+  # Keep this tag in step with fluentbit.image.tag in helm/values.yaml.
+  fluent-bit:
+    image: fluent/fluent-bit:${FLUENT_BIT_TAG:-5.0.7}
+    network_mode: "service:nginx"
+    depends_on:
+      - nginx
+    # Same override the chart applies: the image's default command loads the classic
+    # fluent-bit.conf, and the sidecar's config is YAML.
+    command: ["-c", "/fluent-bit/etc/fluent-bit.yaml"]
+    volumes:
+      - ./rendered/fluent-bit.yaml:/fluent-bit/etc/fluent-bit.yaml:ro
+      - ./rendered/metadata.lua:/fluent-bit/etc/metadata.lua:ro
+      # fluentbit.lua.script when set; a placeholder Fluent Bit never loads when it isn't.
+      - ./rendered/fluent-bit.lua:/fluent-bit/scripts/custom.lua:ro
+    # Stands in for the downward API: in a pod the chart injects this from metadata.uid.
+    environment:
+      POD_UID: ${POD_UID:-00000000-0000-0000-0000-000000000000}
+
+  # Present so fluentbit.accessLog.metrics.scrapeExporter (on by default) has something real
+  # to scrape, and the merged /metrics can be checked for the stub_status gauges.
+  nginx-prometheus-exporter:
+    image: nginx/nginx-prometheus-exporter:${EXPORTER_TAG:-1.5.1}
+    command: ["-nginx.scrape-uri=http://localhost:8081/nginx_status"]
+    network_mode: "service:nginx"
+    depends_on:
+      - nginx
+
+  # Stands in for central Alloy. Its debug exporter is the only view of what the sidecar
+  # actually put on the wire -- resource attributes, log attributes, severity, body.
+  otel-collector:
+    image: otel/opentelemetry-collector-contrib:${OTELCOL_TAG:-latest}
+    command: ["--config=/etc/otelcol/config.yaml"]
+    volumes:
+      - ./otel-collector.yaml:/etc/otelcol/config.yaml:ro
+      - ./logs:/tmp/logs/:rw
+
+  # The alternative backend: OTLP -> Loki/Prometheus/Tempo + Grafana, for when the records are
+  # worth browsing rather than tailing. Large image (~1.5 GB), pulled once.
+  lgtm:
+    image: grafana/otel-lgtm:${LGTM_TAG:-latest}
+    ports:
+      - "3000:3000" # Grafana
+      - "3100:3100" # Loki HTTP API
diff --git a/test/local/lab-values.yaml b/test/local/lab-values.yaml
new file mode 100644
index 0000000..fcc24f1
--- /dev/null
+++ b/test/local/lab-values.yaml
@@ -0,0 +1,43 @@
+# Values for the local harness. Only what matters for rendering the nginx and Fluent Bit
+# configs; cluster-only concerns (route, pull secrets) are irrelevant here.
+
+cloudProvider:
+  dockerRegistryUrl: ""
+  imagePullSecretName: ""
+  flavor: minikube
+
+authorization:
+  enabled: false
+
+# No upstream by default, so nginx answers from its own docroot.
+backend:
+  enabled: false
+
+opentelemetry:
+  exporterHost: "127.0.0.1"
+  samplerMethod: "AlwaysOff"
+
+route:
+  enabled: false
+
+fluentbit:
+  enabled: true
+  debug:
+    enabled: true
+  output:
+    logs:
+      # The harness's stand-in for central Alloy (docker-compose.yml).
+      host: "otel-collector"
+      port: 4318
+      protocol: http
+  accessLog:
+    forward:
+      serverErrors: true
+      # Both stated explicitly (they match the chart defaults) so the harness's forwarding
+      # selection is readable without cross-checking values.yaml.
+      clientErrors: true
+    metrics:
+      enabled: true
+      scrapeExporter: true
+  errorLog:
+    enabled: true
diff --git a/test/local/logs/.gitkeep b/test/local/logs/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/test/local/otel-collector.yaml b/test/local/otel-collector.yaml
new file mode 100644
index 0000000..85627ef
--- /dev/null
+++ b/test/local/otel-collector.yaml
@@ -0,0 +1,24 @@
+# The harness's stand-in for central Alloy, and its window onto the wire.
+#
+# `debug` prints each OTLP log record fully decoded -- resource attributes, log attributes,
+# severity, body -- which is what tells a correctly shaped record from one whose whole envelope
+# was stuffed into the body. `file` keeps the same records as OTLP JSON in logs/out.json.
+# To browse them in Grafana instead, point the sidecar at lgtm directly -- see README.md.
+
+receivers:
+  otlp:
+    protocols:
+      http:
+        endpoint: 0.0.0.0:4318
+
+exporters:
+  debug:
+    verbosity: detailed
+  file:
+    path: /tmp/logs/out.json
+
+service:
+  pipelines:
+    logs:
+      receivers: [otlp]
+      exporters: [debug, file]
diff --git a/test/local/render.py b/test/local/render.py
new file mode 100755
index 0000000..649b5ff
--- /dev/null
+++ b/test/local/render.py
@@ -0,0 +1,54 @@
+#!/usr/bin/env python3
+"""Render the chart with lab-values.yaml and write every ConfigMap key into ./rendered/.
+
+The harness always tests exactly what the chart produces, so there are no hand-maintained
+copies of nginx.conf / fluent-bit.yaml to drift. Any extra arguments are passed straight
+through to `helm template`, e.g.
+
+    ./render.py --set fluentbit.accessLog.exclude.enabled=true
+"""
+import pathlib
+import subprocess
+import sys
+
+HERE = pathlib.Path(__file__).parent
+CHART = HERE.parent.parent / "helm"
+OUT = HERE / "rendered"
+
+# docker-compose.yml mounts these unconditionally, so they must exist even when the values
+# in use don't make the chart render them.
+ALWAYS_PRESENT = ("fluent-bit.yaml", "metadata.lua", "fluent-bit.lua")
+
+cmd = ["helm", "template", "lab", str(CHART), "-f", str(HERE / "lab-values.yaml")] + sys.argv[1:]
+proc = subprocess.run(cmd, capture_output=True, text=True)
+if proc.returncode != 0:
+    print(proc.stderr, file=sys.stderr)
+    sys.exit(proc.returncode)
+
+try:
+    import yaml
+except ImportError:
+    sys.exit("pyyaml is required: pip install pyyaml")
+
+files = {}
+for doc in yaml.safe_load_all(proc.stdout):
+    if not doc or doc.get("kind") != "ConfigMap":
+        continue
+    files.update(doc.get("data") or {})
+
+rendered = sorted(files)
+for name in ALWAYS_PRESENT:
+    files.setdefault(name, "# not rendered by the chart with these values\n")
+
+OUT.mkdir(exist_ok=True)
+for stale in OUT.iterdir():
+    # is_file() so a stray directory doesn't turn this cleanup into an IsADirectoryError.
+    if stale.name not in files and stale.is_file():
+        stale.unlink()
+
+# Overwrite in place rather than unlink+recreate: docker bind-mounts a single file by inode,
+# so replacing the file would leave running containers reading the old contents forever.
+for name, content in files.items():
+    (OUT / name).write_text(content)
+
+print("rendered:", ", ".join(rendered))