Add class instrumentation examples; add configurable socket log level to http_server_t/http_pusher_t; update example file headers and console output

Author: biaks

3rdparty/ip-sockets-cpp-lite/readme.md

@@ -1,6 +1,8 @@
 # ip-sockets-cpp-lite 🔌
 
 [![Build examples](https://github.com/biaks/ip-sockets-cpp-lite/actions/workflows/cmake.yml/badge.svg)](https://github.com/biaks/ip-sockets-cpp-lite/actions/workflows/cmake.yml)
+[![Build multi-platform](https://github.com/biaks/ip-sockets-cpp-lite/actions/workflows/cmake-multi-platform.yml/badge.svg)](https://github.com/biaks/ip-sockets-cpp-lite/actions/workflows/cmake-multi-platform.yml)
+
 
 **Simple. Lightweight. Cross-platform.**
 
@@ -107,9 +109,9 @@ Keep it simple. Keep it portable.
 
 from /include folder copy:
 
-* `ip_address.h`
-* `udp_socket.h`
-* `tcp_socket.h`
+* [`ip_address.h`](include/ip_address.h)
+* [`udp_socket.h`](include/udp_socket.h)
+* [`tcp_socket.h`](include/tcp_socket.h)
 
 **Option 2 — Use CMake**
 
@@ -255,13 +257,12 @@ if (server.open("0.0.0.0:8080") == no_error) {
 ```
 
 ### 📚 More Examples
-Check out the `examples/` directory for complete working examples:
-* `ip_address.cpp` - all IP address manipulation features
-* `udp_socket.cpp` - UDP client-server interaction
-* `tcp_socket.cpp` - TCP client-server interaction
-* `resolve_host.cpp` - resolving host to ipv4/ipv6 address example
-* `http_server.cpp` - compact multi-page HTTP server
-
+Check out the [`examples/`](examples) directory for complete working examples:
+* [`ip_address.cpp`](examples/ip_address.cpp) - all IP address manipulation features
+* [`udp_socket.cpp`](examples/udp_socket.cpp) - UDP client-server interaction
+* [`tcp_socket.cpp`](examples/tcp_socket.cpp) - TCP client-server interaction
+* [`resolve_host.cpp`](examples/resolve_host.cpp) - resolving host to ipv4/ipv6 address example
+* [`http_server.cpp`](examples/http_server.cpp) - compact multi-page HTTP server
 ---
 
 ## 🤔 Why is this convenient?

README.md

@@ -3,17 +3,17 @@
 [![Build examples](https://github.com/biaks/prometheus-cpp-lite/actions/workflows/cmake.yml/badge.svg)](https://github.com/biaks/prometheus-cpp-lite/actions/workflows/cmake.yml)
 [![Build multi-platform](https://github.com/biaks/prometheus-cpp-lite/actions/workflows/cmake-multi-platform.yml/badge.svg)](https://github.com/biaks/prometheus-cpp-lite/actions/workflows/cmake-multi-platform.yml)
 
-**Crossplatform header-only C++ library for quickly adding metrics (and profiling) functionality to C++ projects - simple, fast, dependency-free.**
+
+**Crossplatform header-only C++ library for quickly adding metrics (and profiling) functionality to C++ projects — simple, fast, dependency-free.**
+
+**Simplest usage — global registry, no boilerplate:**
 
 ```cpp
 #include <prometheus/prometheus.h>
 
 int main() {
-  prometheus::registry_t       registry;
-  prometheus::counter_metric_t requests (registry, "http_requests_total", "Total HTTP requests");
-  prometheus::http_server_t    server   (registry, "127.0.0.1:9100");
-
-  // metrics are now available at http://localhost:9100/metrics
+  prometheus::counter_metric_t requests ("http_requests_total", "Total HTTP requests");
+  prometheus::http_server.start ("127.0.0.1:9100");
 
   for (;;) {
     std::this_thread::sleep_for(std::chrono::seconds(1));
@@ -22,6 +22,29 @@ int main() {
 }
 ```
 
+**Full control — registry, families, labels, value types:**
+
+```cpp
+#include <prometheus/prometheus.h>
+using namespace prometheus;
+
+int main() {
+  registry_t         registry;
+  family_t           reqs   (registry, "http_requests", "HTTP requests", {{"host", "web01"}});
+  counter_t<double&> get    (reqs,     {{"method", "GET"},  {"status", "200"}});
+  counter_t<double&> post   (reqs,     {{"method", "POST"}, {"status", "201"}});
+  gauge_metric_t     conn   (registry, "connections", "Open connections", {{"host", "web01"}});
+  http_server_t      server (registry, "127.0.0.1:9100", "/metrics", log_e::info);
+
+  for (;;) {
+    std::this_thread::sleep_for(std::chrono::seconds(1));
+    get  += 1.5;
+    post += 0.75;
+    conn  = 10 + std::rand() % 50;
+  }
+}
+```
+
 ---
 
 
@@ -37,7 +60,7 @@ The main C++ Prometheus library - [jupp0r/prometheus-cpp](https://github.com/jup
 | Build system        | Bazel (primary) + CMake            | CMake or **just copy files**                                      |
 | Minimum boilerplate | ~20 lines to create one counter    | **2 lines** to create a counter and expose it (with global registry, see below) |
 | Value types         | `double` only                      | `uint64_t` (default), `double`, `int64_t`, or any arithmetic type |
-| Metric types        | counter, gauge, histogram, summary | `counter`, `gauge`, `histogram`, `summary`, `info`, **`benchmark`** or you can make your own custom metric class (see `add_custom_metric_class.cpp` for a complete working example of a new user-defined metric `min_max_t`) |
+| Metric types        | `counter`, `gauge`, `histogram`, `summary`, `info` | [`counter`](examples/test_counter.cpp), [`gauge`](examples/test_gauge.cpp), [`histogram`](examples/test_histogram.cpp), [`summary`](examples/test_summary.cpp), `info`, **[`benchmark`](examples/test_benchmark.cpp)** - or [make your own](examples/add_custom_metric_class.cpp) |
 | C++ standard        | C++11                              | C++11                                                             |
 | Thread-safe         | Yes                                | Yes                                                               |
 
@@ -62,12 +85,12 @@ will work.
 - **Low entry barrier**                 - a working counter with HTTP export is 2 lines of code (with global registry, see below)
 - **Gradual complexity**                - start simple, add families/labels/registries/custom types when needed
 - **Multiple value types**              - `uint64_t` (fast integer), `double` (Prometheus-compatible), `int64_t`, or custom
-- **Six metric types**                  - `counter`, `gauge`, `histogram`, `summary`, `benchmark`, `info`
+- **Six metric types**                  - [`counter`](examples/test_counter.cpp), [`gauge`](examples/test_gauge.cpp), [`histogram`](examples/test_histogram.cpp), [`summary`](examples/test_summary.cpp), `info`, [`benchmark`](examples/test_benchmark.cpp)
 - **Three export modes**                - HTTP pull server, HTTP push (Pushgateway), file (node_exporter textfile)
 - **Simplest way with global_registry** - add metrics anywhere in your code without passing registry references
 - **prometheus-cpp compatible**         - supports the same Builder/Family/Registry API style
-- **Extensible**                        - each metric type is self-contained in one header; **you can add your own metric by following the same pattern** (see `add_custom_metric_class.cpp` example)
-- **Detailed examples**                 - see the examples folder for usage patterns
+- **Extensible**                        - each metric type is self-contained in one header; **you can [add your own](examples/add_custom_metric_class.cpp) metric by following the same pattern**
+- **Detailed examples**                 - see the [examples](examples) folder for usage patterns
 
 ---
 
@@ -123,7 +146,7 @@ int main() {
   histogram_metric_t latency  (registry, "request_duration_sec", "Request latency", {}, {0.01, 0.05, 0.1, 0.5, 1.0});
   summary_metric_t   response (registry, "response_time_sec",    "Response time",   {}, {{0.5,0.05},{0.9,0.01},{0.99,0.001}});
   benchmark_metric_t uptime   (registry, "uptime_sec",           "Process uptime");
-  info_metric_t      info     (registry, "build_info",     "Build information", {{"version", "1.0.0"}, {"commit", "abc123"}});
+  info_metric_t      info     (registry, "build_info",           "Build information", {{"version", "1.0.0"}, {"commit", "abc123"}});
 
   http_server_t      server   (registry, {{127,0,0,1}, 9100});
 
@@ -149,7 +172,7 @@ int main() {
 
 ### 1. HTTP pull (recommended for long-running services)
 
-The application runs an HTTP server. Prometheus scrapes it periodically.
+The application runs an HTTP server. Prometheus scrapes it periodically ([example](examples/provide_via_http_pull_simple.cpp)).
 
 ```cpp
 #include <prometheus/prometheus.h>
@@ -160,7 +183,7 @@ prometheus::http_server_t    server (registry, "127.0.0.1:9100");
 // → http://localhost:9100/metrics
 ```
 
-**Multiple endpoints** for different metric domains:
+**Multiple endpoints** for different metric domains ([example](examples/provide_via_http_pull_advanced.cpp)):
 
 ```cpp
 using namespace prometheus;
@@ -177,19 +200,20 @@ server.start({{127,0,0,1}, 9200});
 
 ### 2. HTTP push (for short-lived jobs, edge devices)
 
-Metrics are POSTed to a Pushgateway or VictoriaMetrics at a fixed interval.
+Metrics are POSTed to a Pushgateway or VictoriaMetrics at a fixed interval ([example](examples/provide_via_http_push_simple.cpp)).
 
 ```cpp
 #include <prometheus/prometheus.h>
 
 prometheus::registry_t       registry;
 prometheus::counter_metric_t metric (registry, "my_counter", "Example counter");
-prometheus::http_pusher_t    pusher (registry, std::chrono::seconds(5), "http://localhost:9091/metrics/job/myapp");
+prometheus::http_pusher_t    pusher (registry, std::chrono::seconds(5),
+                                               "http://localhost:9091/metrics/job/myapp");
 ```
 
 ### 3. File export (for node_exporter textfile collector)
 
-Metrics are written to a `.prom` file at a fixed interval.
+Metrics are written to a `.prom` file at a fixed interval ([example](examples/provide_via_textfile.cpp)).
 
 ```cpp
 #include <prometheus/prometheus.h>
@@ -206,7 +230,7 @@ prometheus::file_saver_t     saver  (registry, std::chrono::seconds(5), "./metri
 ### Using a family
 
 ```cpp
-family_t         requests   (registry, "http_requests", "HTTP requests by method", {{"host", "dev"}});
+family_t         requests   (registry, "http_requests", "Requests by method", {{"host", "dev"}});
 counter_metric_t get_count  (requests, {{"method", "GET"}});
 counter_metric_t post_count (requests, {{"method", "POST"}});
 
@@ -275,7 +299,8 @@ With prometheus-cpp-lite's global registry approach, none of that is
 necessary. The `prometheus-cpp-lite-full` CMake target provides ready-made
 global objects — `global_registry`, `file_saver`, `http_pusher`, and
 `http_server` — so you can create metrics anywhere in your code and start
-exposing them with a single call from any place. No plumbing required.
+exposing them with a single call from any place ([example](examples/check_global_objects.cpp)).
+No plumbing required.
 
 ### The workflow
 
@@ -319,7 +344,8 @@ prometheus::http_server.start("127.0.0.1:9100");
 ```
 
 That's it. Every metric you created in step 2 is automatically available
-at the HTTP endpoint. You can also use the other pre-defined global
+at the HTTP endpoint ([example](examples/use_metrics_in_class_simple.cpp)).
+You can also use the other pre-defined global
 exporters:
 
 ```cpp
@@ -387,7 +413,8 @@ void process_order(const Order& order) {
 
 The accumulated elapsed time is immediately available at your `/metrics`
 endpoint — no separate profiling tool, no recompilation with special flags,
-no post-hoc analysis. You get real production latency data from live traffic.
+no post-hoc analysis. You get real production latency data from live traffic
+([example](examples/use_benchmark_in_class_simple.cpp)).
 
 **Best practice for multithreaded code:** the `start()`/`stop()` state
 machine is local to each metric instance and is intentionally not
@@ -481,7 +508,7 @@ not even the `#include` lines need to be modified.
 
 ### Example 1: Exposer (HTTP pull)
 
-The code below is **valid prometheus-cpp code**. It compiles and runs with
+The code below is **[valid prometheus-cpp code](examples/legacy_prometheus_cpp.cpp)**. It compiles and runs with
 prometheus-cpp-lite without touching a single line — just swap the library
 in your build system:
 
@@ -495,8 +522,8 @@ int main() {
   auto registry = std::make_shared<prometheus::Registry>();
 
   auto& family = prometheus::BuildCounter()
-                   .Name("http_requests_total")
-                   .Help("Total HTTP requests")
+                   .Name("http_requests")
+                   .Help("HTTP requests")
                    .Register(*registry);
 
   auto& counter = family.Add({{"method", "GET"}});
@@ -514,7 +541,7 @@ int main() {
 int main() {
   prometheus::registry_t       registry;
   prometheus::http_server_t    server   (registry, "127.0.0.1:8080");
-  prometheus::counter_metric_t counter  (registry, "http_requests_total", "Total HTTP requests", {{"method", "GET"}});
+  prometheus::counter_metric_t counter  (registry, "http_requests", "HTTP requests", {{"method", "GET"}});
 
   counter++;
 }
@@ -672,7 +699,7 @@ add_subdirectory("prometheus-cpp-lite")
 # If you need SimpleAPI and pre-defined global objects (global_registry, file_saver, etc.):
 target_link_libraries(your_target prometheus-cpp-simpleapi)
 
-# If you use only ComplexAPI or Java liked legacy API from prometheus-cpp and use local registries only:
+# If you use only ComplexAPI or Java liked legacy API from prometheus-cpp and use local registries:
 target_link_libraries(your_target prometheus-cpp-lite-core)
 ```
 
@@ -748,16 +775,45 @@ prometheus::counter_metric_t metric2 (registry, "standalone", "help", labels);
 
 
 
-## Building examples
+## Examples
 
-```cmake
+All examples are in the [`examples/`](examples/) directory. Build them with:
+
+```
 cmake -B build -G Ninja -DPROMETHEUS_BUILD_EXAMPLES=ON
 cmake --build build
 ```
 
-The examples use `prometheus-cpp-lite` (header-only target) and define
-`global_registry` in each `.cpp` file. To use the pre-defined global
-objects instead, link against `prometheus-cpp-lite-full`.
+
+| Example | Description |
+|---------|-------------|
+| **Quick start** | |
+| [`quick_start.cpp`](examples/quick_start.cpp) | All metric types + HTTP server in one file. The code from the README "All metric types at a glance" section. |
+| **Export modes** | |
+| [`provide_via_http_pull_simple.cpp`](examples/provide_via_http_pull_simple.cpp) | Shortest HTTP pull server — 3 lines of setup, `curl http://localhost:9100/metrics`. |
+| [`provide_via_http_pull_advanced.cpp`](examples/provide_via_http_pull_advanced.cpp) | Single-registry and multi-path (multiple registries at different URLs) HTTP pull examples. |
+| [`provide_via_http_push_simple.cpp`](examples/provide_via_http_push_simple.cpp) | Shortest periodic push to Pushgateway — 3 lines of setup. |
+| [`provide_via_http_push_advanced.cpp`](examples/provide_via_http_push_advanced.cpp) | Periodic push, on-demand Push/PushAdd/Delete (Gateway API), and async push examples. |
+| [`provide_via_textfile.cpp`](examples/provide_via_textfile.cpp) | Periodic save to `.prom` file for node_exporter textfile collector. |
+| **Metric types — all API levels** | |
+| [`test_counter.cpp`](examples/test_counter.cpp) | Counter (`uint64_t`) — every way to create: global/explicit registry, untyped/typed family, all legacy APIs. |
+| [`test_gauge.cpp`](examples/test_gauge.cpp) | Gauge (`int64_t`) — same full set of API variants. |
+| [`test_histogram.cpp`](examples/test_histogram.cpp) | Histogram (`double`) — buckets, custom boundaries, same full set of API variants. |
+| [`test_summary.cpp`](examples/test_summary.cpp) | Summary (`double`) — quantiles, custom quantile definitions, same full set of API variants. |
+| [`test_benchmark.cpp`](examples/test_benchmark.cpp) | Benchmark (`double`) — profile method execution time, same full set of API variants. |
+| **Global objects** | |
+| [`check_global_objects.cpp`](examples/check_global_objects.cpp) | Uses `prometheus-cpp-lite-full` cmake target with pre-defined globals: `global_registry`, `file_saver`, `http_server`, `http_pusher`. |
+| **Using metrics in classes** | |
+| [`use_metrics_in_class_simple.cpp`](examples/use_metrics_in_class_simple.cpp) | Simplest way to add metrics to a class — declare as members, increment in methods, expose via `http_server.start()`. |
+| [`use_benchmark_in_class_simple.cpp`](examples/use_benchmark_in_class_simple.cpp) | Profile method execution time with `benchmark_metric_t` — `start()`/`stop()` around code phases. |
+| [`use_metrics_in_class_advanced.cpp`](examples/use_metrics_in_class_advanced.cpp) | Dynamic per-instance metrics with labels — connection pool where each connection creates metrics at runtime via `make_metric<>()` without storing families. |
+| **Compatibility** | |
+| [`legacy_prometheus_cpp.cpp`](examples/legacy_prometheus_cpp.cpp) |  Unmodified prometheus-cpp code (`Exposer`, `BuildCounter`, `Registry`) — compiles as-is with prometheus-cpp-lite. |
+| **Extensibility** | |
+| [`add_custom_metric_class.cpp`](examples/add_custom_metric_class.cpp) | How to create your own metric type (`min_max_t` — tracks min/max of observed values). Demonstrates owning/reference forms, all family wrappers, and the Builder API. |
+
+
+
 
 ---
 

examples/CMakeLists.txt

@@ -26,5 +26,8 @@ if(PROMETHEUS_USE_IP_SOCKETS)
   add_example(provide_via_http_push_advanced  prometheus-cpp-lite)
   add_example(legacy_prometheus_cpp           prometheus-cpp-lite)
   add_example(check_global_objects            prometheus-cpp-lite-full)
+  add_example(use_benchmark_in_class_simple   prometheus-cpp-lite-full)
+  add_example(use_metrics_in_class_simple     prometheus-cpp-lite-full)
+  add_example(use_metrics_in_class_advanced   prometheus-cpp-lite-full)
 endif()