wrapture-instrumentation-aws

Instrumentation for the AWS SDK (boto3 and botocore), applied through wrapture.

wrapture attaches bindings to arbitrary Python call sites without modifying the code being observed, and its config layer can switch on packaged instrumentation for a third-party package by name. This is the AWS package in that collection: one wrapture.Instrumentation class for the AWS SDK, so tracing every call your application makes to S3, DynamoDB, SQS and the rest is one config entry and no code.

Status: beta, ahead of 1.0.0. Developed against wrapture's beta series, with pre-releases published to PyPI, and until 1.0.0 is final a plain pip install wrapture-instrumentation-aws picks up the latest pre-release automatically, so there is no need to pin a specific version.

Why a separate package

The core wrapture-instrumentation package deliberately covers only the standard library and third-party packages that can be exercised in-process, with no separate backend product or service needed to test against. AWS is exactly the kind of product the separate-package rule was drawn for. This package carries its own heavier test dependencies (moto, which reimplements the AWS APIs in memory and pulls in cryptography, PyYAML, Flask and werkzeug) and its own release cadence, so the core package's free-threaded test matrix stays light. It will grow to hold the AWS SDK's async twin (aiobotocore) and a messaging trace-propagation layer.

Installation

$ pip install wrapture-instrumentation-aws

Installing it brings wrapture and nothing else. boto3, botocore and moto are not dependencies: the instrumentation is inert until botocore is present, and wrapture checks the installed version against the range the instrumentation supports at apply time.

Using it

An [[instrument]] entry in wrapture.toml names the target:

[[instrument]]
name = "botocore"

[[sink]]
type = "printer"

and the runner applies it before the application starts, so the patch is in place before boto3 is imported:

$ python -m wrapture -m myapp

The entry point name is botocore, the seam every AWS call passes through: boto3 is sugar over botocore, so a config that traces botocore traces boto3. The same config works through autowrapt injection (AUTOWRAPT_BOOTSTRAP=wrapture python myapp.py); through manual setup, a few lines in the application's own startup where wrapping the launch from outside is awkward; and, in a test, through wrapture.instrumentation("botocore") scoping the instrumentation to a block. The ad-hoc tracing guide covers the config file itself.

To see what is installed, what it supports in the current environment, and what aspects and settings it takes:

$ python -m wrapture.tools instrumentation --verbose

Provided instrumentation

The entry point name is the config's name; the linked per-target README is the full user documentation: what records, what the events carry, its aspect, and what is deliberately not traced.

What is not traced

By design, and where it goes:

• No trace identity is propagated to AWS in this version. A silenced urllib3 beneath the call injects none either, by wrapture's propagation-follows-recording contract, so AWS is never handed headers it would not understand. Trace context into SQS, SNS and Kinesis message attributes, and X-Ray X-Amzn-Trace-Id propagation, are planned for later versions.

• The async SDK (aiobotocore, aioboto3) is a separate top-level package and will get its own Instrumentation class and aiobotocore entry point in this repository, once the sync target is whole.

• s3transfer's multipart uploads fan out to worker threads that do not carry the recording context, so those individual calls may not nest under the caller.

• Bedrock and other LLM telemetry are out of scope.

Adding a target

The AWS SDK's one dispatch seam fronts every service, so a single target covers them all; a future async twin (aiobotocore) would be a second subpackage and entry point here. The subpackage's __init__.py holds one wrapture.Instrumentation subclass and imports only wrapture; everything that touches botocore lives in sibling modules (client.py for the seam, services.py for the per-service table, common.py for the capture policy), imported inside the hook. The class is registered in pyproject.toml under [project.entry-points."wrapture.instrumentation"], and gets its own test suite under tests/<target>/ and a README.md linked from the table above. The instrumentation packages page of the wrapture documentation is the full contract; TESTING.md here covers the tests.

License

BSD 2-Clause. See LICENSE.