Add fastapi prometheus example

Author: hxnir

.github/workflows/lint_peripherals.yaml

@@ -7,7 +7,7 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
 
 env:
-  POETRY_GROUPS: stress_test,code_quality
+  POETRY_GROUPS: stress_test,code_quality,examples
 
 jobs:
   test:
@@ -53,4 +53,7 @@ jobs:
         run: make lint TARGET_DIR=stress_tests
 
       - name: Lint tests code
-        run: make lint TARGET_DIR=tests
+        run: make lint TARGET_DIR=tests
+
+      - name: Lint tests examples
+        run: make lint TARGET_DIR=examples

Makefile

@@ -1,5 +1,5 @@
 TARGET_DIR = .
-POETRY_GROUPS = dev,stress_test,code_quality
+POETRY_GROUPS = dev,stress_test,code_quality,examples
 
 install:
 	poetry install --with ${POETRY_GROUPS} -E uvloop

README.md

@@ -52,17 +52,23 @@ With every call you will receive an [IoLoopMonitorState](monitored_ioloop/monito
 - `cpu_loop_duration`: The time it took to execute the current step of the event loop in CPU time.
 - `handles_count`: The amount of handles (think about them as tasks) that the IO loop is currently handling.
 
-
 ## Performance impact
-As many of you might be concerned about the performance impact of this library, I have run some benchmarks to measure the performance impact of this library.    
-You can find the results in the [following README](stress_tests/results/README.md) folder.
+As many of you might be concerned about the performance impact of this library, I have run some benchmarks to measure the performance impact of this library.  
+In summary the performance impact is negligible for most use cases.  
+You can find the more detailed information in the following [README.md](stress_tests/results/README.md).
+
+## Usage examples
+You can find examples projects showing potential use cases in the [examples](examples) folder.  
+Currently there is only the [fastapi with prometheus exporter example](examples/fastapi_with_prometheus) but more will be added in the future.
+
 
 ## Roadmap
 - [x] Add support for the amount of `Handle`'s on the event loop
+- [x] Add an examples folder
 - [ ] Add visibility into which `Handle` are making the event loop slower
 - [ ] Add easier integration with popular monitoring tools like Prometheus
 - [ ] Add easier integration with `uvicorn`
-- [ ] Add an examples folder
+
 
 ## Credits
 I took a lot of inspiration from the [uvloop](https://github.com/MagicStack/uvloop) project with everythin

examples/fastapi_with_prometheus/Makefile

@@ -0,0 +1,4 @@
+run:
+	poetry run python server.py
+create-trafiic:
+	poetry run python create_traffic.py

examples/fastapi_with_prometheus/create_traffic.py

@@ -0,0 +1,22 @@
+import random
+
+from httpx import AsyncClient
+from httpx import Limits, Timeout
+import asyncio
+
+URLS = [
+    "http://localhost:1441/ping",
+    "http://localhost:1441/async_slow?sleep_for=5&coroutines_number=10",
+    "http://localhost:1441/blocking_slow?sleep_for=1",
+]
+
+
+async def main() -> None:
+    async with AsyncClient(
+        limits=Limits(max_connections=20), timeout=Timeout(timeout=30)
+    ) as client:
+        await asyncio.gather(*[client.get(random.choice(URLS)) for _ in range(10)])
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/fastapi_with_prometheus/server.py

@@ -0,0 +1,55 @@
+import asyncio
+import time
+
+from monitored_ioloop.monitored_asyncio import MonitoredAsyncIOEventLoopPolicy
+from monitored_ioloop.monitoring import IoLoopMonitorState
+from fastapi import FastAPI
+from prometheus_client import start_http_server, Histogram
+from uvicorn import Server, Config
+
+ioloop_execution_time_histogram = Histogram(
+    "ioloop_execution_time_histogram",
+    "Histogram of the ioloop execution time",
+    buckets=[0.000001, 0.00001, 0.0001, 0.001, 0.01, 0.1, 1, 2, 4],
+)
+
+app = FastAPI()
+
+
+@app.get("/ping")
+async def ping() -> str:
+    return "pong"
+
+
+@app.get("/async_slow")
+async def async_slow(sleep_for: int, coroutines_number: int) -> str:
+    await asyncio.gather(*[asyncio.sleep(sleep_for) for _ in range(coroutines_number)])
+    return f"slept for {sleep_for} seconds and created {coroutines_number} coroutines"
+
+
+@app.get("/blocking_slow")
+async def blocking_slow(sleep_for: int) -> str:
+    time.sleep(sleep_for)
+    return f"slept for {sleep_for} seconds"
+
+
+def monitor_ioloop(ioloop_monitor_state: IoLoopMonitorState) -> None:
+    ioloop_execution_time_histogram.observe(ioloop_monitor_state.wall_loop_duration)
+
+
+def main() -> None:
+    """
+    Current because uvloop does not support settings the ioloop to a custom implementation, we need to
+    run the server manually and not from the CLI.
+    I am currently working on allowing passing an import string to a custom event loop policy which
+    will considerably simplify the fastapi example.
+    """
+    asyncio.set_event_loop_policy(MonitoredAsyncIOEventLoopPolicy(monitor_ioloop))
+    config = Config(app=app, host="localhost", port=1441, loop="asyncio")
+    server = Server(config)
+    start_http_server(1551)
+    asyncio.run(server.serve())
+
+
+if __name__ == "__main__":
+    main()

monitored_ioloop/monioted_ioloop_base.py

@@ -10,3 +10,14 @@ def __init__(
     ):
         super().__init__()
         self._monitor_callback = monitor_callback
+
+    if typing.TYPE_CHECKING:
+        # EventLoopPolicy doesn't implement these, but since they are marked
+        # as abstract in typeshed, we have to put them in so mypy thinks
+        # the base methods are overridden. This is the same approach taken
+        # for the Windows event loop policy classes in typeshed.
+        def get_child_watcher(self) -> typing.NoReturn:
+            ...
+
+        def set_child_watcher(self, watcher: typing.Any) -> typing.NoReturn:
+            ...

poetry.lock

@@ -39,6 +39,15 @@ uvicorn = "^0.27.1"
 click = "^8.1.7"
 locust = "^2.23.1"
 
+[tool.poetry.group.examples]
+optional = true
+
+[tool.poetry.group.examples.dependencies]
+fastapi = "^0.109.2"
+prometheus-client = "^0.20.0"
+httpx = "^0.27.0"
+
+
 [build-system]
 requires = ["poetry-core"]
 build-backend = "poetry.core.masonry.api"