wrapture-instrumentation 1.0.0.dev8__tar.gz → 1.0.0.dev9__tar.gz

{wrapture_instrumentation-1.0.0.dev8 → wrapture_instrumentation-1.0.0.dev9}/CHANGES.md

@@ -228,8 +228,9 @@ In development.
   Supports httpx 0.27 and later, below 1.0.
 
 - Jinja2 (`jinja2`, Jinja2 3.x): every render traced in all its
-  forms, sync, streamed and async, each annotated with the
-  template's own name; the loading pipeline
+  forms, sync, streamed and async, each carrying the template
+  category and annotated with the template's own name; the loading
+  pipeline
   (`Environment._load_template` on every get_template,
   `Environment.compile` inside a cold load) beneath it, behind a
   `loading` switch; every event named by its patched location as
@@ -247,8 +248,8 @@ In development.
   are noted against the request, whether Flask answered 500 or a
   registered handler absorbed a real exception (an `HTTPException`
   is control flow and is not noted); and template rendering records
-  beneath the view that asked for it, named by the spelling the call
-  took (`flask:render_template` or
+  beneath the view that asked for it, carrying the template category,
+  named by the spelling the call took (`flask:render_template` or
   `flask.templating:render_template`), capturing the template name
   while the render context and output stay out of capture. Three
   settings switch the optional layers, all on by default:
@@ -371,3 +372,28 @@ In development.
   records its own. Three settings: `leaf` and `propagate`, both on
   by default, and `redact`. Supports urllib3 1.26 and later, below
   3.
+
+- Django (`django`, Django 4.2+): one instrumentation whose events
+  span three categories. Every request records as one tree through
+  the recording WSGI or ASGI middleware wrapped around the handler's
+  own `__call__` (both transports covered from the shared
+  `BaseHandler` dispatch), carrying method, path, redacted query and
+  status, joining the trace a `traceparent` header carries, and
+  annotated with the matched route pattern (`archive/<int:year>/`,
+  exported as `http.route`) and view name, an unmatched 404 left
+  unannotated. Every view is observed at URL resolution
+  (`ResolverMatch` construction), labelled by its URL pattern name,
+  function, class-based and async views alike, one call event per
+  view. An unhandled exception is noted on the request beside its
+  500 at Django's own catch-all; `Http404` and friends are their
+  statuses, not failures. ORM queries record as database leaves at
+  the `CursorWrapper` seam every backend funnels through, carrying
+  system, operation, database and, for a server database, host and
+  port; commit and rollback record beside them; bound parameters are
+  never recorded and the SQL text only behind the `statement`
+  setting; `leaf` folds an instrumented driver (sqlite3) beneath a
+  query. DTL renders record as template events beneath their views,
+  named templates annotated, contexts never captured; Django's
+  Jinja2 backend composes with the jinja2 target instead. Six
+  settings: `ignore_paths`, `redact`, `queries`, `statement`, `leaf`
+  and `templates`. Supports Django 4.2 and later, below 7.

{wrapture_instrumentation-1.0.0.dev8/src/wrapture_instrumentation.egg-info → wrapture_instrumentation-1.0.0.dev9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wrapture-instrumentation
-Version: 1.0.0.dev8
+Version: 1.0.0.dev9
 Summary: Instrumentation for common Python packages, applied through wrapture.
 Author-email: Graham Dumpleton <Graham.Dumpleton@gmail.com>
 License-Expression: BSD-2-Clause
@@ -29,14 +29,16 @@ 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
 project is the collection of that packaged instrumentation: one
-`wrapture.Instrumentation` class per target package (Flask first,
-more to follow), each registered under the bare target name, so that
-tracing a framework is one config entry and no code.
+`wrapture.Instrumentation` class per target package, each registered
+under the bare target name, so that tracing a framework is one config
+entry and no code.
 
 > **Status: pre-alpha.** The package is being built target by target
 > against wrapture's alpha series, with development releases published
-> to [PyPI](https://pypi.org/project/wrapture-instrumentation/). Flask
-> is the first target and covers its basics; see the table below.
+> to [PyPI](https://pypi.org/project/wrapture-instrumentation/). The
+> table below lists what is covered so far, from web frameworks and
+> the servers that carry them to HTTP clients, databases and template
+> engines.
 
 ## Installation
 
@@ -70,8 +72,12 @@ $ python -m wrapture -m myapp
 
 The same config works through
 [autowrapt](https://github.com/GrahamDumpleton/autowrapt) injection
-(`AUTOWRAPT_BOOTSTRAP=wrapture python myapp.py`) and, in a test,
-through `wrapture.instrumentation("flask")` scoping the
+(`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 applying the config
+where wrapping the launch from outside is awkward (an embedded
+interpreter, gunicorn and other multi-process managers); and, in a
+test, through `wrapture.instrumentation("flask")` 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.
@@ -96,6 +102,7 @@ $ python -m wrapture.tools instrumentation --toml
 | ------ | ------------------ | ------- | -------- |
 | [`aiohttp.client`](https://github.com/GrahamDumpleton/wrapture-instrumentation/blob/develop/src/wrapture_instrumentation/external/aiohttp_client/README.md) | aiohttp 3.10+ (3.x) | Every outbound request through a `ClientSession` (the verb helpers, `session.request`, a streamed `async with`) as one external leaf on `_request` carrying method, URL, host, port, path, query and status (an error status is a status, not an exception); a followed redirect one event resolved inside it; the trace identity propagated hop by hop; the query and any URL credentials masked, the body never recorded. | `leaf`, `propagate`, `redact` |
 | [`aiohttp.web`](https://github.com/GrahamDumpleton/wrapture-instrumentation/blob/develop/src/wrapture_instrumentation/server/aiohttp_web/README.md) | aiohttp 3.10+ (3.x) | Every request an aiohttp server handles as one `server`-categorised request boundary carrying method, path, scheme, peer and redacted query, annotated with the matched route pattern (a sub-application's prefix folded in, exported as `http.route`) and status (an `HTTPException` is its status, not a failure), joining the trace a `traceparent` header carries; every registered handler function observed as its route is built and recorded beneath the boundary, labelled by the route's name. | `ignore_paths`, `join`, `redact` |
+| [`django`](https://github.com/GrahamDumpleton/wrapture-instrumentation/blob/develop/src/wrapture_instrumentation/framework/django/README.md) | Django 4.2+ (below 7.0) | Every request as one tree through the recording WSGI or ASGI middleware on the handler's own `__call__`, annotated with the matched route pattern and view name (the pattern exported as `http.route`); every view observed at URL resolution and labelled by its URL name, function, class-based and async views alike; ORM queries and transaction ends as database leaves at the cursor seam carrying system, operation and database, bound parameters never recorded and the SQL text only behind a setting; DTL renders as template events beneath their views, contexts never captured; unhandled failures noted on the request beside the 500 (an `Http404` is its status, not a failure). | `ignore_paths`, `redact`, `queries`, `statement`, `leaf`, `templates` |
 | [`fastapi`](https://github.com/GrahamDumpleton/wrapture-instrumentation/blob/develop/src/wrapture_instrumentation/framework/fastapi/README.md) | fastapi 0.110+ (below 1.0) | Every request as one tree through the recording ASGI middleware on the application's own `__call__`, annotated with the matched route pattern (router prefixes folded in) and name, the pattern exported as `http.route`; every endpoint function observed as its `APIRoute` is built, labelled by the route's name, dependency injection and response models undisturbed; validation failures record as their 422, unhandled failures on the request event beside the 500. | `ignore_paths`, `redact` |
 | [`flask`](https://github.com/GrahamDumpleton/wrapture-instrumentation/blob/develop/src/wrapture_instrumentation/framework/flask/README.md) | Flask 3.x | Every request as one tree, annotated with route and endpoint; every view observed and labelled by endpoint; template renders beneath their views; handled and unhandled failures noted on the request. | `ignore_paths`, `redact`, `lifecycle`, `handled_errors`, `templates` |
 | [`grpc`](https://github.com/GrahamDumpleton/wrapture-instrumentation/blob/develop/src/wrapture_instrumentation/rpc/grpc/README.md) | grpcio 1.76+ (1.x) | Every RPC a channel makes, all four call shapes, as one external leaf through an injected client interceptor, carrying the rpc system, service and method, host, port and status code (an error code is a status, not an exception; a streamed response records the call, its consumption deliberately not tracked); every RPC a server handles as one `server` boundary through an injected server interceptor spanning the handler's run (a streaming handler's whole body), joining the trace the metadata carries; an abort is its code with the boundary clean, an escaped exception the failure it is; payloads and metadata never recorded. | `client`, `server`, `propagate`, `join` |
@@ -121,6 +128,15 @@ settings, and what is deliberately not traced. Settings, further
 choke points and wider version ranges are being added target by
 target.
 
+This 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.
+Instrumentation for targets that do need one (a real PostgreSQL,
+MySQL or Redis to speak to, and their driver packages) will be
+provided as separate self-contained packages, one per
+product/service, each carrying its own test arrangements and release
+cadence. No such packages exist yet; they are coming.
+
 ## Adding a target
 
 Each target lives under `src/wrapture_instrumentation/` in a role
@@ -177,4 +193,5 @@ here covers the tests.
 
 ## License
 
-BSD-2-Clause, as wrapture.
+BSD 2-Clause. See
+[LICENSE](https://github.com/GrahamDumpleton/wrapture-instrumentation/blob/develop/LICENSE).

{wrapture_instrumentation-1.0.0.dev8 → wrapture_instrumentation-1.0.0.dev9}/README.md

@@ -7,14 +7,16 @@ 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
 project is the collection of that packaged instrumentation: one
-`wrapture.Instrumentation` class per target package (Flask first,
-more to follow), each registered under the bare target name, so that
-tracing a framework is one config entry and no code.
+`wrapture.Instrumentation` class per target package, each registered
+under the bare target name, so that tracing a framework is one config
+entry and no code.
 
 > **Status: pre-alpha.** The package is being built target by target
 > against wrapture's alpha series, with development releases published
-> to [PyPI](https://pypi.org/project/wrapture-instrumentation/). Flask
-> is the first target and covers its basics; see the table below.
+> to [PyPI](https://pypi.org/project/wrapture-instrumentation/). The
+> table below lists what is covered so far, from web frameworks and
+> the servers that carry them to HTTP clients, databases and template
+> engines.
 
 ## Installation
 
@@ -48,8 +50,12 @@ $ python -m wrapture -m myapp
 
 The same config works through
 [autowrapt](https://github.com/GrahamDumpleton/autowrapt) injection
-(`AUTOWRAPT_BOOTSTRAP=wrapture python myapp.py`) and, in a test,
-through `wrapture.instrumentation("flask")` scoping the
+(`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 applying the config
+where wrapping the launch from outside is awkward (an embedded
+interpreter, gunicorn and other multi-process managers); and, in a
+test, through `wrapture.instrumentation("flask")` 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.
@@ -74,6 +80,7 @@ $ python -m wrapture.tools instrumentation --toml
 | ------ | ------------------ | ------- | -------- |
 | [`aiohttp.client`](https://github.com/GrahamDumpleton/wrapture-instrumentation/blob/develop/src/wrapture_instrumentation/external/aiohttp_client/README.md) | aiohttp 3.10+ (3.x) | Every outbound request through a `ClientSession` (the verb helpers, `session.request`, a streamed `async with`) as one external leaf on `_request` carrying method, URL, host, port, path, query and status (an error status is a status, not an exception); a followed redirect one event resolved inside it; the trace identity propagated hop by hop; the query and any URL credentials masked, the body never recorded. | `leaf`, `propagate`, `redact` |
 | [`aiohttp.web`](https://github.com/GrahamDumpleton/wrapture-instrumentation/blob/develop/src/wrapture_instrumentation/server/aiohttp_web/README.md) | aiohttp 3.10+ (3.x) | Every request an aiohttp server handles as one `server`-categorised request boundary carrying method, path, scheme, peer and redacted query, annotated with the matched route pattern (a sub-application's prefix folded in, exported as `http.route`) and status (an `HTTPException` is its status, not a failure), joining the trace a `traceparent` header carries; every registered handler function observed as its route is built and recorded beneath the boundary, labelled by the route's name. | `ignore_paths`, `join`, `redact` |
+| [`django`](https://github.com/GrahamDumpleton/wrapture-instrumentation/blob/develop/src/wrapture_instrumentation/framework/django/README.md) | Django 4.2+ (below 7.0) | Every request as one tree through the recording WSGI or ASGI middleware on the handler's own `__call__`, annotated with the matched route pattern and view name (the pattern exported as `http.route`); every view observed at URL resolution and labelled by its URL name, function, class-based and async views alike; ORM queries and transaction ends as database leaves at the cursor seam carrying system, operation and database, bound parameters never recorded and the SQL text only behind a setting; DTL renders as template events beneath their views, contexts never captured; unhandled failures noted on the request beside the 500 (an `Http404` is its status, not a failure). | `ignore_paths`, `redact`, `queries`, `statement`, `leaf`, `templates` |
 | [`fastapi`](https://github.com/GrahamDumpleton/wrapture-instrumentation/blob/develop/src/wrapture_instrumentation/framework/fastapi/README.md) | fastapi 0.110+ (below 1.0) | Every request as one tree through the recording ASGI middleware on the application's own `__call__`, annotated with the matched route pattern (router prefixes folded in) and name, the pattern exported as `http.route`; every endpoint function observed as its `APIRoute` is built, labelled by the route's name, dependency injection and response models undisturbed; validation failures record as their 422, unhandled failures on the request event beside the 500. | `ignore_paths`, `redact` |
 | [`flask`](https://github.com/GrahamDumpleton/wrapture-instrumentation/blob/develop/src/wrapture_instrumentation/framework/flask/README.md) | Flask 3.x | Every request as one tree, annotated with route and endpoint; every view observed and labelled by endpoint; template renders beneath their views; handled and unhandled failures noted on the request. | `ignore_paths`, `redact`, `lifecycle`, `handled_errors`, `templates` |
 | [`grpc`](https://github.com/GrahamDumpleton/wrapture-instrumentation/blob/develop/src/wrapture_instrumentation/rpc/grpc/README.md) | grpcio 1.76+ (1.x) | Every RPC a channel makes, all four call shapes, as one external leaf through an injected client interceptor, carrying the rpc system, service and method, host, port and status code (an error code is a status, not an exception; a streamed response records the call, its consumption deliberately not tracked); every RPC a server handles as one `server` boundary through an injected server interceptor spanning the handler's run (a streaming handler's whole body), joining the trace the metadata carries; an abort is its code with the boundary clean, an escaped exception the failure it is; payloads and metadata never recorded. | `client`, `server`, `propagate`, `join` |
@@ -99,6 +106,15 @@ settings, and what is deliberately not traced. Settings, further
 choke points and wider version ranges are being added target by
 target.
 
+This 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.
+Instrumentation for targets that do need one (a real PostgreSQL,
+MySQL or Redis to speak to, and their driver packages) will be
+provided as separate self-contained packages, one per
+product/service, each carrying its own test arrangements and release
+cadence. No such packages exist yet; they are coming.
+
 ## Adding a target
 
 Each target lives under `src/wrapture_instrumentation/` in a role
@@ -155,4 +171,5 @@ here covers the tests.
 
 ## License
 
-BSD-2-Clause, as wrapture.
+BSD 2-Clause. See
+[LICENSE](https://github.com/GrahamDumpleton/wrapture-instrumentation/blob/develop/LICENSE).

wrapture_instrumentation-1.0.0.dev9/demo/framework_django.py

@@ -0,0 +1,188 @@
+"""Drive a Django application with the django and sqlite3
+instrumentations applied together.
+
+The instrumentations are resolved by their entry point names, the way
+a config file finds them, and the application is the tests' own shop
+app, configured and imported only after the instrumentations apply,
+the order the runner guarantees in real use. Applying both is the
+point: with the django target's `leaf` on (the default) each ORM
+query is a terminal node and the sqlite3 driver's events fold into
+it, one database event per query.
+
+The requests go through the real handlers, a WSGIHandler driven by
+the tests' WSGI driver and then an ASGIHandler driven by the ASGI
+one, covering every view shape: plain views, a route with an int
+converter, a class-based view, an async view, views that query and
+populate the database inside atomic(), a DTL render, a streaming
+response, an Http404 (its status, no failure), a 404 that matched no
+route, and a view that raises (Django answers 500 and the exception
+is noted against the request event).
+
+Two views of the run always print: the live stream, one line as each
+operation begins and a closing line with its outcome, and the tidy
+tree reconstructed afterwards 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), for verifying the spans in a backend such as Jaeger:
+
+    docker run --rm -p 16686:16686 -p 4318:4318 jaegertracing/all-in-one
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+import wrapture
+
+WSGI_REQUESTS: tuple[tuple[str, str, str], ...] = (
+    ("GET", "/", ""),
+    ("GET", "/quote/widget/", "token=hunter2&item=widget"),
+    ("GET", "/archive/1999/", ""),
+    ("GET", "/catalog/", ""),
+    ("GET", "/restock/", ""),
+    ("GET", "/stocked/", ""),
+    ("GET", "/pricelist/", "person=pat"),
+    ("GET", "/export/", ""),
+    ("GET", "/missing/", ""),
+    ("GET", "/nowhere", ""),
+    ("GET", "/quote/missing/", ""),
+)
+
+ASGI_REQUESTS: tuple[tuple[str, str, str], ...] = (
+    ("GET", "/motd/", ""),
+    ("GET", "/", ""),
+)
+
+
+def add_otel_sink() -> None:
+    """Register the OpenTelemetry sink, exporting the run's events as
+    spans; 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-django --otel`, which overlays"
+            " wrapture[otel] for the run"
+        ) from error
+
+    wrapture.add_sink(wrapture.otel.sink(service_name="wrapture-django-demo"))
+
+
+def configure_django() -> None:
+    """Configure the minimum settings the shop app needs and set
+    Django up, the demo's stand-in for a project's settings module."""
+
+    from pathlib import Path
+
+    import django
+    from django.conf import settings
+
+    import tests.framework.django
+
+    settings.configure(
+        DEBUG=False,
+        SECRET_KEY="demo-only",
+        DATABASES={
+            "default": {
+                "ENGINE": "django.db.backends.sqlite3",
+                "NAME": ":memory:",
+            }
+        },
+        ROOT_URLCONF="tests.framework.django.shop.urls",
+        INSTALLED_APPS=["tests.framework.django.shop"],
+        TEMPLATES=[
+            {
+                "BACKEND": "django.template.backends.django.DjangoTemplates",
+                "DIRS": [
+                    str(Path(tests.framework.django.__file__).parent / "templates")
+                ],
+                "APP_DIRS": False,
+                "OPTIONS": {},
+            }
+        ],
+        ALLOWED_HOSTS=["*"],
+        USE_TZ=True,
+    )
+    django.setup()
+
+
+def main(arguments: list[str] | None = None) -> None:
+    """Run the demo: apply the instrumentations, drive the requests
+    through both handlers, print the live stream and the tree, and
+    flush any exporters."""
+
+    parser = argparse.ArgumentParser(
+        prog="demo.framework_django",
+        description="Drive a Django application with the django and"
+        " sqlite3 instrumentations 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)
+
+    # The exporting sink registers first, mirroring the config loader,
+    # which always puts the [otel] table's sink ahead of the [[sink]]
+    # list; the printer writes to stdout so the stream and the demo's
+    # own headings interleave in order.
+
+    if options.otel:
+        add_otel_sink()
+
+    wrapture.add_sink(wrapture.Printer(stream=sys.stdout))
+
+    print("== live stream ==")
+
+    with wrapture.instrumentation("django", "sqlite3"), wrapture.timeline() as tape:
+        configure_django()
+
+        from django.db import connection
+
+        from tests import asgi, wsgi
+        from tests.framework.django.shop import make_asgi_app, make_wsgi_app
+        from tests.framework.django.shop.models import Item
+
+        # The model's table, created without migrations; the schema
+        # editor's statements record like any other, an honest look
+        # at what setup costs.
+
+        with connection.schema_editor() as editor:
+            editor.create_model(Item)
+
+        app = make_wsgi_app()
+        for method, path, query in WSGI_REQUESTS:
+            wsgi.request(app, method, path, query=query)
+
+        aapp = make_asgi_app()
+        for method, path, query in ASGI_REQUESTS:
+            asgi.request(aapp, method, path, query=query)
+
+    print()
+    print("== tree ==")
+    print(tape.tree(times=True))
+
+    # Deliver everything owed: batched spans push to the exporter here
+    # rather than at interpreter exit, so the closing hint below is
+    # true by the time it prints.
+
+    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-django-demo")
+
+
+if __name__ == "__main__":
+    main()

{wrapture_instrumentation-1.0.0.dev8 → wrapture_instrumentation-1.0.0.dev9}/pyproject.toml

@@ -41,6 +41,7 @@ Documentation = "https://wrapture.readthedocs.io"
 [project.entry-points."wrapture.instrumentation"]
 "aiohttp.client" = "wrapture_instrumentation.external.aiohttp_client:AiohttpClientInstrumentation"
 "aiohttp.web" = "wrapture_instrumentation.server.aiohttp_web:AiohttpWebInstrumentation"
+django = "wrapture_instrumentation.framework.django:DjangoInstrumentation"
 fastapi = "wrapture_instrumentation.framework.fastapi:FastAPIInstrumentation"
 flask = "wrapture_instrumentation.framework.flask:FlaskInstrumentation"
 grpc = "wrapture_instrumentation.rpc.grpc:GRPCInstrumentation"
@@ -85,6 +86,7 @@ test = [
     # without, and the sqlalchemy suite skips itself where the
     # import fails.
     "aiosqlite; python_version != '3.13'",
+    "django",
     "fastapi",
     "flask",
     "httpx",
@@ -122,10 +124,20 @@ files = ["src/wrapture_instrumentation", "tests", "demo"]
 module = ["grpc", "grpc.*"]
 ignore_missing_imports = true
 
+# Django ships no inline types either (django-stubs is a separate
+# project); the patch modules import it lazily so most of it is Any
+# already, and the test app's model and class-based view necessarily
+# subclass its (Any-typed) bases.
+[[tool.mypy.overrides]]
+module = ["django", "django.*"]
+ignore_missing_imports = true
+
 [[tool.mypy.overrides]]
 module = [
     "wrapture_instrumentation.rpc.grpc.interceptors",
     "tests.rpc.grpc.service",
+    "tests.framework.django.shop.models",
+    "tests.framework.django.shop.views",
 ]
 disallow_subclassing_any = false
 

{wrapture_instrumentation-1.0.0.dev8 → wrapture_instrumentation-1.0.0.dev9}/src/wrapture_instrumentation/__init__.py

@@ -22,5 +22,5 @@ def _format_version(parts: tuple[str, ...]) -> str:
     )
 
 
-__version_info__ = ("1", "0", "0", "dev8")
+__version_info__ = ("1", "0", "0", "dev9")
 __version__ = _format_version(__version_info__)

wrapture_instrumentation-1.0.0.dev9/src/wrapture_instrumentation/framework/django/README.md

@@ -0,0 +1,137 @@
+# django instrumentation
+
+Request, database and template tracing for
+[Django](https://www.djangoproject.com/). Entry point name `django`,
+the package it patches; supports Django 4.2 and later, below 7.0;
+fully removable. One instrumentation whose events span three
+categories: requests from the handler boundary, database events from
+the ORM's cursor seam, template events from DTL rendering.
+
+## Enabling it
+
+An `[[instrument]]` entry in `wrapture.toml` (with at least one sink
+to hear the events):
+
+```toml
+[[instrument]]
+name = "django"
+
+[[sink]]
+type = "printer"
+```
+
+run under wrapture's runner or through autowrapt injection, so the
+patches are in place before Django imports; in a test, the context
+manager `wrapture.instrumentation("django")` scopes it to a block.
+
+## What you see
+
+One `request` event per request, WSGI and ASGI alike, with the
+matched route on it, the view beneath it, and the view's queries and
+template renders beneath that:
+
+```
+GET /quote/widget/ (django.core.handlers.wsgi:WSGIHandler.__call__)  -> '200 OK'
+  quoted(...)  -> <HttpResponse ...>
+    CursorWrapper.execute(...)  -> ...
+    Template.render(...)  -> '<27 chars>'
+```
+
+- The request boundary is wrapture's recording WSGI or ASGI
+  middleware, installed by decorating the handler's own `__call__`,
+  the callable a server actually invokes. Each event carries the
+  method, path, query (with the built-in sensitive names masked),
+  scheme and peer, and the status line as its result. A request
+  carrying a `traceparent` header joins the caller's trace.
+
+- Once dispatch has resolved the URL, the request event is annotated
+  with the route pattern (`archive/<int:year>/`) and the view name
+  from `resolver_match`, the low-cardinality grouping key the raw
+  path is not; wrapture's OpenTelemetry export reads the pattern as
+  `http.route` and names the span by it. A request that matched no
+  route (a 404) records with its raw path and no route keys. A view
+  that raised still gets its route keys.
+
+- Every view is observed as URL resolution constructs its
+  `ResolverMatch`, labelled by the URL pattern's name when it has
+  one, so it records as a call beneath its request under the name
+  Django knows it by; an unnamed pattern's view keeps its
+  module-qualified path as its identity. A class-based view records
+  as one event for the whole view (its `dispatch` and HTTP-method
+  methods run inside it), and an async view is still awaited: the
+  observed proxy reads as a coroutine function to Django's own
+  checks. The view's captured request argument reduces to its type
+  (its repr carries the raw query string); URL-derived arguments
+  pass. Two deliberate gaps: `resolve("/x/").func` compares equal
+  to the view but is not the same object under instrumentation, and
+  the 404/500 error-handler views resolve outside `ResolverMatch`
+  and are not observed.
+
+- An unhandled exception is noted against the request event at
+  Django's own catch-all, so the request shows the failure beside
+  the 500 it answered; the failing view's own event carries the
+  exception directly. `Http404`, `PermissionDenied` and
+  `SuspiciousOperation` are control flow that carry a status
+  (404/403/400) and are never noted.
+
+- Every ORM query, and raw SQL through a Django cursor, records as a
+  `database` event at the `CursorWrapper` seam every backend funnels
+  through (`DEBUG = True`'s debug cursor included), carrying
+  `system` (the connection's vendor: `sqlite`, `postgresql`,
+  `mysql`, `oracle`), `operation` (the SQL's leading keyword),
+  `database` and, for a server database, `host` and `port`. Commit
+  and rollback record the same way at the connection, showing the
+  real transaction boundaries `atomic()` creates; under plain
+  autocommit most statements never hit them. Bound parameters are
+  never recorded; the SQL text (with placeholders, not values) only
+  when the `statement` setting is on.
+
+- Every DTL render records as a `template`-categorised event beneath
+  the view that asked for it, annotated with the template's name,
+  the render context masked wholesale and the output reduced to its
+  size. Included and extended templates nest beneath the render that
+  pulled them in.
+
+## Composition
+
+- Under an instrumented server (the `uvicorn` target, or any
+  recording middleware a server interposed), a request still records
+  as one tree: the outer middleware records and marks the scope, the
+  handler's own passes through, and the route annotation lands on
+  the one boundary.
+
+- With the `sqlite3` target also applied and `leaf` on (the
+  default), each Django query is a terminal node and the driver's
+  own events beneath it are folded in, so a query records once; with
+  `leaf` off they nest beneath it instead. A future per-backend
+  driver package composes the same way.
+
+- Django's Jinja2 template backend delegates to real Jinja2, so
+  those renders are the `jinja2` target's to record; this
+  instrumentation covers only DTL templates and the two never double
+  up.
+
+## Settings
+
+| Setting | Default | Controls |
+| ------- | ------- | -------- |
+| `ignore_paths` | `[]` | Request paths not to record, as path globs (`'/health'`, `'/static/*'`). An ignored request records nothing at all, its view, queries and template renders included. |
+| `redact` | `[]` | Query string parameters to mask by name, on top of the built-in sensitive set (passwords, tokens, keys and session ids are always masked). The parameter still reaches the application; only the recording is masked. |
+| `queries` | `true` | Record ORM statements and transaction ends as database events. |
+| `statement` | `false` | Record the SQL text on each query event, as compiled with placeholders; bound parameters are never recorded regardless. |
+| `leaf` | `true` | Record each query as a terminal node, folding an instrumented driver beneath it. |
+| `templates` | `true` | Observe DTL template rendering beneath the view that asked for it. |
+
+```toml
+[[instrument]]
+name = "django"
+ignore_paths = ["/health"]
+statement = true
+```
+
+## How it patches
+
+For the implementation detail see the module docstrings of
+[handlers.py](handlers.py), [dispatch.py](dispatch.py),
+[resolvers.py](resolvers.py), [exceptions.py](exceptions.py),
+[db.py](db.py) and [templates.py](templates.py).