wrapture-instrumentation-aws 1.0.0.dev1__tar.gz

wrapture_instrumentation_aws-1.0.0.dev1/CHANGES.md

@@ -0,0 +1,9 @@
+# Changes
+
+## Version 1.0.0
+
+Initial release of wrapture-instrumentation-aws. Everything is new in
+this version, so rather than listing changes, see the
+[README](README.md) for what the package provides: the table of
+covered targets there links to each target's own notes describing
+what it records and its settings.

wrapture_instrumentation_aws-1.0.0.dev1/LICENSE

@@ -0,0 +1,24 @@
+Copyright (c) 2026, Graham Dumpleton
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

wrapture_instrumentation_aws-1.0.0.dev1/MANIFEST.in

@@ -0,0 +1,7 @@
+# setuptools includes test_*.py files by default but not the helpers
+# they import (conftest.py, the package __init__.py), so the tests
+# directory is taken whole, with the repository's other notes.
+graft tests
+graft demo
+include CHANGES.md TESTING.md
+global-exclude __pycache__ *.py[cod]

wrapture_instrumentation_aws-1.0.0.dev1/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: wrapture-instrumentation-aws
+Version: 1.0.0.dev1
+Summary: Instrumentation for the AWS SDK (boto3 and botocore), applied through wrapture.
+Author-email: Graham Dumpleton <Graham.Dumpleton@gmail.com>
+License-Expression: BSD-2-Clause
+Project-URL: Homepage, https://github.com/GrahamDumpleton/wrapture-instrumentation-aws
+Project-URL: Documentation, https://wrapture.readthedocs.io
+Project-URL: Bug Tracker, https://github.com/GrahamDumpleton/wrapture-instrumentation-aws/issues/
+Keywords: wrapture,instrumentation,aws,boto3,botocore,tracing
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: wrapture>=1.0.0a20
+Dynamic: license-file
+
+# wrapture-instrumentation-aws
+
+Instrumentation for the AWS SDK (boto3 and botocore), applied through
+[wrapture](https://github.com/GrahamDumpleton/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: alpha, ahead of 1.0.0.** Developed against wrapture's
+> alpha series, with pre-releases published to
+> [PyPI](https://pypi.org/project/wrapture-instrumentation-aws/), 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](https://github.com/GrahamDumpleton/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
+
+```console
+$ 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:
+
+```toml
+[[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:
+
+```console
+$ 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](https://github.com/GrahamDumpleton/autowrapt) injection
+(`AUTOWRAPT_BOOTSTRAP=wrapture python myapp.py`); through
+[manual setup](https://wrapture.readthedocs.io/en/latest/manual-setup.html),
+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](https://wrapture.readthedocs.io/en/latest/ad-hoc-tracing.html)
+covers the config file itself.
+
+To see what is installed, what it supports in the current
+environment, and what settings it takes:
+
+```console
+$ python -m wrapture.tools instrumentation --verbose
+```
+
+## Provided instrumentation
+
+| Target | Supported versions | Records | Settings |
+| ------ | ------------------ | ------- | -------- |
+| [`botocore`](https://github.com/GrahamDumpleton/wrapture-instrumentation-aws/blob/develop/src/wrapture_instrumentation_aws/botocore/README.md) | botocore 1.34+ (1.x), and boto3 above it | Every AWS API call as one event at the SDK's single dispatch seam, whichever service or client made it, named `service/operation` (`s3/GetObject`) and categorised per service (S3 external, DynamoDB a datastore, SQS/SNS/Kinesis messaging, Lambda and Step Functions tasks); carrying the system, service, operation, region, endpoint host and port, the resource identifiers (bucket and key, table, queue, topic, stream, function), and from the response the status, request id and any retry count; a failing call's `ClientError` recorded as the exception with its status and AWS error code beside it. Retries fold into the one call; a paginator or waiter is one event per underlying call. The parameters reduce to a count and the response to its type: payloads, items and message bodies are never recorded. | `leaf` |
+
+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, the setting, 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](https://wrapture.readthedocs.io/en/latest/instrumentation-packages.html)
+page of the wrapture documentation is the full contract; TESTING.md
+here covers the tests.
+
+## License
+
+BSD 2-Clause. See
+[LICENSE](https://github.com/GrahamDumpleton/wrapture-instrumentation-aws/blob/develop/LICENSE).

wrapture_instrumentation_aws-1.0.0.dev1/README.md

@@ -0,0 +1,136 @@
+# wrapture-instrumentation-aws
+
+Instrumentation for the AWS SDK (boto3 and botocore), applied through
+[wrapture](https://github.com/GrahamDumpleton/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: alpha, ahead of 1.0.0.** Developed against wrapture's
+> alpha series, with pre-releases published to
+> [PyPI](https://pypi.org/project/wrapture-instrumentation-aws/), 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](https://github.com/GrahamDumpleton/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
+
+```console
+$ 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:
+
+```toml
+[[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:
+
+```console
+$ 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](https://github.com/GrahamDumpleton/autowrapt) injection
+(`AUTOWRAPT_BOOTSTRAP=wrapture python myapp.py`); through
+[manual setup](https://wrapture.readthedocs.io/en/latest/manual-setup.html),
+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](https://wrapture.readthedocs.io/en/latest/ad-hoc-tracing.html)
+covers the config file itself.
+
+To see what is installed, what it supports in the current
+environment, and what settings it takes:
+
+```console
+$ python -m wrapture.tools instrumentation --verbose
+```
+
+## Provided instrumentation
+
+| Target | Supported versions | Records | Settings |
+| ------ | ------------------ | ------- | -------- |
+| [`botocore`](https://github.com/GrahamDumpleton/wrapture-instrumentation-aws/blob/develop/src/wrapture_instrumentation_aws/botocore/README.md) | botocore 1.34+ (1.x), and boto3 above it | Every AWS API call as one event at the SDK's single dispatch seam, whichever service or client made it, named `service/operation` (`s3/GetObject`) and categorised per service (S3 external, DynamoDB a datastore, SQS/SNS/Kinesis messaging, Lambda and Step Functions tasks); carrying the system, service, operation, region, endpoint host and port, the resource identifiers (bucket and key, table, queue, topic, stream, function), and from the response the status, request id and any retry count; a failing call's `ClientError` recorded as the exception with its status and AWS error code beside it. Retries fold into the one call; a paginator or waiter is one event per underlying call. The parameters reduce to a count and the response to its type: payloads, items and message bodies are never recorded. | `leaf` |
+
+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, the setting, 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](https://wrapture.readthedocs.io/en/latest/instrumentation-packages.html)
+page of the wrapture documentation is the full contract; TESTING.md
+here covers the tests.
+
+## License
+
+BSD 2-Clause. See
+[LICENSE](https://github.com/GrahamDumpleton/wrapture-instrumentation-aws/blob/develop/LICENSE).

wrapture_instrumentation_aws-1.0.0.dev1/TESTING.md

@@ -0,0 +1,197 @@
+# Testing
+
+## Where the tests are
+
+Tests live in the [tests/](tests/) directory at the top of the
+repository, separate from the package code in
+src/wrapture_instrumentation_aws/. Test files are named `test_*.py`
+and are discovered by pytest, configured via the
+`[tool.pytest.ini_options]` section of [pyproject.toml](pyproject.toml).
+
+The directory has two levels:
+
+- Package-level tests directly under tests/: the version, the rule
+  that importing the package or loading any registered class never
+  imports a target, and the listing tool reporting every entry
+  cleanly.
+
+- One subdirectory per target, `tests/<target>/` (`tests/botocore/`),
+  holding that instrumentation's suite: settings validation, applying
+  and removing the class directly, the whole path through
+  `wrapture.instrumentation()` with a timeline recording what the
+  bindings observe, resolving the entry point by name, a check that
+  the installed botocore satisfies the class's `supports` range, and
+  the composition tests over a real wire.
+
+Shared helpers live in [tests/conftest.py](tests/conftest.py).
+
+## Testing with moto
+
+The suite drives real boto3 clients against
+[moto](https://docs.getmoto.org/), which reimplements the AWS APIs in
+memory. Two modes are used, and the split maps onto what the suite
+needs:
+
+- In-process mode (`moto.mock_aws` as a context manager) registers a
+  `before-send` handler on botocore's event system and answers each
+  request from the in-memory backend, no socket. Everything above
+  `before-send`, `_make_api_call` included, is real botocore
+  executing normally, so the instrumented path is exercised with full
+  fidelity. This is the workhorse: the `aws` fixture opens `mock_aws()`
+  with dummy credentials and a region in the environment, and the
+  tests drive real clients and assert the tape.
+
+- Server mode (`ThreadedMotoServer` from `moto.server`, on a thread,
+  no docker) is a real HTTP server speaking the AWS protocols on
+  localhost, with boto3 pointed at it via `endpoint_url`. It supplies
+  a genuine wire for the composition tests with the core package's
+  urllib3 target, and for asserting what headers the request carried
+  on the wire.
+
+Because the seam sits strictly above moto's in-process interception,
+the tests are faithful; the corollary is that this instrumentation
+must never bind at or below botocore's HTTP send, where in-process
+moto would short-circuit beneath it.
+
+moto needs cryptography, which has no free threaded wheel for 3.13 or
+3.15 yet, so those two builds are left out of the version matrix
+rather than run with nothing installed. The suites also guard their
+imports with `pytest.importorskip`, so a build where moto or the core
+package is absent skips rather than errors.
+
+## Running the tests
+
+All tooling in this project goes through
+[uv](https://docs.astral.sh/uv/), which manages the project
+environment and installs the package, its development dependencies
+(including pytest) and the target packages the tests need.
+
+The simplest way to run the test suite is via the Justfile target:
+
+```console
+just test
+```
+
+Extra arguments are passed through to pytest, for example:
+
+```console
+just test -v
+just test tests/botocore/test_recording.py
+just test -k redirect
+```
+
+One target's suite alone:
+
+```console
+just test-target botocore
+```
+
+Equivalently, run pytest directly with uv:
+
+```console
+uv run pytest
+```
+
+## Watching what the tests record
+
+The suites assert on tapes rather than printing anything, but the
+recorded events can be watched live for visual verification. Setting
+WRAPTURE_PRINTER in the environment installs a process-wide
+wrapture.Printer sink for the session, streaming one line to stderr as
+each operation begins and a closing line with its outcome and timing;
+pytest captures stderr, so add -s to see it:
+
+```console
+WRAPTURE_PRINTER=1 just test tests/botocore -s
+```
+
+For a purpose-built run rather than the tests' traffic, the demo
+module under demo/ applies the instrumentation, drives boto3 against
+moto, and prints both the live stream and the reconstructed tree with
+timings:
+
+```console
+just demo-botocore
+```
+
+With --otel the same events also export as OpenTelemetry spans over
+OTLP (to http://localhost:4318, or wherever
+OTEL_EXPORTER_OTLP_ENDPOINT points), for verifying the spans in a
+local backend such as Jaeger; the Justfile target overlays the
+wrapture[otel] dependencies for the run:
+
+```console
+just demo-botocore --otel
+```
+
+## Testing across Python versions
+
+The project supports Python 3.12 through 3.15, and the free threaded
+build of 3.14. The supported list is defined at the top of the
+[Justfile](Justfile); the free threaded builds of 3.13 and 3.15 are
+excluded until moto's dependency wheels exist for them. The default
+version used by plain `just test` is pinned in
+[.python-version](.python-version).
+
+```console
+just test-all
+just test-python 3.14t
+```
+
+uv downloads any Python version it does not already have, and each
+version gets its own environment (.venv-VERSION) so the default .venv
+is left untouched.
+
+## Testing across target versions
+
+The `test` dependency group installs boto3 (and so botocore) at
+whatever version the lock resolves. The instrumentation's `supports`
+range is kept honest by running the suite against other boto3 lines,
+overlaid on the project environment for that run; boto3 pins botocore
+to its matching minor, so overlaying boto3 is how a botocore line is
+tested. Each line has a place in `boto3_versions` in the Justfile, run
+one at a time by `just test-botocore 1.34.162` or all by
+`just test-botocore-all`, and the CI workflow runs the same matrix. A
+test in the suite asserts the installed botocore satisfies `supports`,
+so a matrix entry outside the range fails loudly rather than passing
+vacuously.
+
+## Testing against unreleased wrapture
+
+The package depends on a released wrapture. To run the tests against a
+checkout of wrapture in the sibling directory ../wrapture, without
+editing pyproject.toml:
+
+```console
+just test-dev
+```
+
+which overlays that checkout as an editable install for the run. This
+is the way to exercise the package against unreleased wrapture
+changes, such as a new resolver capability the seam relies on.
+
+## Writing tests
+
+- Put new test files in tests/ (package level) or tests/<target>/
+  (for one instrumentation) and name them `test_*.py`.
+
+- Import the package under test as `wrapture_instrumentation_aws`, and
+  the instrumentation classes from their subpackages. The project is
+  installed into the uv-managed environment, so no path manipulation
+  is needed.
+
+- Guard the target imports with `pytest.importorskip` at the top of
+  the module (`boto3 = pytest.importorskip("boto3")`), so a build
+  without moto or boto3 skips the suite rather than erroring.
+
+- Validate behaviour with wrapture's own unit testing layer:
+  `wrapture.timeline()` to record what the instrumentation's bindings
+  observe and the tape's tree and queries to assert on it, and
+  `wrapture.instrumentation()` to scope an application of a class to a
+  block, driving real boto3 clients against moto. Do not use
+  `unittest.mock`. If something cannot be expressed that way, write it
+  plainly with a comment naming the gap, and say so when summarising
+  the work.
+
+- Tests should not depend on anything in the scratch/ directory,
+  which is not part of the repository.

wrapture_instrumentation_aws-1.0.0.dev1/demo/botocore.py

@@ -0,0 +1,136 @@
+"""Drive boto3 against moto with the AWS SDK instrumentation applied.
+
+The instrumentation is resolved by its entry point name, and the
+calls go to moto's in-memory backend, so no real AWS and no
+credentials beyond dummy ones are needed. The calls cover the shapes
+that matter: an S3 put and get (external, with a bucket and key), a
+DynamoDB put (a datastore, with a collection), an SQS send (messaging,
+with a destination), a paginated list (one event per page), and a
+failing get (a ClientError recorded with its status and code). Each
+runs beneath an observed function, so the leaves sit in a tree.
+
+Two views of the run always print: the live stream and the tree
+reconstructed with timings. With --otel the same events also export
+as OpenTelemetry spans to a local OTLP endpoint (http://localhost:4318
+unless OTEL_EXPORTER_OTLP_ENDPOINT says otherwise), where each span's
+kind and attributes follow the call's category: an S3 call CLIENT with
+rpc attributes, a DynamoDB call CLIENT with db attributes, an SQS call
+PRODUCER with messaging attributes.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+import wrapture
+
+
+def add_otel_sink() -> None:
+    """Register the OpenTelemetry sink; exits with guidance when the
+    optional dependencies are missing."""
+
+    try:
+        import wrapture.otel
+    except ImportError as error:
+        raise SystemExit(
+            "the OpenTelemetry dependencies are not installed; run the"
+            " demo through `just demo-botocore --otel`, which overlays"
+            " wrapture[otel] for the run"
+        ) from error
+
+    wrapture.add_sink(wrapture.otel.sink(service_name="wrapture-botocore-demo"))
+
+
+def main(arguments: list[str] | None = None) -> None:
+    """Run the demo: apply the instrumentation, make the calls against
+    moto, print the live stream and the tree, and flush any
+    exporters."""
+
+    parser = argparse.ArgumentParser(
+        prog="demo.botocore",
+        description="Drive boto3 against moto with the instrumentation"
+        " applied, printing the live stream and the tree.",
+    )
+    parser.add_argument(
+        "--otel",
+        action="store_true",
+        help="also export the events as OpenTelemetry spans over OTLP",
+    )
+    options = parser.parse_args(arguments)
+
+    os.environ.setdefault("AWS_ACCESS_KEY_ID", "testing")
+    os.environ.setdefault("AWS_SECRET_ACCESS_KEY", "testing")
+    os.environ.setdefault("AWS_SESSION_TOKEN", "testing")
+    os.environ.setdefault("AWS_DEFAULT_REGION", "us-east-1")
+
+    if options.otel:
+        add_otel_sink()
+
+    wrapture.add_sink(wrapture.Printer(stream=sys.stdout))
+
+    print("== live stream ==")
+
+    import boto3
+    from botocore.exceptions import ClientError
+    from moto import mock_aws
+
+    with (
+        mock_aws(),
+        wrapture.instrumentation("botocore"),
+        wrapture.timeline() as tape,
+    ):
+
+        @wrapture.observed
+        def exercise() -> None:
+            s3 = boto3.client("s3")
+            s3.create_bucket(Bucket="reports")
+            s3.put_object(Bucket="reports", Key="q1.csv", Body=b"secret contents")
+            s3.get_object(Bucket="reports", Key="q1.csv")["Body"].read()
+
+            dynamodb = boto3.client("dynamodb")
+            dynamodb.create_table(
+                TableName="orders",
+                KeySchema=[{"AttributeName": "id", "KeyType": "HASH"}],
+                AttributeDefinitions=[{"AttributeName": "id", "AttributeType": "S"}],
+                BillingMode="PAY_PER_REQUEST",
+            )
+            dynamodb.put_item(TableName="orders", Item={"id": {"S": "1"}})
+
+            sqs = boto3.client("sqs")
+            queue = sqs.create_queue(QueueName="jobs")["QueueUrl"]
+            sqs.send_message(QueueUrl=queue, MessageBody="run report")
+
+            for name in ("a", "b"):
+                s3.put_object(Bucket="reports", Key=name, Body=b"x")
+            list(
+                s3.get_paginator("list_objects_v2").paginate(
+                    Bucket="reports", PaginationConfig={"PageSize": 1}
+                )
+            )
+
+            try:
+                s3.get_object(Bucket="reports", Key="missing")
+            except ClientError as error:
+                print(f"expected failure: {error.response['Error']['Code']}")
+
+        exercise()
+
+    print()
+    print("== tree ==")
+    print(tape.tree(times=True))
+
+    wrapture.shutdown()
+
+    if options.otel:
+        endpoint = os.environ.get(
+            "OTEL_EXPORTER_OTLP_ENDPOINT", "http://localhost:4318"
+        )
+        print()
+        print("== otel ==")
+        print(f"spans flushed to {endpoint} as service wrapture-botocore-demo")
+
+
+if __name__ == "__main__":
+    main()