diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..571df87 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,13 @@ +version: 2 + +build: + os: "ubuntu-22.04" + tools: + python: "3.10" + +python: + install: + - requirements: docs/requirements.txt + +mkdocs: + configuration: mkdocs.yml diff --git a/README.md b/README.md index 640dadb..0d05a82 100644 --- a/README.md +++ b/README.md @@ -6,11 +6,27 @@ Lite-Bootstrap [![downloads](https://img.shields.io/pypi/dm/lite-bootstrap.svg)](https://pypistats.org/packages/lite-bootstrap) [![GitHub stars](https://img.shields.io/github/stars/modern-python/lite-bootstrap)](https://github.com/modern-python/lite-bootstrap/stargazers) -This package helps to build new microservices +`lite-bootstrap` assists you in creating applications with all the necessary instruments already set up. -## Quickstart: -### Installation +With `lite-bootstrap`, you receive an application with lightweight built-in support for: +- `sentry` +- `prometheus` +- `opentelemetry` +- `structlog` +- `cors` +- `swagger` - with additional offline version support +- `health-checks` -```shell -$ pip install lite-bootstrap -``` +Those instruments can be bootstrapped for: + +1. LiteStar +2. FastStream +3. FastAPI +4. services and scripts without frameworks +--- + +## 📚 [Documentation](https://lite-bootstrap.readthedocs.io) + +## 📦 [PyPi](https://pypi.org/project/lite-bootstrap) + +## 📝 [License](LICENSE) diff --git a/docs/css/code.css b/docs/css/code.css new file mode 100644 index 0000000..c066a04 --- /dev/null +++ b/docs/css/code.css @@ -0,0 +1,10 @@ +/* Round the corners of code blocks */ +.md-typeset .highlight code { + border-radius: 10px !important; +} + +@media (max-width: 600px) { + .md-typeset code { + border-radius: 4px; + } +} diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..68ab3ba --- /dev/null +++ b/docs/index.md @@ -0,0 +1,22 @@ +# Lite Bootstrap + +Welcome to the `lite-bootstrap` documentation! + +`lite-bootstrap` assists you in creating applications with all the necessary instruments already set up. + +With `lite-bootstrap`, you receive an application with lightweight built-in support for: +- `sentry` +- `prometheus` +- `opentelemetry` +- `structlog` +- `cors` +- `swagger` - with additional offline version support +- `health-checks` + +Those instruments can be bootstrapped for: + +- [LiteStar](integrations/litestar) +- [FastStream](integrations/faststream) +- [FastAPI](integrations/fastapi) +- [services and scripts without frameworks](integrations/free) +--- diff --git a/docs/integrations/fastapi.md b/docs/integrations/fastapi.md new file mode 100644 index 0000000..fba0bae --- /dev/null +++ b/docs/integrations/fastapi.md @@ -0,0 +1,49 @@ +# Usage with `Fastapi` + +*Another example of usage with FastAPI - [fastapi-sqlalchemy-template](https://github.com/modern-python/fastapi-sqlalchemy-template)* + +## 1. Install `lite-bootstrapp[fastapi-all]`: + +=== "uv" + + ```bash + uv add lite-bootstrapp[fastapi-all] + ``` + +=== "pip" + + ```bash + pip install lite-bootstrapp[fastapi-all] + ``` + +=== "poetry" + + ```bash + poetry add lite-bootstrapp[fastapi-all] + ``` + +Read more about available extras [here](../../../introduction/installation): + +## 2. Define bootstrapper config and build you application: + +```python +from lite_bootstrap import FastAPIConfig, FastAPIBootstrapper + + +bootstrapper_config = FastAPIConfig( + service_name="microservice", + service_version="2.0.0", + service_environment="test", + service_debug=False, + cors_allowed_origins=["http://test"], + health_checks_path="/custom-health/", + opentelemetry_endpoint="otl", + prometheus_metrics_path="/custom-metrics/", + sentry_dsn="https://testdsn@localhost/1", + swagger_offline_docs=True, +) +bootstrapper = FastAPIBootstrapper(bootstrapper_config) +application = bootstrapper.bootstrap() +``` + +Read more about available configuration options [here](../../../introduction/configuration): diff --git a/docs/integrations/faststream.md b/docs/integrations/faststream.md new file mode 100644 index 0000000..19d831a --- /dev/null +++ b/docs/integrations/faststream.md @@ -0,0 +1,53 @@ +# Usage with `FastStream` + +## 1. Install `lite-bootstrapp[faststream-all]`: + +=== "uv" + + ```bash + uv add lite-bootstrapp[faststream-all] + ``` + +=== "pip" + + ```bash + pip install lite-bootstrapp[faststream-all] + ``` + +=== "poetry" + + ```bash + poetry add lite-bootstrapp[faststream-all] + ``` + +Read more about available extras [here](../../../introduction/installation): + +## 2. Define bootstrapper config and build you application: + +```python +from lite_bootstrap import FastStreamConfig, FastStreamBootstrapper +from faststream.redis.opentelemetry import RedisTelemetryMiddleware +from faststream.redis.prometheus import RedisPrometheusMiddleware +from faststream.redis import RedisBroker + + +broker = RedisBroker() +bootstrapper_config = FastStreamConfig( + service_name="microservice", + service_version="2.0.0", + service_environment="test", + service_debug=False, + opentelemetry_endpoint="otl", + opentelemetry_middleware_cls=RedisTelemetryMiddleware, + prometheus_metrics_path="/custom-metrics/", + prometheus_middleware_cls=RedisPrometheusMiddleware, + sentry_dsn="https://testdsn@localhost/1", + health_checks_path="/custom-health/", + logging_buffer_capacity=0, + broker=broker, +) +bootstrapper = FastStreamBootstrapper(bootstrapper_config) +application = bootstrapper.bootstrap() +``` + +Read more about available configuration options [here](../../../introduction/configuration): diff --git a/docs/integrations/free.md b/docs/integrations/free.md new file mode 100644 index 0000000..5f74c05 --- /dev/null +++ b/docs/integrations/free.md @@ -0,0 +1,40 @@ +# Usage without frameworks + +## 1. Install `lite-bootstrapp[free-all]`: + +=== "uv" + + ```bash + uv add lite-bootstrapp[free-all] + ``` + +=== "pip" + + ```bash + pip install lite-bootstrapp[free-all] + ``` + +=== "poetry" + + ```bash + poetry add lite-bootstrapp[free-all] + ``` + +Read more about available extras [here](../../../introduction/installation): + +## 2. Define bootstrapper config and build you application: + +```python +from lite_bootstrap import FreeBootstrapperConfig, FreeBootstrapper + + +bootstrapper_config = FreeBootstrapperConfig( + service_debug=False, + opentelemetry_endpoint="otl", + sentry_dsn="https://testdsn@localhost/1", +) +bootstrapper = FreeBootstrapper(bootstrapper_config) +bootstrapper.bootstrap() +``` + +Read more about available configuration options [here](../../../introduction/configuration): diff --git a/docs/integrations/litestar.md b/docs/integrations/litestar.md new file mode 100644 index 0000000..ca98070 --- /dev/null +++ b/docs/integrations/litestar.md @@ -0,0 +1,49 @@ +# Usage with `Litestar` + +*Another example of usage with LiteStar - [litestar-sqlalchemy-template](https://github.com/modern-python/litestar-sqlalchemy-template)* + +## 1. Install `lite-bootstrap[litestar-all]`: + +=== "uv" + + ```bash + uv add lite-bootstrapp[litestar-all] + ``` + +=== "pip" + + ```bash + pip install lite-bootstrapp[litestar-all] + ``` + +=== "poetry" + + ```bash + poetry add lite-bootstrapp[litestar-all] + ``` + +Read more about available extras [here](../../../introduction/installation): + +## 2. Define bootstrapper config and build you application: + +```python +from lite_bootstrap import LitestarConfig, LitestarBootstrapper + + +bootstrapper_config = LitestarConfig( + service_name="microservice", + service_version="2.0.0", + service_environment="test", + service_debug=False, + cors_allowed_origins=["http://test"], + health_checks_path="/custom-health/", + opentelemetry_endpoint="otl", + prometheus_metrics_path="/custom-metrics/", + sentry_dsn="https://testdsn@localhost/1", + swagger_offline_docs=True, +) +bootstrapper = LitestarBootstrapper(bootstrapper_config) +application = bootstrapper.bootstrap() +``` + +Read more about available configuration options [here](../../../introduction/configuration): diff --git a/docs/introduction/configuration.md b/docs/introduction/configuration.md new file mode 100644 index 0000000..5b6f0a2 --- /dev/null +++ b/docs/introduction/configuration.md @@ -0,0 +1,128 @@ +# Configuration + +## Sentry + +Sentry integration uses `sentry_sdk` package under the hood. + +To bootstrap Sentry, you must provide at least: + +- `sentry_dsn` - tells sentry-sdk where to send the events. + +Additional parameters can also be supplied through the settings object: + +- `sentry_traces_sample_rate` - in the range of 0.0 to 1.0, the percentage chance a given transaction will be sent +- `sentry_sample_rate` - in the range of 0.0 to 1.0, the sample rate for error events +- `sentry_max_breadcrumbs` - the total amount of breadcrumbs +- `sentry_max_value_length` - the max event payload length +- `sentry_attach_stacktrace` - if True, stack traces are automatically attached to all messages logged +- `sentry_integrations` - list of integrations to enable +- `sentry_tags` - key/value string pairs that are both indexed and searchable +- `sentry_additional_params** - additional params, which will be passed to `sentry_sdk.init` + +Read more about sentry_sdk params [here](https://docs.sentry.io/platforms/python/configuration/options/). + + +## Prometheus + +To bootstrap Prometheus, you must provide at least: + +- `prometheus_metrics_path`. + +Additional parameters: + +- `prometheus_metrics_include_in_schema`. + +### Prometheus Litestar + +Prometheus's integration for Litestar requires `prometheus_client` package. + +Additional parameters for Litestar integration: + +- `prometheus_additional_params` - passed to `litestar.plugins.prometheus.PrometheusConfig`. + +### Prometheus FastStream + +Prometheus's integration for FastStream requires `prometheus_client` package. + +To bootstrap Prometheus for FastStream, you must provide additionally: + +- `prometheus_middleware_cls`. + +### Prometheus FastAPI + +Prometheus's integration for FastAPI uses `prometheus_fastapi_instrumentator` package. + +Additional parameters for FastAPI integration: + +- `prometheus_instrumentator_params` - passed to `prometheus_fastapi_instrumentator.Instrumentator` +- `prometheus_instrument_params` - passed to `method Instrumentator(...).instrument` +- `prometheus_expose_params` - passed to `method Instrumentator(...).expose`. + + +## Opentelemetry + +To bootstrap Opentelemetry, you must provide at least: + +- `opentelemetry_endpoint`. + +Additional parameters: + +- `opentelemetry_service_name` +- `opentelemetry_container_name` +- `opentelemetry_endpoint` +- `opentelemetry_namespace` +- `opentelemetry_insecure` +- `opentelemetry_instrumentors` +- `opentelemetry_span_exporter` + +Additional parameters for Litestar and FastAPI: + +- `opentelemetry_excluded_urls` - by default, heath checks and metrics paths will be excluded. + +For FastStream you must provide additionally: + +- `opentelemetry_middleware_cls` + + +## Structlog + +To bootstrap Structlog, you must set `service_debug` to False + +Additional parameters: + +- `logging_log_level` +- `logging_flush_level` +- `logging_buffer_capacity` +- `logging_extra_processors` +- `logging_unset_handlers`. + +## CORS + +To bootstrap CORS headers, you must provide `cors_allowed_origins` or `cors_allowed_origin_regex`. + +Additional params: + +- `cors_allowed_methods` +- `cors_allowed_headers` +- `cors_exposed_headers` +- `cors_allowed_credentials` +- `cors_max_age` + +## Swagger + +To bootstrap swagger, you have the following parameters: + +- `swagger_static_path` - path for offline docs static +- `swagger_path` +- `swagger_offline_docs` - option to turn on offline docs. + +For Litestar `swagger_path` is required to bootstrap swagger instrument. + +## Health checks + +To bootstrap Health checks, you must provide set `health_checks_enabled` to True. + +Additional params: + +- `health_checks_path` +- `health_checks_include_in_schema` diff --git a/docs/introduction/installation.md b/docs/introduction/installation.md new file mode 100644 index 0000000..ba2b2bc --- /dev/null +++ b/docs/introduction/installation.md @@ -0,0 +1,41 @@ +# Installation + +## Choose suitable extras + +You can choose required framework and instruments using this table: + +| Instrument | Litestar | Faststream | FastAPI | Free Bootstrapper, without framework | +|---------------|--------------------|----------------------|-------------------|--------------------------------------| +| sentry | `litestar-sentry` | `faststream-sentry` | `fastapi-sentry` | `sentry` | +| prometheus | `litestar-metrics` | `faststream-metrics` | `fastapi-metrics` | not used | +| opentelemetry | `litestar-otl` | `faststream-otl` | `fastapi-otl` | `otl` | +| structlog | `litestar-logging` | `faststream-logging` | `fastapi-logging` | `logging` | +| cors | no extra | not used | no extra | not used | +| swagger | no extra | not used | no extra | not used | +| health-checks | no extra | no extra | no extra | not used | +| all | `litestar-all` | `faststream-all` | `fastapi-all` | `free-all` | + +* not used - means that the instrument is not implemented in the integration. +* no extra - means that the instrument requires no additional dependencies. + +## Install `lite-bootstrap` using your favorite tool with choosen extras + +For example, if you want to bootstrap litestar with structlog and opentelemetry instruments: + +=== "uv" + + ```bash + uv add lite-bootstrapp[litestar-logging,litestar-otl] + ``` + +=== "pip" + + ```bash + pip install lite-bootstrapp[litestar-logging,litestar-otl] + ``` + +=== "poetry" + + ```bash + poetry add lite-bootstrapp[litestar-logging,litestar-otl] + ``` diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..9a8a4ca --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,2 @@ +mkdocs +mkdocs-material diff --git a/lite_bootstrap/bootstrappers/fastapi_bootstrapper.py b/lite_bootstrap/bootstrappers/fastapi_bootstrapper.py index 7cd8960..e613193 100644 --- a/lite_bootstrap/bootstrappers/fastapi_bootstrapper.py +++ b/lite_bootstrap/bootstrappers/fastapi_bootstrapper.py @@ -130,7 +130,7 @@ def check_dependencies() -> bool: return import_checker.is_prometheus_fastapi_instrumentator_installed def bootstrap(self) -> None: - Instrumentator(**self.bootstrap_config.prometheus_instrument_params).instrument( + Instrumentator(**self.bootstrap_config.prometheus_instrumentator_params).instrument( self.bootstrap_config.application, **self.bootstrap_config.prometheus_instrument_params, ).expose( diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..0f6be7d --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,72 @@ +site_name: lite-bootstrap +repo_url: https://github.com/modern-python/lite-bootstrap +docs_dir: docs +edit_uri: edit/main/docs/ +nav: + - Introduction: + - Installation: introduction/installation.md + - Configuration: introduction/configuration.md + - Integrations: + - Litestar: integrations/litestar.md + - FastStream: integrations/faststream.md + - FastAPI: integrations/fastapi.md +theme: + name: material + features: + - content.code.copy + - content.code.annotate + - content.action.edit + - content.action.view + - navigation.footer + - navigation.sections + - navigation.expand + - navigation.top + - navigation.instant + - header.autohide + - announce.dismiss + icon: + edit: material/pencil + view: material/eye + repo: fontawesome/brands/git-alt + palette: + - media: "(prefers-color-scheme: light)" + scheme: default + primary: black + accent: pink + toggle: + icon: material/brightness-7 + name: Switch to dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: black + accent: pink + toggle: + icon: material/brightness-4 + name: Switch to system preference + +markdown_extensions: + - toc: + permalink: true + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + - pymdownx.tabbed: + alternate_style: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.superfences + - def_list + - codehilite: + use_pygments: true + - attr_list + - md_in_html + +extra_css: + - css/code.css + +extra: + social: + - icon: fontawesome/brands/github + link: https://github.com/modern-python/lite-bootstrap + name: GitHub