lua: add stats API for creating counters, gauges, and histograms

[derekargueta]

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

[repokitteh-read-only]

As a reminder, PRs marked as draft will not be automatically assigned reviewers,
or be handled by maintainer-oncall triage.

Please mark your PR as ready when you want it to be reviewed!

🐱

Caused by: #44334 was opened by derekargueta.

see: more, trace.