diff options
Diffstat (limited to 'python-starlette-exporter.spec')
| -rw-r--r-- | python-starlette-exporter.spec | 845 |
1 files changed, 845 insertions, 0 deletions
diff --git a/python-starlette-exporter.spec b/python-starlette-exporter.spec new file mode 100644 index 0000000..91ae47e --- /dev/null +++ b/python-starlette-exporter.spec @@ -0,0 +1,845 @@ +%global _empty_manifest_terminate_build 0 +Name: python-starlette-exporter +Version: 0.15.1 +Release: 1 +Summary: Prometheus metrics exporter for Starlette applications. +License: Apache License 2.0 +URL: https://github.com/stephenhillier/starlette_exporter +Source0: https://mirrors.nju.edu.cn/pypi/web/packages/7c/6d/72fbe02fd9dec57c8990f466255082a26a7b298ccf8a6960f79f3286b746/starlette_exporter-0.15.1.tar.gz +BuildArch: noarch + +Requires: python3-prometheus-client +Requires: python3-starlette + +%description +# starlette_exporter + +## Prometheus exporter for Starlette and FastAPI + +starlette_exporter collects basic metrics for Starlette and FastAPI based applications: + +* starlette_requests_total: a counter representing the total requests +* starlette_request_duration_seconds: a histogram representing the distribution of request response times +* starlette_requests_in_progress: a gauge that keeps track of how many concurrent requests are being processed + +Metrics include labels for the HTTP method, the path, and the response status code. + +``` +starlette_requests_total{method="GET",path="/",status_code="200"} 1.0 +starlette_request_duration_seconds_bucket{le="0.01",method="GET",path="/",status_code="200"} 1.0 +``` + +Use the HTTP handler `handle_metrics` at path `/metrics` to expose a metrics endpoint to Prometheus. + +## Table of Contents + +* [starlette_exporter](#starlette_exporter) + * [Prometheus exporter for Starlette and FastAPI](#prometheus-exporter-for-starlette-and-fastapi) + * [Table of Contents](#table-of-contents) + * [Usage](#usage) + * [Starlette](#starlette) + * [FastAPI](#fastapi) + * [Options](#options) + * [Labels](#labels) + * [Exemplars](#exemplars) + * [Custom Metrics](#custom-metrics) + * [Multiprocess mode (gunicorn deployments)](#multiprocess-mode-gunicorn-deployments) + * [Developing](#developing) + * [License](#license) + * [Dependencies](#dependencies) + * [Credits](#credits) + +## Usage + +```sh +pip install starlette_exporter +``` + +### Starlette + +```python +from starlette.applications import Starlette +from starlette_exporter import PrometheusMiddleware, handle_metrics + +app = Starlette() +app.add_middleware(PrometheusMiddleware) +app.add_route("/metrics", openmetrics_handler) + +... +``` + +### FastAPI + +```python +from fastapi import FastAPI +from starlette_exporter import PrometheusMiddleware, handle_metrics + +app = FastAPI() +app.add_middleware(PrometheusMiddleware) +app.add_route("/metrics", openmetrics_handler) + +... +``` + +## Options + +`app_name`: Sets the value of the `app_name` label for exported metrics (default: `starlette`). + +`prefix`: Sets the prefix of the exported metric names (default: `starlette`). + +`labels`: Optional dict containing default labels that will be added to all metrics. The values can be either a static value or a callback function that +retrieves a value from the `Request` object. [See below](#labels) for examples. + +`exemplars`: Optional dict containing label/value pairs. The "value" should be a callback function that returns the desired value at runtime. + +`group_paths`: setting this to `True` will populate the path label using named parameters (if any) in the router path, e.g. `/api/v1/items/{item_id}`. This will group requests together by endpoint (regardless of the value of `item_id`). This option may come with a performance hit for larger routers. Default is `False`, which will result in separate metrics for different URLs (e.g., `/api/v1/items/42`, `/api/v1/items/43`, etc.). + +`filter_unhandled_paths`: setting this to `True` will cause the middleware to ignore requests with unhandled paths (in other words, 404 errors). This helps prevent filling up the metrics with 404 errors and/or intentially bad requests. Default is `False`. + +`buckets`: accepts an optional list of numbers to use as histogram buckets. The default value is `None`, which will cause the library to fall back on the Prometheus defaults (currently `[0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1.0, 2.5, 5.0, 7.5, 10.0]`). + +`skip_paths`: accepts an optional list of paths that will not collect metrics. The default value is `None`, which will cause the library to collect metrics on every requested path. This option is useful to avoid collecting metrics on health check, readiness or liveness probe endpoints. + +`always_use_int_status`: accepts a boolean. The default value is False. If set to True the libary will attempt to convert the `status_code` value to an integer (e.g. if you are using HTTPStatus, HTTPStatus.OK will become 200 for all metrics). + +`optional_metrics`: a list of pre-defined metrics that can be optionally added to the default metrics. The following optional metrics are available: + +* `response_body_size`: a counter that tracks the size of response bodies for each endpoint + +For optional metric examples, [see below](#optional-metrics). + +Full example: + +```python +app.add_middleware( + PrometheusMiddleware, + app_name="hello_world", + prefix='myapp', + labels={ + "server_name": os.getenv("HOSTNAME"), + }), + group_paths=True, + buckets=[0.1, 0.25, 0.5], + skip_paths=['/health'], + always_use_int_status=False), + exemplars={"trace_id": get_trace_id} # function that returns a trace id +``` + +## Labels + +The included metrics have built-in default labels such as `app_name`, `method`, `path`, and `status_code`. Additional default labels can be +added by passing a dictionary to the `labels` arg to `PrometheusMiddleware`. Each label's value can be either a static +value or, optionally, a callback function. The built-in default label names are reserved and cannot be reused. + +If a callback function is used, it will receive the Request instance as its argument. + +```python +app.add_middleware( + PrometheusMiddleware, + labels={ + "service": "api", + "env": os.getenv("ENV") + } +``` + +Ensure that label names follow [Prometheus naming conventions](https://prometheus.io/docs/practices/naming/) and that label +values are constrained (see [this writeup from Grafana on cardinality](https://grafana.com/blog/2022/02/15/what-are-cardinality-spikes-and-why-do-they-matter/)). + +### Label helpers + +**`from_header(key: string, allowed_values: Optional[Iterable])`**: a convenience function for using a header value as a label. + +`allowed_values` allows you to supply a list of allowed values. If supplied, header values not in the list will result in +an empty string being returned. This allows you to constrain the label values, reducing the risk of excessive cardinality. + +Do not use headers that could contain unconstrained values (e.g. user id) or user-supplied values. + +```python +from starlette_exporter import PrometheusMiddleware, from_header + +app.add_middleware( + PrometheusMiddleware, + labels={ + "host": from_header("X-Internal-Org", allowed_values=("accounting", "marketing", "product")) + } +``` + +## Exemplars + +Exemplars are used for labeling histogram observations or counter increments with a trace id. This allows adding +trace ids to your charts (for example, latency graphs could include traces corresponding to various latency buckets). + +To add exemplars to `starlette_exporter` metrics, pass a dict to the PrometheusMiddleware class with label as well as +a callback function that returns a string (typically the current trace id). + +**Example:** + +```python +# must use `handle_openmetrics` instead of `handle_metrics` for exemplars to appear in /metrics output. +from starlette_exporter import PrometheusMiddleware, handle_openmetrics + +app.add_middleware( + PrometheusMiddleware, + exemplars={"trace_id": get_trace_id} # supply your own callback function +) + +app.add_route("/metrics", handle_openmetrics) +``` + +Exemplars are only supported by the openmetrics-text exposition format. A new `handle_openmetrics` handler function is provided +(see above example). + +For more information, see the [Grafana exemplar documentation](https://grafana.com/docs/grafana/latest/fundamentals/exemplars/). + +## Optional metrics + +Optional metrics are pre-defined metrics that can be added to the default metrics. + +* `response_body_size`: the size of response bodies returned, in bytes +* `request_body_size`: the size of request bodies received, in bytes + +**Example**: + +```python +from fastapi import FastAPI +from starlette_exporter import PrometheusMiddleware, handle_metrics +from starlette_exporter.optional_metrics import response_body_size, request_body_size + +app = FastAPI() +app.add_middleware(PrometheusMiddleware, optional_metrics=[response_body_size, request_body_size]) +``` + +## Custom Metrics + +starlette_exporter will export all the prometheus metrics from the process, so custom metrics can be created by using the prometheus_client API. + +**Example**: + +```python +from prometheus_client import Counter +from starlette.responses import RedirectResponse + +REDIRECT_COUNT = Counter("redirect_total", "Count of redirects", ["redirected_from"]) + +async def some_view(request): + REDIRECT_COUNT.labels("some_view").inc() + return RedirectResponse(url="https://example.com", status_code=302) +``` + +The new metric will now be included in the the `/metrics` endpoint output: + +``` +... +redirect_total{redirected_from="some_view"} 2.0 +... +``` + +## Multiprocess mode (gunicorn deployments) + +Running starlette_exporter in a multiprocess deployment (e.g. with gunicorn) will need the `PROMETHEUS_MULTIPROC_DIR` env variable set, as well as extra gunicorn config. + +For more information, see the [Prometheus Python client documentation](https://github.com/prometheus/client_python#multiprocess-mode-eg-gunicorn). + +## Developing + +This package supports Python 3.6+. + +```sh +git clone https://github.com/stephenhillier/starlette_exporter +cd starlette_exporter +pytest tests +``` + +## License + +Code released under the [Apache License, Version 2.0](./LICENSE). + +## Dependencies + +https://github.com/prometheus/client_python (>= 0.12) + +https://github.com/encode/starlette + +## Credits + +Starlette - https://github.com/encode/starlette + +FastAPI - https://github.com/tiangolo/fastapi + +Flask exporter - https://github.com/rycus86/prometheus_flask_exporter + +Alternate Starlette exporter - https://github.com/perdy/starlette-prometheus + + +%package -n python3-starlette-exporter +Summary: Prometheus metrics exporter for Starlette applications. +Provides: python-starlette-exporter +BuildRequires: python3-devel +BuildRequires: python3-setuptools +BuildRequires: python3-pip +%description -n python3-starlette-exporter +# starlette_exporter + +## Prometheus exporter for Starlette and FastAPI + +starlette_exporter collects basic metrics for Starlette and FastAPI based applications: + +* starlette_requests_total: a counter representing the total requests +* starlette_request_duration_seconds: a histogram representing the distribution of request response times +* starlette_requests_in_progress: a gauge that keeps track of how many concurrent requests are being processed + +Metrics include labels for the HTTP method, the path, and the response status code. + +``` +starlette_requests_total{method="GET",path="/",status_code="200"} 1.0 +starlette_request_duration_seconds_bucket{le="0.01",method="GET",path="/",status_code="200"} 1.0 +``` + +Use the HTTP handler `handle_metrics` at path `/metrics` to expose a metrics endpoint to Prometheus. + +## Table of Contents + +* [starlette_exporter](#starlette_exporter) + * [Prometheus exporter for Starlette and FastAPI](#prometheus-exporter-for-starlette-and-fastapi) + * [Table of Contents](#table-of-contents) + * [Usage](#usage) + * [Starlette](#starlette) + * [FastAPI](#fastapi) + * [Options](#options) + * [Labels](#labels) + * [Exemplars](#exemplars) + * [Custom Metrics](#custom-metrics) + * [Multiprocess mode (gunicorn deployments)](#multiprocess-mode-gunicorn-deployments) + * [Developing](#developing) + * [License](#license) + * [Dependencies](#dependencies) + * [Credits](#credits) + +## Usage + +```sh +pip install starlette_exporter +``` + +### Starlette + +```python +from starlette.applications import Starlette +from starlette_exporter import PrometheusMiddleware, handle_metrics + +app = Starlette() +app.add_middleware(PrometheusMiddleware) +app.add_route("/metrics", openmetrics_handler) + +... +``` + +### FastAPI + +```python +from fastapi import FastAPI +from starlette_exporter import PrometheusMiddleware, handle_metrics + +app = FastAPI() +app.add_middleware(PrometheusMiddleware) +app.add_route("/metrics", openmetrics_handler) + +... +``` + +## Options + +`app_name`: Sets the value of the `app_name` label for exported metrics (default: `starlette`). + +`prefix`: Sets the prefix of the exported metric names (default: `starlette`). + +`labels`: Optional dict containing default labels that will be added to all metrics. The values can be either a static value or a callback function that +retrieves a value from the `Request` object. [See below](#labels) for examples. + +`exemplars`: Optional dict containing label/value pairs. The "value" should be a callback function that returns the desired value at runtime. + +`group_paths`: setting this to `True` will populate the path label using named parameters (if any) in the router path, e.g. `/api/v1/items/{item_id}`. This will group requests together by endpoint (regardless of the value of `item_id`). This option may come with a performance hit for larger routers. Default is `False`, which will result in separate metrics for different URLs (e.g., `/api/v1/items/42`, `/api/v1/items/43`, etc.). + +`filter_unhandled_paths`: setting this to `True` will cause the middleware to ignore requests with unhandled paths (in other words, 404 errors). This helps prevent filling up the metrics with 404 errors and/or intentially bad requests. Default is `False`. + +`buckets`: accepts an optional list of numbers to use as histogram buckets. The default value is `None`, which will cause the library to fall back on the Prometheus defaults (currently `[0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1.0, 2.5, 5.0, 7.5, 10.0]`). + +`skip_paths`: accepts an optional list of paths that will not collect metrics. The default value is `None`, which will cause the library to collect metrics on every requested path. This option is useful to avoid collecting metrics on health check, readiness or liveness probe endpoints. + +`always_use_int_status`: accepts a boolean. The default value is False. If set to True the libary will attempt to convert the `status_code` value to an integer (e.g. if you are using HTTPStatus, HTTPStatus.OK will become 200 for all metrics). + +`optional_metrics`: a list of pre-defined metrics that can be optionally added to the default metrics. The following optional metrics are available: + +* `response_body_size`: a counter that tracks the size of response bodies for each endpoint + +For optional metric examples, [see below](#optional-metrics). + +Full example: + +```python +app.add_middleware( + PrometheusMiddleware, + app_name="hello_world", + prefix='myapp', + labels={ + "server_name": os.getenv("HOSTNAME"), + }), + group_paths=True, + buckets=[0.1, 0.25, 0.5], + skip_paths=['/health'], + always_use_int_status=False), + exemplars={"trace_id": get_trace_id} # function that returns a trace id +``` + +## Labels + +The included metrics have built-in default labels such as `app_name`, `method`, `path`, and `status_code`. Additional default labels can be +added by passing a dictionary to the `labels` arg to `PrometheusMiddleware`. Each label's value can be either a static +value or, optionally, a callback function. The built-in default label names are reserved and cannot be reused. + +If a callback function is used, it will receive the Request instance as its argument. + +```python +app.add_middleware( + PrometheusMiddleware, + labels={ + "service": "api", + "env": os.getenv("ENV") + } +``` + +Ensure that label names follow [Prometheus naming conventions](https://prometheus.io/docs/practices/naming/) and that label +values are constrained (see [this writeup from Grafana on cardinality](https://grafana.com/blog/2022/02/15/what-are-cardinality-spikes-and-why-do-they-matter/)). + +### Label helpers + +**`from_header(key: string, allowed_values: Optional[Iterable])`**: a convenience function for using a header value as a label. + +`allowed_values` allows you to supply a list of allowed values. If supplied, header values not in the list will result in +an empty string being returned. This allows you to constrain the label values, reducing the risk of excessive cardinality. + +Do not use headers that could contain unconstrained values (e.g. user id) or user-supplied values. + +```python +from starlette_exporter import PrometheusMiddleware, from_header + +app.add_middleware( + PrometheusMiddleware, + labels={ + "host": from_header("X-Internal-Org", allowed_values=("accounting", "marketing", "product")) + } +``` + +## Exemplars + +Exemplars are used for labeling histogram observations or counter increments with a trace id. This allows adding +trace ids to your charts (for example, latency graphs could include traces corresponding to various latency buckets). + +To add exemplars to `starlette_exporter` metrics, pass a dict to the PrometheusMiddleware class with label as well as +a callback function that returns a string (typically the current trace id). + +**Example:** + +```python +# must use `handle_openmetrics` instead of `handle_metrics` for exemplars to appear in /metrics output. +from starlette_exporter import PrometheusMiddleware, handle_openmetrics + +app.add_middleware( + PrometheusMiddleware, + exemplars={"trace_id": get_trace_id} # supply your own callback function +) + +app.add_route("/metrics", handle_openmetrics) +``` + +Exemplars are only supported by the openmetrics-text exposition format. A new `handle_openmetrics` handler function is provided +(see above example). + +For more information, see the [Grafana exemplar documentation](https://grafana.com/docs/grafana/latest/fundamentals/exemplars/). + +## Optional metrics + +Optional metrics are pre-defined metrics that can be added to the default metrics. + +* `response_body_size`: the size of response bodies returned, in bytes +* `request_body_size`: the size of request bodies received, in bytes + +**Example**: + +```python +from fastapi import FastAPI +from starlette_exporter import PrometheusMiddleware, handle_metrics +from starlette_exporter.optional_metrics import response_body_size, request_body_size + +app = FastAPI() +app.add_middleware(PrometheusMiddleware, optional_metrics=[response_body_size, request_body_size]) +``` + +## Custom Metrics + +starlette_exporter will export all the prometheus metrics from the process, so custom metrics can be created by using the prometheus_client API. + +**Example**: + +```python +from prometheus_client import Counter +from starlette.responses import RedirectResponse + +REDIRECT_COUNT = Counter("redirect_total", "Count of redirects", ["redirected_from"]) + +async def some_view(request): + REDIRECT_COUNT.labels("some_view").inc() + return RedirectResponse(url="https://example.com", status_code=302) +``` + +The new metric will now be included in the the `/metrics` endpoint output: + +``` +... +redirect_total{redirected_from="some_view"} 2.0 +... +``` + +## Multiprocess mode (gunicorn deployments) + +Running starlette_exporter in a multiprocess deployment (e.g. with gunicorn) will need the `PROMETHEUS_MULTIPROC_DIR` env variable set, as well as extra gunicorn config. + +For more information, see the [Prometheus Python client documentation](https://github.com/prometheus/client_python#multiprocess-mode-eg-gunicorn). + +## Developing + +This package supports Python 3.6+. + +```sh +git clone https://github.com/stephenhillier/starlette_exporter +cd starlette_exporter +pytest tests +``` + +## License + +Code released under the [Apache License, Version 2.0](./LICENSE). + +## Dependencies + +https://github.com/prometheus/client_python (>= 0.12) + +https://github.com/encode/starlette + +## Credits + +Starlette - https://github.com/encode/starlette + +FastAPI - https://github.com/tiangolo/fastapi + +Flask exporter - https://github.com/rycus86/prometheus_flask_exporter + +Alternate Starlette exporter - https://github.com/perdy/starlette-prometheus + + +%package help +Summary: Development documents and examples for starlette-exporter +Provides: python3-starlette-exporter-doc +%description help +# starlette_exporter + +## Prometheus exporter for Starlette and FastAPI + +starlette_exporter collects basic metrics for Starlette and FastAPI based applications: + +* starlette_requests_total: a counter representing the total requests +* starlette_request_duration_seconds: a histogram representing the distribution of request response times +* starlette_requests_in_progress: a gauge that keeps track of how many concurrent requests are being processed + +Metrics include labels for the HTTP method, the path, and the response status code. + +``` +starlette_requests_total{method="GET",path="/",status_code="200"} 1.0 +starlette_request_duration_seconds_bucket{le="0.01",method="GET",path="/",status_code="200"} 1.0 +``` + +Use the HTTP handler `handle_metrics` at path `/metrics` to expose a metrics endpoint to Prometheus. + +## Table of Contents + +* [starlette_exporter](#starlette_exporter) + * [Prometheus exporter for Starlette and FastAPI](#prometheus-exporter-for-starlette-and-fastapi) + * [Table of Contents](#table-of-contents) + * [Usage](#usage) + * [Starlette](#starlette) + * [FastAPI](#fastapi) + * [Options](#options) + * [Labels](#labels) + * [Exemplars](#exemplars) + * [Custom Metrics](#custom-metrics) + * [Multiprocess mode (gunicorn deployments)](#multiprocess-mode-gunicorn-deployments) + * [Developing](#developing) + * [License](#license) + * [Dependencies](#dependencies) + * [Credits](#credits) + +## Usage + +```sh +pip install starlette_exporter +``` + +### Starlette + +```python +from starlette.applications import Starlette +from starlette_exporter import PrometheusMiddleware, handle_metrics + +app = Starlette() +app.add_middleware(PrometheusMiddleware) +app.add_route("/metrics", openmetrics_handler) + +... +``` + +### FastAPI + +```python +from fastapi import FastAPI +from starlette_exporter import PrometheusMiddleware, handle_metrics + +app = FastAPI() +app.add_middleware(PrometheusMiddleware) +app.add_route("/metrics", openmetrics_handler) + +... +``` + +## Options + +`app_name`: Sets the value of the `app_name` label for exported metrics (default: `starlette`). + +`prefix`: Sets the prefix of the exported metric names (default: `starlette`). + +`labels`: Optional dict containing default labels that will be added to all metrics. The values can be either a static value or a callback function that +retrieves a value from the `Request` object. [See below](#labels) for examples. + +`exemplars`: Optional dict containing label/value pairs. The "value" should be a callback function that returns the desired value at runtime. + +`group_paths`: setting this to `True` will populate the path label using named parameters (if any) in the router path, e.g. `/api/v1/items/{item_id}`. This will group requests together by endpoint (regardless of the value of `item_id`). This option may come with a performance hit for larger routers. Default is `False`, which will result in separate metrics for different URLs (e.g., `/api/v1/items/42`, `/api/v1/items/43`, etc.). + +`filter_unhandled_paths`: setting this to `True` will cause the middleware to ignore requests with unhandled paths (in other words, 404 errors). This helps prevent filling up the metrics with 404 errors and/or intentially bad requests. Default is `False`. + +`buckets`: accepts an optional list of numbers to use as histogram buckets. The default value is `None`, which will cause the library to fall back on the Prometheus defaults (currently `[0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1.0, 2.5, 5.0, 7.5, 10.0]`). + +`skip_paths`: accepts an optional list of paths that will not collect metrics. The default value is `None`, which will cause the library to collect metrics on every requested path. This option is useful to avoid collecting metrics on health check, readiness or liveness probe endpoints. + +`always_use_int_status`: accepts a boolean. The default value is False. If set to True the libary will attempt to convert the `status_code` value to an integer (e.g. if you are using HTTPStatus, HTTPStatus.OK will become 200 for all metrics). + +`optional_metrics`: a list of pre-defined metrics that can be optionally added to the default metrics. The following optional metrics are available: + +* `response_body_size`: a counter that tracks the size of response bodies for each endpoint + +For optional metric examples, [see below](#optional-metrics). + +Full example: + +```python +app.add_middleware( + PrometheusMiddleware, + app_name="hello_world", + prefix='myapp', + labels={ + "server_name": os.getenv("HOSTNAME"), + }), + group_paths=True, + buckets=[0.1, 0.25, 0.5], + skip_paths=['/health'], + always_use_int_status=False), + exemplars={"trace_id": get_trace_id} # function that returns a trace id +``` + +## Labels + +The included metrics have built-in default labels such as `app_name`, `method`, `path`, and `status_code`. Additional default labels can be +added by passing a dictionary to the `labels` arg to `PrometheusMiddleware`. Each label's value can be either a static +value or, optionally, a callback function. The built-in default label names are reserved and cannot be reused. + +If a callback function is used, it will receive the Request instance as its argument. + +```python +app.add_middleware( + PrometheusMiddleware, + labels={ + "service": "api", + "env": os.getenv("ENV") + } +``` + +Ensure that label names follow [Prometheus naming conventions](https://prometheus.io/docs/practices/naming/) and that label +values are constrained (see [this writeup from Grafana on cardinality](https://grafana.com/blog/2022/02/15/what-are-cardinality-spikes-and-why-do-they-matter/)). + +### Label helpers + +**`from_header(key: string, allowed_values: Optional[Iterable])`**: a convenience function for using a header value as a label. + +`allowed_values` allows you to supply a list of allowed values. If supplied, header values not in the list will result in +an empty string being returned. This allows you to constrain the label values, reducing the risk of excessive cardinality. + +Do not use headers that could contain unconstrained values (e.g. user id) or user-supplied values. + +```python +from starlette_exporter import PrometheusMiddleware, from_header + +app.add_middleware( + PrometheusMiddleware, + labels={ + "host": from_header("X-Internal-Org", allowed_values=("accounting", "marketing", "product")) + } +``` + +## Exemplars + +Exemplars are used for labeling histogram observations or counter increments with a trace id. This allows adding +trace ids to your charts (for example, latency graphs could include traces corresponding to various latency buckets). + +To add exemplars to `starlette_exporter` metrics, pass a dict to the PrometheusMiddleware class with label as well as +a callback function that returns a string (typically the current trace id). + +**Example:** + +```python +# must use `handle_openmetrics` instead of `handle_metrics` for exemplars to appear in /metrics output. +from starlette_exporter import PrometheusMiddleware, handle_openmetrics + +app.add_middleware( + PrometheusMiddleware, + exemplars={"trace_id": get_trace_id} # supply your own callback function +) + +app.add_route("/metrics", handle_openmetrics) +``` + +Exemplars are only supported by the openmetrics-text exposition format. A new `handle_openmetrics` handler function is provided +(see above example). + +For more information, see the [Grafana exemplar documentation](https://grafana.com/docs/grafana/latest/fundamentals/exemplars/). + +## Optional metrics + +Optional metrics are pre-defined metrics that can be added to the default metrics. + +* `response_body_size`: the size of response bodies returned, in bytes +* `request_body_size`: the size of request bodies received, in bytes + +**Example**: + +```python +from fastapi import FastAPI +from starlette_exporter import PrometheusMiddleware, handle_metrics +from starlette_exporter.optional_metrics import response_body_size, request_body_size + +app = FastAPI() +app.add_middleware(PrometheusMiddleware, optional_metrics=[response_body_size, request_body_size]) +``` + +## Custom Metrics + +starlette_exporter will export all the prometheus metrics from the process, so custom metrics can be created by using the prometheus_client API. + +**Example**: + +```python +from prometheus_client import Counter +from starlette.responses import RedirectResponse + +REDIRECT_COUNT = Counter("redirect_total", "Count of redirects", ["redirected_from"]) + +async def some_view(request): + REDIRECT_COUNT.labels("some_view").inc() + return RedirectResponse(url="https://example.com", status_code=302) +``` + +The new metric will now be included in the the `/metrics` endpoint output: + +``` +... +redirect_total{redirected_from="some_view"} 2.0 +... +``` + +## Multiprocess mode (gunicorn deployments) + +Running starlette_exporter in a multiprocess deployment (e.g. with gunicorn) will need the `PROMETHEUS_MULTIPROC_DIR` env variable set, as well as extra gunicorn config. + +For more information, see the [Prometheus Python client documentation](https://github.com/prometheus/client_python#multiprocess-mode-eg-gunicorn). + +## Developing + +This package supports Python 3.6+. + +```sh +git clone https://github.com/stephenhillier/starlette_exporter +cd starlette_exporter +pytest tests +``` + +## License + +Code released under the [Apache License, Version 2.0](./LICENSE). + +## Dependencies + +https://github.com/prometheus/client_python (>= 0.12) + +https://github.com/encode/starlette + +## Credits + +Starlette - https://github.com/encode/starlette + +FastAPI - https://github.com/tiangolo/fastapi + +Flask exporter - https://github.com/rycus86/prometheus_flask_exporter + +Alternate Starlette exporter - https://github.com/perdy/starlette-prometheus + + +%prep +%autosetup -n starlette-exporter-0.15.1 + +%build +%py3_build + +%install +%py3_install +install -d -m755 %{buildroot}/%{_pkgdocdir} +if [ -d doc ]; then cp -arf doc %{buildroot}/%{_pkgdocdir}; fi +if [ -d docs ]; then cp -arf docs %{buildroot}/%{_pkgdocdir}; fi +if [ -d example ]; then cp -arf example %{buildroot}/%{_pkgdocdir}; fi +if [ -d examples ]; then cp -arf examples %{buildroot}/%{_pkgdocdir}; fi +pushd %{buildroot} +if [ -d usr/lib ]; then + find usr/lib -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/lib64 ]; then + find usr/lib64 -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/bin ]; then + find usr/bin -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/sbin ]; then + find usr/sbin -type f -printf "/%h/%f\n" >> filelist.lst +fi +touch doclist.lst +if [ -d usr/share/man ]; then + find usr/share/man -type f -printf "/%h/%f.gz\n" >> doclist.lst +fi +popd +mv %{buildroot}/filelist.lst . +mv %{buildroot}/doclist.lst . + +%files -n python3-starlette-exporter -f filelist.lst +%dir %{python3_sitelib}/* + +%files help -f doclist.lst +%{_docdir}/* + +%changelog +* Mon Apr 10 2023 Python_Bot <Python_Bot@openeuler.org> - 0.15.1-1 +- Package Spec generated |