Description

Adds a stats() method to the Lua stream handle that returns a stats scope object, allowing Lua scripts to create and manipulate Envoy stats directly. This has been a requested feature for a while - being able to emit custom metrics from Lua scripts without needing to write a native filter.

The API provides:

• counter(name) - create/get a counter with inc(), add(), value() methods
• gauge(name) - create/get a gauge with inc(), dec(), add(), sub(), set(), value() methods
• histogram(name, unit) - create/get a histogram with recordValue() method

Example usage:

function envoy_on_request(request_handle)
  local stats = request_handle:stats()
  
  local counter = stats:counter("my_requests")
  counter:inc()
  
  local gauge = stats:gauge("active_connections")
  gauge:set(10)
  
  local histogram = stats:histogram("request_latency", "ms")
  histogram:recordValue(42)
end

Stats are prefixed with lua. plus the optional stat_prefix from the filter config. Gauges use NeverImport mode since they track local process state and shouldn't be accumulated across hot restarts.

Risk Level: Low

This is an additive API that doesn't change existing behavior.

Testing

• Unit tests for all wrapper operations and error cases
• Integration test verifying end-to-end behavior including cross-phase stat accumulation

Test Plan

• Unit tests pass (//test/extensions/filters/http/lua:wrappers_test)
• Filter tests pass (//test/extensions/filters/http/lua:lua_filter_test)
• Integration test passes (//test/extensions/filters/http/lua:lua_integration_test --test_filter="*StatsApi*")

Documentation

Added docs for the new stats() method and all stat object APIs to lua_filter.rst.

---

Signed-off-by: Derek Argueta derek.argueta@airbnb.com

Request variables

Key	Value
ref	708390b
sha	8dd7403
pr	44334
base-sha	7367e6c
actor	@derekargueta
message	lua: add stats API for creating counters, gauges, and histograms...
started	1775675613.950105
target-branch	main
trusted	false

Container image/s (as used in this CI run)

Envoy version (as used in this CI run)