diff options
| -rw-r--r-- | .gitignore | 1 | ||||
| -rw-r--r-- | python-xraysink.spec | 523 | ||||
| -rw-r--r-- | sources | 1 |
3 files changed, 525 insertions, 0 deletions
@@ -0,0 +1 @@ +/xraysink-1.6.1.tar.gz diff --git a/python-xraysink.spec b/python-xraysink.spec new file mode 100644 index 0000000..e682444 --- /dev/null +++ b/python-xraysink.spec @@ -0,0 +1,523 @@ +%global _empty_manifest_terminate_build 0 +Name: python-xraysink +Version: 1.6.1 +Release: 1 +Summary: Instrument asyncio Python for distributed tracing with AWS X-Ray. +License: Apache 2.0 +URL: https://github.com/garyd203/xraysink +Source0: https://mirrors.nju.edu.cn/pypi/web/packages/cb/1e/3772d5ca59f3841fbc15cf8da520217ac4ddd7fc6a3feec89efacb7dbf64/xraysink-1.6.1.tar.gz +BuildArch: noarch + +Requires: python3-aiohttp +Requires: python3-async-asgi-testclient +Requires: python3-aws_xray_sdk +Requires: python3-black +Requires: python3-coverage[toml] +Requires: python3-coverage[toml] +Requires: python3-fastapi +Requires: python3-flake8 +Requires: python3-flake8-bugbear +Requires: python3-flake8-builtins +Requires: python3-flake8-comprehensions +Requires: python3-flake8-eradicate +Requires: python3-flake8-executable +Requires: python3-flake8-implicit-str-concat +Requires: python3-flake8-import-order +Requires: python3-flake8-logging-format +Requires: python3-flake8-print +Requires: python3-flake8-pytest-style +Requires: python3-flake8-simplify +Requires: python3-flake8-string-format +Requires: python3-flake8-use-fstring +Requires: python3-pytest +Requires: python3-pytest-asyncio +Requires: python3-pytest-cov +Requires: python3-setuptools +Requires: python3-wrapt +Requires: python3-yamllint +Requires: python3-zimports + +%description +# xraysink + +<div align="center"> + <a href="https://pypi.org/project/xraysink/"> + <img src="https://img.shields.io/pypi/v/xraysink.svg" alt="Package version"> + </a> + <a href="https://pypi.org/project/xraysink/"> + <img src="https://img.shields.io/pypi/pyversions/xraysink.svg" alt="Python versions"> + </a> + <a href="https://pypi.org/project/xraysink/"> + <img src="https://img.shields.io/pypi/dm/xraysink.svg" alt="Monthly downloads"> + </a> +</div> +<div align="center"> + <!-- Coverage badge stored in our wiki by the python-coverage-comment-action plugin --> + <a href="https://github.com/garyd203/xraysink/"> + <img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/wiki/garyd203/xraysink/python-coverage-comment-action-badge.json" alt="Coverage"> + </a> +</div> + +Extra AWS X-Ray instrumentation to use distributed tracing with asyncio Python +libraries that are not (yet) supported by the official +[aws_xray_sdk](https://github.com/aws/aws-xray-sdk-python) library. + + +## Integrations Supported +* Generic ASGI-compatible tracing middleware for *any* ASGI-compliant web + framework. This has been tested with: + - [aiohttp server](https://docs.aiohttp.org/en/stable/) + - [FastAPI](https://fastapi.tiangolo.com/) +* asyncio [Task's](https://docs.python.org/3/library/asyncio-task.html) +* Background jobs/tasks + +## Installation +xraysink is distributed as a standard python package through +[pypi](https://pypi.org/), so you can install it with your favourite Python +package manager. For example: + + pip install xraysink + + +## How to use +`xraysink` augments the functionality provided by `aws_xray_sdk`. Before +using the tools in `xraysink`, you first need to configure `aws_xray_sdk` - +this will probably involve calling `xray_recorder.configure()` when your +process starts, and optionally `aws_xray_sdk.core.patch()`. + +Extra instrumentation provided by `xraysink` is described below. + +### FastAPI +Instrument incoming requests in your FastAPI web server by adding the +`xray_middleware` to your app. For example, you could do: + + from starlette.middleware.base import BaseHTTPMiddleware + from xraysink.asgi.middleware import xray_middleware + + # Standard asyncio X-Ray configuration, customise as you choose + xray_recorder.configure(context=AsyncContext(), service="my-cute-little-service") + + # Create a FastAPI app with various middleware + app = FastAPI() + app.add_middleware(MyTracingDependentMiddleware) # Any middleware that is added earlier will have the X-Ray tracing context available to it + app.add_middleware(BaseHTTPMiddleware, dispatch=xray_middleware) + + +### Asyncio Tasks +If you start asyncio [Task's](https://docs.python.org/3/library/asyncio-task.html) +from a standard request handler, then the AWS X-Ray SDK will not correctly +instrument any outgoing requests made inside those Tasks. + +Use the fixed `AsyncContext` from `xraysink` as a drop-in replacement, like so: + + from aws_xray_sdk.core import xray_recorder + from xraysink.context import AsyncContext # NB: Use the AsyncContext from xraysink + + # Use the fixed AsyncContext when configuring X-Ray, + # and customise other configuration as you choose. + xray_recorder.configure(context=AsyncContext(use_task_factory=True)) + + +### Background Jobs/Tasks +If your process starts background tasks that make network calls (eg. to the +database or an API in another service), then each execution of one of those +tasks should be treated as a new X-Ray trace. Indeed, if you don't do so then +you will likely get `context_missing` errors. + +An async function that implements a background task can be easily instrumented +using the `@xray_task_async()` decorator, like so: + + from aws_xray_sdk.core import xray_recorder + from xraysink.tasks import xray_task_async + + # Standard asyncio X-Ray configuration, customise as you choose + xray_recorder.configure(context=AsyncContext(), service="my-cute-little-service") + + # Any call to this function will start a new X-Ray trace + @xray_task_async() + async def cleanup_stale_tokens(): + await database.get_table("tokens").delete(age__gt=1) + + # Start your background task using your scheduling system of choice :) + schedule_recurring_task(cleanup_stale_tokens) + +If your background task functions are called from a function that is already +instrumented (eg. send an email immediately after handling a request), then +the background task will appear as a child segment of that trace. In this case, +you must ensure you use the non-buggy `AsyncContext` when configuring the recorder +(ie. `from xraysink.context import AsyncContext`) + + +### CloudWatch Logs integration +You can link your X-Ray traces to your CloudWatch Logs log records, which +enhances the integration with AWS CloudWatch ServiceLens. Take the following +steps: + +1. Put the X-Ray trace ID into every log message. There is no convention for + how to do this (it just has to appear verbatim in the log message + somewhere), but if you are using structured logging then the convention is + to use a field called `traceId`. Here's an example + + trace_id = xray_recorder.get_trace_entity().trace_id + logging.getLogger("example").info("Hello World!", extra={"traceId": trace_id}) + +1. Explicitly set the name of the CloudWatch Logs log group associated with + your process. There is no general way to detect the Log Group from inside + the process, hence it requires manual configuration as part of your process + initialisation (eg. in the same place where you call + `xray_recorder.configure`). + + set_xray_log_group("/example/service-name") + +Note that this feature relies on undocumented functionality, and is +[not yet](https://github.com/aws/aws-xray-sdk-python/issues/188) +supported by the official Python SDK. + + +## Licence +This project uses the Apache 2.0 licence, to make it compatible with +[aws_xray_sdk](https://github.com/aws/aws-xray-sdk-python), the +primary library for integrating with AWS X-Ray. + + + +%package -n python3-xraysink +Summary: Instrument asyncio Python for distributed tracing with AWS X-Ray. +Provides: python-xraysink +BuildRequires: python3-devel +BuildRequires: python3-setuptools +BuildRequires: python3-pip +%description -n python3-xraysink +# xraysink + +<div align="center"> + <a href="https://pypi.org/project/xraysink/"> + <img src="https://img.shields.io/pypi/v/xraysink.svg" alt="Package version"> + </a> + <a href="https://pypi.org/project/xraysink/"> + <img src="https://img.shields.io/pypi/pyversions/xraysink.svg" alt="Python versions"> + </a> + <a href="https://pypi.org/project/xraysink/"> + <img src="https://img.shields.io/pypi/dm/xraysink.svg" alt="Monthly downloads"> + </a> +</div> +<div align="center"> + <!-- Coverage badge stored in our wiki by the python-coverage-comment-action plugin --> + <a href="https://github.com/garyd203/xraysink/"> + <img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/wiki/garyd203/xraysink/python-coverage-comment-action-badge.json" alt="Coverage"> + </a> +</div> + +Extra AWS X-Ray instrumentation to use distributed tracing with asyncio Python +libraries that are not (yet) supported by the official +[aws_xray_sdk](https://github.com/aws/aws-xray-sdk-python) library. + + +## Integrations Supported +* Generic ASGI-compatible tracing middleware for *any* ASGI-compliant web + framework. This has been tested with: + - [aiohttp server](https://docs.aiohttp.org/en/stable/) + - [FastAPI](https://fastapi.tiangolo.com/) +* asyncio [Task's](https://docs.python.org/3/library/asyncio-task.html) +* Background jobs/tasks + +## Installation +xraysink is distributed as a standard python package through +[pypi](https://pypi.org/), so you can install it with your favourite Python +package manager. For example: + + pip install xraysink + + +## How to use +`xraysink` augments the functionality provided by `aws_xray_sdk`. Before +using the tools in `xraysink`, you first need to configure `aws_xray_sdk` - +this will probably involve calling `xray_recorder.configure()` when your +process starts, and optionally `aws_xray_sdk.core.patch()`. + +Extra instrumentation provided by `xraysink` is described below. + +### FastAPI +Instrument incoming requests in your FastAPI web server by adding the +`xray_middleware` to your app. For example, you could do: + + from starlette.middleware.base import BaseHTTPMiddleware + from xraysink.asgi.middleware import xray_middleware + + # Standard asyncio X-Ray configuration, customise as you choose + xray_recorder.configure(context=AsyncContext(), service="my-cute-little-service") + + # Create a FastAPI app with various middleware + app = FastAPI() + app.add_middleware(MyTracingDependentMiddleware) # Any middleware that is added earlier will have the X-Ray tracing context available to it + app.add_middleware(BaseHTTPMiddleware, dispatch=xray_middleware) + + +### Asyncio Tasks +If you start asyncio [Task's](https://docs.python.org/3/library/asyncio-task.html) +from a standard request handler, then the AWS X-Ray SDK will not correctly +instrument any outgoing requests made inside those Tasks. + +Use the fixed `AsyncContext` from `xraysink` as a drop-in replacement, like so: + + from aws_xray_sdk.core import xray_recorder + from xraysink.context import AsyncContext # NB: Use the AsyncContext from xraysink + + # Use the fixed AsyncContext when configuring X-Ray, + # and customise other configuration as you choose. + xray_recorder.configure(context=AsyncContext(use_task_factory=True)) + + +### Background Jobs/Tasks +If your process starts background tasks that make network calls (eg. to the +database or an API in another service), then each execution of one of those +tasks should be treated as a new X-Ray trace. Indeed, if you don't do so then +you will likely get `context_missing` errors. + +An async function that implements a background task can be easily instrumented +using the `@xray_task_async()` decorator, like so: + + from aws_xray_sdk.core import xray_recorder + from xraysink.tasks import xray_task_async + + # Standard asyncio X-Ray configuration, customise as you choose + xray_recorder.configure(context=AsyncContext(), service="my-cute-little-service") + + # Any call to this function will start a new X-Ray trace + @xray_task_async() + async def cleanup_stale_tokens(): + await database.get_table("tokens").delete(age__gt=1) + + # Start your background task using your scheduling system of choice :) + schedule_recurring_task(cleanup_stale_tokens) + +If your background task functions are called from a function that is already +instrumented (eg. send an email immediately after handling a request), then +the background task will appear as a child segment of that trace. In this case, +you must ensure you use the non-buggy `AsyncContext` when configuring the recorder +(ie. `from xraysink.context import AsyncContext`) + + +### CloudWatch Logs integration +You can link your X-Ray traces to your CloudWatch Logs log records, which +enhances the integration with AWS CloudWatch ServiceLens. Take the following +steps: + +1. Put the X-Ray trace ID into every log message. There is no convention for + how to do this (it just has to appear verbatim in the log message + somewhere), but if you are using structured logging then the convention is + to use a field called `traceId`. Here's an example + + trace_id = xray_recorder.get_trace_entity().trace_id + logging.getLogger("example").info("Hello World!", extra={"traceId": trace_id}) + +1. Explicitly set the name of the CloudWatch Logs log group associated with + your process. There is no general way to detect the Log Group from inside + the process, hence it requires manual configuration as part of your process + initialisation (eg. in the same place where you call + `xray_recorder.configure`). + + set_xray_log_group("/example/service-name") + +Note that this feature relies on undocumented functionality, and is +[not yet](https://github.com/aws/aws-xray-sdk-python/issues/188) +supported by the official Python SDK. + + +## Licence +This project uses the Apache 2.0 licence, to make it compatible with +[aws_xray_sdk](https://github.com/aws/aws-xray-sdk-python), the +primary library for integrating with AWS X-Ray. + + + +%package help +Summary: Development documents and examples for xraysink +Provides: python3-xraysink-doc +%description help +# xraysink + +<div align="center"> + <a href="https://pypi.org/project/xraysink/"> + <img src="https://img.shields.io/pypi/v/xraysink.svg" alt="Package version"> + </a> + <a href="https://pypi.org/project/xraysink/"> + <img src="https://img.shields.io/pypi/pyversions/xraysink.svg" alt="Python versions"> + </a> + <a href="https://pypi.org/project/xraysink/"> + <img src="https://img.shields.io/pypi/dm/xraysink.svg" alt="Monthly downloads"> + </a> +</div> +<div align="center"> + <!-- Coverage badge stored in our wiki by the python-coverage-comment-action plugin --> + <a href="https://github.com/garyd203/xraysink/"> + <img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/wiki/garyd203/xraysink/python-coverage-comment-action-badge.json" alt="Coverage"> + </a> +</div> + +Extra AWS X-Ray instrumentation to use distributed tracing with asyncio Python +libraries that are not (yet) supported by the official +[aws_xray_sdk](https://github.com/aws/aws-xray-sdk-python) library. + + +## Integrations Supported +* Generic ASGI-compatible tracing middleware for *any* ASGI-compliant web + framework. This has been tested with: + - [aiohttp server](https://docs.aiohttp.org/en/stable/) + - [FastAPI](https://fastapi.tiangolo.com/) +* asyncio [Task's](https://docs.python.org/3/library/asyncio-task.html) +* Background jobs/tasks + +## Installation +xraysink is distributed as a standard python package through +[pypi](https://pypi.org/), so you can install it with your favourite Python +package manager. For example: + + pip install xraysink + + +## How to use +`xraysink` augments the functionality provided by `aws_xray_sdk`. Before +using the tools in `xraysink`, you first need to configure `aws_xray_sdk` - +this will probably involve calling `xray_recorder.configure()` when your +process starts, and optionally `aws_xray_sdk.core.patch()`. + +Extra instrumentation provided by `xraysink` is described below. + +### FastAPI +Instrument incoming requests in your FastAPI web server by adding the +`xray_middleware` to your app. For example, you could do: + + from starlette.middleware.base import BaseHTTPMiddleware + from xraysink.asgi.middleware import xray_middleware + + # Standard asyncio X-Ray configuration, customise as you choose + xray_recorder.configure(context=AsyncContext(), service="my-cute-little-service") + + # Create a FastAPI app with various middleware + app = FastAPI() + app.add_middleware(MyTracingDependentMiddleware) # Any middleware that is added earlier will have the X-Ray tracing context available to it + app.add_middleware(BaseHTTPMiddleware, dispatch=xray_middleware) + + +### Asyncio Tasks +If you start asyncio [Task's](https://docs.python.org/3/library/asyncio-task.html) +from a standard request handler, then the AWS X-Ray SDK will not correctly +instrument any outgoing requests made inside those Tasks. + +Use the fixed `AsyncContext` from `xraysink` as a drop-in replacement, like so: + + from aws_xray_sdk.core import xray_recorder + from xraysink.context import AsyncContext # NB: Use the AsyncContext from xraysink + + # Use the fixed AsyncContext when configuring X-Ray, + # and customise other configuration as you choose. + xray_recorder.configure(context=AsyncContext(use_task_factory=True)) + + +### Background Jobs/Tasks +If your process starts background tasks that make network calls (eg. to the +database or an API in another service), then each execution of one of those +tasks should be treated as a new X-Ray trace. Indeed, if you don't do so then +you will likely get `context_missing` errors. + +An async function that implements a background task can be easily instrumented +using the `@xray_task_async()` decorator, like so: + + from aws_xray_sdk.core import xray_recorder + from xraysink.tasks import xray_task_async + + # Standard asyncio X-Ray configuration, customise as you choose + xray_recorder.configure(context=AsyncContext(), service="my-cute-little-service") + + # Any call to this function will start a new X-Ray trace + @xray_task_async() + async def cleanup_stale_tokens(): + await database.get_table("tokens").delete(age__gt=1) + + # Start your background task using your scheduling system of choice :) + schedule_recurring_task(cleanup_stale_tokens) + +If your background task functions are called from a function that is already +instrumented (eg. send an email immediately after handling a request), then +the background task will appear as a child segment of that trace. In this case, +you must ensure you use the non-buggy `AsyncContext` when configuring the recorder +(ie. `from xraysink.context import AsyncContext`) + + +### CloudWatch Logs integration +You can link your X-Ray traces to your CloudWatch Logs log records, which +enhances the integration with AWS CloudWatch ServiceLens. Take the following +steps: + +1. Put the X-Ray trace ID into every log message. There is no convention for + how to do this (it just has to appear verbatim in the log message + somewhere), but if you are using structured logging then the convention is + to use a field called `traceId`. Here's an example + + trace_id = xray_recorder.get_trace_entity().trace_id + logging.getLogger("example").info("Hello World!", extra={"traceId": trace_id}) + +1. Explicitly set the name of the CloudWatch Logs log group associated with + your process. There is no general way to detect the Log Group from inside + the process, hence it requires manual configuration as part of your process + initialisation (eg. in the same place where you call + `xray_recorder.configure`). + + set_xray_log_group("/example/service-name") + +Note that this feature relies on undocumented functionality, and is +[not yet](https://github.com/aws/aws-xray-sdk-python/issues/188) +supported by the official Python SDK. + + +## Licence +This project uses the Apache 2.0 licence, to make it compatible with +[aws_xray_sdk](https://github.com/aws/aws-xray-sdk-python), the +primary library for integrating with AWS X-Ray. + + + +%prep +%autosetup -n xraysink-1.6.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-xraysink -f filelist.lst +%dir %{python3_sitelib}/* + +%files help -f doclist.lst +%{_docdir}/* + +%changelog +* Wed May 31 2023 Python_Bot <Python_Bot@openeuler.org> - 1.6.1-1 +- Package Spec generated @@ -0,0 +1 @@ +ca6103358d582a519c699a8c52cfae20 xraysink-1.6.1.tar.gz |