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

[derekargueta]

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
Testing: unit tests & integration test
Docs Changes: done
Release Notes: done
Platform Specific Features: no

[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.

[derekargueta]

All the CI failures I'm seeing are pointing to the Rust SDK which should be unrelated to this PR

Notice: INFO: Streaming build results to: https://mordenite.cluster.engflow.com/invocation/76748376-5a51-4e2c-9a18-32793a97c024
Notice: INFO: Streaming build results to: https://mordenite.cluster.engflow.com/invocation/a8fb24ec-1273-4d79-8a7f-1874a23e774d
Notice: INFO: Streaming build results to: https://mordenite.cluster.engflow.com/invocation/b83dac8c-aa81-4dfb-aa23-185dc616a6b4
Notice: INFO: Streaming build results to: https://mordenite.cluster.engflow.com/invocation/e279ddee-7510-4292-9b54-6923a0084147
Error: error: aborting due to 2 previous errors
Error: error: unnecessary `unsafe` block
Error: ERROR: /source/test/extensions/dynamic_modules/BUILD:66:10: Compiling Rust bin rust_sdk_test (19 files) failed: (Exit 1): process_wrapper failed: error executing Rustc command (from target //test/extensions/dynamic_modules:rust_sdk_test)
Error: ERROR: Build did NOT complete successfully
Warning: WARNING: The background upload of the Build Event Protocol for the previous invocation failed to complete in 5.000 seconds. Cancelling and starting a new invocation...

so opening...

hello Envoy friends :) 👋

[wbpcode]

Thanks for this great contribution. I guess this cannot catch up 1.38 but should be good to be part of 1.39.

Could you merge main to fix the CI also? Thanks.

[wbpcode]

Suggested change

	virtual Stats::ScopeSharedPtr statsScope() PURE;
	virtual Stats::Scope& statsScope() PURE;

[wbpcode]

we needn't to extend the lifetime of scope so reference is preferred..

[derekargueta]

@wbpcode updated - sorry about the force-pushes, had to fix my DCO workflow.

[derekargueta]

MacOS and do_ci.sh config Precheck builds hit a network flake with www.antlr.org

Error: ERROR: /private/var/tmp/_bazel_runner/24e7a101d26e6b05dd6bbfabf7fb2d6f/external/bazel_tools/tools/build_defs/repo/http.bzl:224:33: An error occurred during the fetch of repository 'antlr4_jar':
Error: ERROR: /private/var/tmp/_bazel_runner/24e7a101d26e6b05dd6bbfabf7fb2d6f/external/cel-cpp/bazel/BUILD:4:12: @@cel-cpp//bazel:antlr4_tool depends on @@antlr4_jar//jar:jar in repository @@antlr4_jar which failed to fetch. no such package '@@antlr4_jar//jar': java.io.IOException: Error downloading [https://www.antlr.org/download/antlr-4.13.1-complete.jar] to /private/var/tmp/_bazel_runner/24e7a101d26e6b05dd6bbfabf7fb2d6f/external/antlr4_jar/jar/downloaded.jar: GET returned 503 Service Unavailable
Error: ERROR: Analysis of target '//source/exe:envoy-static' failed; build aborted: Analysis failed
Error: ERROR: Build did NOT complete successfully
Error: ERROR: no such package '@@antlr4_jar//jar': java.io.IOException: Error downloading [https://www.antlr.org/download/antlr-4.13.1-complete.jar] to /private/var/tmp/_bazel_runner/24e7a101d26e6b05dd6bbfabf7fb2d6f/external/antlr4_jar/jar/downloaded.jar: GET returned 503 Service Unavailable

[wbpcode]

LGTM. Thanks.

[wbpcode]

The release of 1.38 is delayed and this change is low risk change.

[derekargueta]

Thanks for squeezing this in @wbpcode!