@descryy/runtime-adapter-python 0.0.0 → 0.1.0

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 export type { RawPythonFrame } from "./python-frame-parsing.ts";
 export { CHAINED_EXCEPTION_CONNECTIVES, createPythonLineClassifier, isPythonBannerLine, isPythonLocationLine, isPythonTrailerLine, looksLikeContinuation, parsePythonFrame, } from "./python-frame-parsing.ts";
-export { createUvicornLogEnvelope } from "./python-log-envelopes.ts";
+export { createUvicornLogEnvelope, pythonLogPatternRegistry, UVICORN_LOG_PATTERN } from "./python-log-envelopes.ts";
 export { createPythonSourceLocationResolver } from "./python-source-location-resolver.ts";
 export { createPythonStackTraceParser } from "./python-stack-trace-parser.ts";
 export type { PythonRuntimeAdapterOptions } from "./python-runtime-adapter.ts";
 export { createPythonRuntimeAdapter } from "./python-runtime-adapter.ts";
+export { PYTHON_OUTBOUND_HTTP_PRELOAD_DIR, pythonOutboundHttpEnv } from "./outbound-http-instrumentation.ts";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EACL,6BAA6B,EAC7B,0BAA0B,EAC1B,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACnB,qBAAqB,EACrB,gBAAgB,GACjB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,EAAE,kCAAkC,EAAE,MAAM,sCAAsC,CAAC;AAC1F,OAAO,EAAE,4BAA4B,EAAE,MAAM,gCAAgC,CAAC;AAC9E,YAAY,EAAE,2BAA2B,EAAE,MAAM,6BAA6B,CAAC;AAC/E,OAAO,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EACL,6BAA6B,EAC7B,0BAA0B,EAC1B,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACnB,qBAAqB,EACrB,gBAAgB,GACjB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,wBAAwB,EAAE,wBAAwB,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACpH,OAAO,EAAE,kCAAkC,EAAE,MAAM,sCAAsC,CAAC;AAC1F,OAAO,EAAE,4BAA4B,EAAE,MAAM,gCAAgC,CAAC;AAC9E,YAAY,EAAE,2BAA2B,EAAE,MAAM,6BAA6B,CAAC;AAC/E,OAAO,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAC;AACzE,OAAO,EAAE,gCAAgC,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC"}

package/dist/index.js

@@ -1,6 +1,7 @@
 export { CHAINED_EXCEPTION_CONNECTIVES, createPythonLineClassifier, isPythonBannerLine, isPythonLocationLine, isPythonTrailerLine, looksLikeContinuation, parsePythonFrame, } from "./python-frame-parsing.js";
-export { createUvicornLogEnvelope } from "./python-log-envelopes.js";
+export { createUvicornLogEnvelope, pythonLogPatternRegistry, UVICORN_LOG_PATTERN } from "./python-log-envelopes.js";
 export { createPythonSourceLocationResolver } from "./python-source-location-resolver.js";
 export { createPythonStackTraceParser } from "./python-stack-trace-parser.js";
 export { createPythonRuntimeAdapter } from "./python-runtime-adapter.js";
+export { PYTHON_OUTBOUND_HTTP_PRELOAD_DIR, pythonOutboundHttpEnv } from "./outbound-http-instrumentation.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,6BAA6B,EAC7B,0BAA0B,EAC1B,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACnB,qBAAqB,EACrB,gBAAgB,GACjB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,EAAE,kCAAkC,EAAE,MAAM,sCAAsC,CAAC;AAC1F,OAAO,EAAE,4BAA4B,EAAE,MAAM,gCAAgC,CAAC;AAE9E,OAAO,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,6BAA6B,EAC7B,0BAA0B,EAC1B,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACnB,qBAAqB,EACrB,gBAAgB,GACjB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,wBAAwB,EAAE,wBAAwB,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACpH,OAAO,EAAE,kCAAkC,EAAE,MAAM,sCAAsC,CAAC;AAC1F,OAAO,EAAE,4BAA4B,EAAE,MAAM,gCAAgC,CAAC;AAE9E,OAAO,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAC;AACzE,OAAO,EAAE,gCAAgC,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC"}

package/dist/outbound-http-instrumentation.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Where Python's outbound-HTTP instrumentation lives, and how a caller
+ * launches a process with it.
+ *
+ * The artifact itself is Python (`../python-preload/`), so it cannot live in
+ * `src/` and be compiled — it is loaded by CPython, not by tsc. It sits in a
+ * sibling directory of `src/` and `dist/` and is resolved by walking out of
+ * whichever of the two this module is running from, the identical arrangement
+ * `jvm-agent/build.ts` already uses for `Agent.java` and for the identical
+ * reason: an `import.meta.url`-relative path that stays *inside* `src` or
+ * `dist` resolves to a directory that only exists in one of them.
+ *
+ * The hop count is one, not `jvm-agent/build.ts`'s two, because that file
+ * sits a directory deeper than this one. Getting it wrong produces a path
+ * that exists nowhere and a child process that starts perfectly and observes
+ * nothing — measured, not hypothetical, and the reason this module's test
+ * asserts the directory is really on disk rather than only that the two
+ * spellings of the constant agree with each other.
+ *
+ * **Env, not a rewritten command.** CPython has no `--import`, and rewriting
+ * a caller's command string to inject a flag would be this runtime editing
+ * how the application boots. `site` imports a module named `sitecustomize` at
+ * interpreter startup, so prepending this directory to `PYTHONPATH` runs the
+ * instrumentation before the application's own code through a hook CPython
+ * already provides. See `sitecustomize.py` for the one real cost of that
+ * mechanism, stated there rather than discovered later.
+ */
+/** Absolute path to the directory holding `sitecustomize.py` and the instrumentation it installs. Prepend it to `PYTHONPATH`; never import it from Node. */
+export declare const PYTHON_OUTBOUND_HTTP_PRELOAD_DIR: string;
+/**
+ * The environment a Python process must be launched with for its outbound
+ * `httpx` calls to be observed.
+ *
+ * `existingPythonPath` is **prepended to, never replaced**: a target whose own
+ * `PYTHONPATH` matters would otherwise stop finding its own modules, which is
+ * a way of breaking the application in order to watch it.
+ */
+export declare function pythonOutboundHttpEnv(existingPythonPath?: string): {
+    readonly PYTHONPATH: string;
+};
+//# sourceMappingURL=outbound-http-instrumentation.d.ts.map

package/dist/outbound-http-instrumentation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbound-http-instrumentation.d.ts","sourceRoot":"","sources":["../src/outbound-http-instrumentation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAKH,4JAA4J;AAC5J,eAAO,MAAM,gCAAgC,QAA+D,CAAC;AAE7G;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,kBAAkB,CAAC,EAAE,MAAM,GAAG;IAAE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAOlG"}

package/dist/outbound-http-instrumentation.js

@@ -0,0 +1,47 @@
+/**
+ * Where Python's outbound-HTTP instrumentation lives, and how a caller
+ * launches a process with it.
+ *
+ * The artifact itself is Python (`../python-preload/`), so it cannot live in
+ * `src/` and be compiled — it is loaded by CPython, not by tsc. It sits in a
+ * sibling directory of `src/` and `dist/` and is resolved by walking out of
+ * whichever of the two this module is running from, the identical arrangement
+ * `jvm-agent/build.ts` already uses for `Agent.java` and for the identical
+ * reason: an `import.meta.url`-relative path that stays *inside* `src` or
+ * `dist` resolves to a directory that only exists in one of them.
+ *
+ * The hop count is one, not `jvm-agent/build.ts`'s two, because that file
+ * sits a directory deeper than this one. Getting it wrong produces a path
+ * that exists nowhere and a child process that starts perfectly and observes
+ * nothing — measured, not hypothetical, and the reason this module's test
+ * asserts the directory is really on disk rather than only that the two
+ * spellings of the constant agree with each other.
+ *
+ * **Env, not a rewritten command.** CPython has no `--import`, and rewriting
+ * a caller's command string to inject a flag would be this runtime editing
+ * how the application boots. `site` imports a module named `sitecustomize` at
+ * interpreter startup, so prepending this directory to `PYTHONPATH` runs the
+ * instrumentation before the application's own code through a hook CPython
+ * already provides. See `sitecustomize.py` for the one real cost of that
+ * mechanism, stated there rather than discovered later.
+ */
+import { delimiter } from "node:path";
+import { fileURLToPath } from "node:url";
+/** Absolute path to the directory holding `sitecustomize.py` and the instrumentation it installs. Prepend it to `PYTHONPATH`; never import it from Node. */
+export const PYTHON_OUTBOUND_HTTP_PRELOAD_DIR = fileURLToPath(new URL("../python-preload", import.meta.url));
+/**
+ * The environment a Python process must be launched with for its outbound
+ * `httpx` calls to be observed.
+ *
+ * `existingPythonPath` is **prepended to, never replaced**: a target whose own
+ * `PYTHONPATH` matters would otherwise stop finding its own modules, which is
+ * a way of breaking the application in order to watch it.
+ */
+export function pythonOutboundHttpEnv(existingPythonPath) {
+    return {
+        PYTHONPATH: existingPythonPath === undefined || existingPythonPath === ""
+            ? PYTHON_OUTBOUND_HTTP_PRELOAD_DIR
+            : `${PYTHON_OUTBOUND_HTTP_PRELOAD_DIR}${delimiter}${existingPythonPath}`,
+    };
+}
+//# sourceMappingURL=outbound-http-instrumentation.js.map

package/dist/outbound-http-instrumentation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbound-http-instrumentation.js","sourceRoot":"","sources":["../src/outbound-http-instrumentation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,4JAA4J;AAC5J,MAAM,CAAC,MAAM,gCAAgC,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,mBAAmB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAE7G;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CAAC,kBAA2B;IAC/D,OAAO;QACL,UAAU,EACR,kBAAkB,KAAK,SAAS,IAAI,kBAAkB,KAAK,EAAE;YAC3D,CAAC,CAAC,gCAAgC;YAClC,CAAC,CAAC,GAAG,gCAAgC,GAAG,SAAS,GAAG,kBAAkB,EAAE;KAC7E,CAAC;AACJ,CAAC"}

package/dist/python-log-envelopes.d.ts

@@ -71,6 +71,29 @@
  * no idea whether that line began a record, and saying so would be the
  * inference `fields()` exists to refuse.
  */
-import type { LogEnvelope } from "@descryy/runtime-backend-observation";
+import { type LogEnvelope, type LogPattern, type LogPatternRegistry } from "@descryy/runtime-backend-observation";
+/**
+ * uvicorn's wrapper, expressed as a registry entry rather than as a private
+ * constant inside one envelope factory.
+ *
+ * The regexes and the fields are unchanged — this is the same measurement
+ * against the same real `uvicorn 0.41.0` output, moved to where a caller can
+ * name it and compose it with another format. What changed is that
+ * `PythonRuntimeAdapterOptions.server` is no longer the entire Python
+ * vocabulary: a process that prints uvicorn's access lines AND formatted
+ * console output can now be given both, which is what UAT phase 2's Phase 9
+ * asked for and what a closed union of framework names structurally cannot do.
+ */
+export declare const UVICORN_LOG_PATTERN: LogPattern;
+/**
+ * The patterns a Python process can be declared to use: the framework-agnostic
+ * built-ins (the bracket-tag consoles — `rich`, and anything else that prints
+ * `[TAG] message`) plus uvicorn's own.
+ *
+ * A fresh registry per call, so a caller registering its own pattern cannot
+ * change what another caller resolves a name to.
+ */
+export declare function pythonLogPatternRegistry(): LogPatternRegistry;
+/** Unchanged in behaviour and in name: exactly `pythonLogPatternRegistry().envelope(["uvicorn"])`, kept because it is the spelling every existing caller and test uses. */
 export declare function createUvicornLogEnvelope(): LogEnvelope;
 //# sourceMappingURL=python-log-envelopes.d.ts.map

package/dist/python-log-envelopes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"python-log-envelopes.d.ts","sourceRoot":"","sources":["../src/python-log-envelopes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAiC,MAAM,sCAAsC,CAAC;AAqBvG,wBAAgB,wBAAwB,IAAI,WAAW,CAyCtD"}
+{"version":3,"file":"python-log-envelopes.d.ts","sourceRoot":"","sources":["../src/python-log-envelopes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;AAEH,OAAO,EAIL,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,kBAAkB,EACxB,MAAM,sCAAsC,CAAC;AAqB9C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB,EAAE,UA4BjC,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,IAAI,kBAAkB,CAI7D;AAED,2KAA2K;AAC3K,wBAAgB,wBAAwB,IAAI,WAAW,CAEtD"}

package/dist/python-log-envelopes.js

@@ -71,6 +71,7 @@
  * no idea whether that line began a record, and saying so would be the
  * inference `fields()` exists to refuse.
  */
+import { createLogPatternRegistry, createPatternLogEnvelope, } from "@descryy/runtime-backend-observation";
 /**
  * `INFO:     127.0.0.1:39334 - "GET /health HTTP/1.1" 200 OK`
  *
@@ -88,42 +89,61 @@ const UVICORN_HEADER = /^(CRITICAL|ERROR|WARNING|INFO|DEBUG|TRACE): +/;
  * same contract `attrs` has in the IR.
  */
 const ACCESS_MESSAGE = /^(?<client>\S+) - "(?<method>[A-Z]+) (?<path>\S+) (?<protocol>\S+)" (?<status>\d{3})\b/;
+/**
+ * uvicorn's wrapper, expressed as a registry entry rather than as a private
+ * constant inside one envelope factory.
+ *
+ * The regexes and the fields are unchanged — this is the same measurement
+ * against the same real `uvicorn 0.41.0` output, moved to where a caller can
+ * name it and compose it with another format. What changed is that
+ * `PythonRuntimeAdapterOptions.server` is no longer the entire Python
+ * vocabulary: a process that prints uvicorn's access lines AND formatted
+ * console output can now be given both, which is what UAT phase 2's Phase 9
+ * asked for and what a closed union of framework names structurally cannot do.
+ */
+export const UVICORN_LOG_PATTERN = {
+    name: "uvicorn",
+    header: UVICORN_HEADER,
+    headerStartsRecord: true,
+    fields(match) {
+        const access = ACCESS_MESSAGE.exec(match.input.slice(match[0].length));
+        return {
+            // uvicorn's own word, never normalised to a shared vocabulary.
+            level: match[1] ?? null,
+            // uvicorn's formatter discards the logger name — `uvicorn.access`
+            // and `uvicorn.error` are indistinguishable in the printed stream.
+            // Null because it is genuinely absent, not merely unparsed.
+            category: null,
+            // uvicorn has no request-id concept and prints none. Unlike
+            // Kestrel's `Request id "..."`, there is nothing here to read, and
+            // deriving one from the client port would be an invention.
+            requestId: null,
+            attrs: access?.groups === undefined
+                ? {}
+                : {
+                    client: access.groups["client"] ?? "",
+                    method: access.groups["method"] ?? "",
+                    path: access.groups["path"] ?? "",
+                    status: access.groups["status"] ?? "",
+                },
+        };
+    },
+};
+/**
+ * The patterns a Python process can be declared to use: the framework-agnostic
+ * built-ins (the bracket-tag consoles — `rich`, and anything else that prints
+ * `[TAG] message`) plus uvicorn's own.
+ *
+ * A fresh registry per call, so a caller registering its own pattern cannot
+ * change what another caller resolves a name to.
+ */
+export function pythonLogPatternRegistry() {
+    const registry = createLogPatternRegistry();
+    registry.register(UVICORN_LOG_PATTERN);
+    return registry;
+}
+/** Unchanged in behaviour and in name: exactly `pythonLogPatternRegistry().envelope(["uvicorn"])`, kept because it is the spelling every existing caller and test uses. */
 export function createUvicornLogEnvelope() {
-    let fields = null;
-    return {
-        frameworkName: "uvicorn",
-        unwrap(line) {
-            const match = UVICORN_HEADER.exec(line);
-            // Not a header: a traceback line, an application logger's own output,
-            // or anything else. Returned byte-identical, and explicitly NOT
-            // claiming a boundary — an unrecognised line is not evidence of one.
-            if (match === null)
-                return { content: line, startsRecord: false };
-            const content = line.slice(match[0].length);
-            const access = ACCESS_MESSAGE.exec(content);
-            fields = {
-                // uvicorn's own word, never normalised to a shared vocabulary.
-                level: match[1] ?? null,
-                // uvicorn's formatter discards the logger name — `uvicorn.access`
-                // and `uvicorn.error` are indistinguishable in the printed stream.
-                // Null because it is genuinely absent, not merely unparsed.
-                category: null,
-                // uvicorn has no request-id concept and prints none. Unlike
-                // Kestrel's `Request id "..."`, there is nothing here to read, and
-                // deriving one from the client port would be an invention.
-                requestId: null,
-                attrs: access?.groups === undefined
-                    ? {}
-                    : {
-                        client: access.groups["client"] ?? "",
-                        method: access.groups["method"] ?? "",
-                        path: access.groups["path"] ?? "",
-                        status: access.groups["status"] ?? "",
-                    },
-            };
-            return { content, startsRecord: true };
-        },
-        fields: () => fields,
-    };
+    return createPatternLogEnvelope("uvicorn", [UVICORN_LOG_PATTERN]);
 }
 //# sourceMappingURL=python-log-envelopes.js.map

package/dist/python-log-envelopes.js.map

@@ -1 +1 @@
-{"version":3,"file":"python-log-envelopes.js","sourceRoot":"","sources":["../src/python-log-envelopes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;AAIH;;;;;;;;;GASG;AACH,MAAM,cAAc,GAAG,+CAA+C,CAAC;AAEvE;;;;GAIG;AACH,MAAM,cAAc,GAAG,wFAAwF,CAAC;AAEhH,MAAM,UAAU,wBAAwB;IACtC,IAAI,MAAM,GAA0B,IAAI,CAAC;IAEzC,OAAO;QACL,aAAa,EAAE,SAAS;QAExB,MAAM,CAAC,IAAY;YACjB,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACxC,sEAAsE;YACtE,gEAAgE;YAChE,qEAAqE;YACrE,IAAI,KAAK,KAAK,IAAI;gBAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC;YAElE,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;YAC5C,MAAM,MAAM,GAAG,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAC5C,MAAM,GAAG;gBACP,+DAA+D;gBAC/D,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,IAAI,IAAI;gBACvB,kEAAkE;gBAClE,mEAAmE;gBACnE,4DAA4D;gBAC5D,QAAQ,EAAE,IAAI;gBACd,4DAA4D;gBAC5D,mEAAmE;gBACnE,2DAA2D;gBAC3D,SAAS,EAAE,IAAI;gBACf,KAAK,EACH,MAAM,EAAE,MAAM,KAAK,SAAS;oBAC1B,CAAC,CAAC,EAAE;oBACJ,CAAC,CAAC;wBACE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE;wBACrC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE;wBACrC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE;wBACjC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE;qBACtC;aACR,CAAC;YACF,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;QACzC,CAAC;QAED,MAAM,EAAE,GAAG,EAAE,CAAC,MAAM;KACrB,CAAC;AACJ,CAAC"}
+{"version":3,"file":"python-log-envelopes.js","sourceRoot":"","sources":["../src/python-log-envelopes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;AAEH,OAAO,EACL,wBAAwB,EACxB,wBAAwB,GAKzB,MAAM,sCAAsC,CAAC;AAE9C;;;;;;;;;GASG;AACH,MAAM,cAAc,GAAG,+CAA+C,CAAC;AAEvE;;;;GAIG;AACH,MAAM,cAAc,GAAG,wFAAwF,CAAC;AAEhH;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAe;IAC7C,IAAI,EAAE,SAAS;IACf,MAAM,EAAE,cAAc;IACtB,kBAAkB,EAAE,IAAI;IACxB,MAAM,CAAC,KAAsB;QAC3B,MAAM,MAAM,GAAG,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;QACvE,OAAO;YACL,+DAA+D;YAC/D,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,IAAI,IAAI;YACvB,kEAAkE;YAClE,mEAAmE;YACnE,4DAA4D;YAC5D,QAAQ,EAAE,IAAI;YACd,4DAA4D;YAC5D,mEAAmE;YACnE,2DAA2D;YAC3D,SAAS,EAAE,IAAI;YACf,KAAK,EACH,MAAM,EAAE,MAAM,KAAK,SAAS;gBAC1B,CAAC,CAAC,EAAE;gBACJ,CAAC,CAAC;oBACE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE;oBACrC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE;oBACrC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE;oBACjC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE;iBACtC;SACR,CAAC;IACJ,CAAC;CACF,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,UAAU,wBAAwB;IACtC,MAAM,QAAQ,GAAG,wBAAwB,EAAE,CAAC;IAC5C,QAAQ,CAAC,QAAQ,CAAC,mBAAmB,CAAC,CAAC;IACvC,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,2KAA2K;AAC3K,MAAM,UAAU,wBAAwB;IACtC,OAAO,wBAAwB,CAAC,SAAS,EAAE,CAAC,mBAAmB,CAAC,CAAC,CAAC;AACpE,CAAC"}

package/dist/python-runtime-adapter.d.ts

@@ -38,8 +38,31 @@ export interface PythonRuntimeAdapterOptions {
      * default `[%(asctime)s] [%(process)d] [%(levelname)s]` and Django's
      * `runserver` output are different formats and get no envelope until one
      * of them is run and read.
+     *
+     * **Superseded in reach, not in rule, by `logPatterns`.** This option is
+     * exactly `logPatterns: ["uvicorn"]` and is kept because it is the spelling
+     * every existing caller uses. Declaring both is refused rather than merged.
      */
     readonly server?: "uvicorn";
+    /**
+     * Log patterns this process's output is declared to use, by name, from
+     * `pythonLogPatternRegistry()` — composed into one envelope in the order
+     * given, first match per line winning.
+     *
+     * **This is UAT phase 2's Phase 9.** `server` was the entire Python
+     * vocabulary and it named one framework, so a process printing formatted
+     * console output — `[POSTGRES] Creating and opening a Postgres connection
+     * pool`, through `rich.console.Console().print()` — had no envelope that
+     * could see it, and those were the most operationally interesting lines of
+     * the run that found this. `["uvicorn", "bracket-tag-console"]` covers both
+     * halves of exactly that process.
+     *
+     * Still declared, never sniffed, and now for a sharper reason than before:
+     * `bracket-tag-console` and Ruby's `rails-tagged-logging` are the same
+     * regex with opposite record semantics, so no line can be inspected to
+     * decide which applies. An unknown name is refused, not skipped.
+     */
+    readonly logPatterns?: readonly string[];
 }
 export declare function createPythonRuntimeAdapter(options?: PythonRuntimeAdapterOptions): RuntimeAdapter;
 //# sourceMappingURL=python-runtime-adapter.d.ts.map

package/dist/python-runtime-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"python-runtime-adapter.d.ts","sourceRoot":"","sources":["../src/python-runtime-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAuB,MAAM,sCAAsC,CAAC;AAShG,MAAM,WAAW,2BAA2B;IAC1C,qGAAqG;IACrG,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;CAC7B;AAED,wBAAgB,0BAA0B,CAAC,OAAO,GAAE,2BAAgC,GAAG,cAAc,CA4BpG"}
+{"version":3,"file":"python-runtime-adapter.d.ts","sourceRoot":"","sources":["../src/python-runtime-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAA2C,MAAM,sCAAsC,CAAC;AAUpH,MAAM,WAAW,2BAA2B;IAC1C,qGAAqG;IACrG,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;IAC5B;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAED,wBAAgB,0BAA0B,CAAC,OAAO,GAAE,2BAAgC,GAAG,cAAc,CA6DpG"}

package/dist/python-runtime-adapter.js

@@ -21,12 +21,27 @@
  */
 import { createLogCollector } from "@descryy/runtime-backend-observation";
 import { createPythonLineClassifier } from "./python-frame-parsing.js";
-import { createUvicornLogEnvelope } from "./python-log-envelopes.js";
+import { pythonLogPatternRegistry } from "./python-log-envelopes.js";
 import { createPythonSourceLocationResolver } from "./python-source-location-resolver.js";
 import { createPythonStackTraceParser } from "./python-stack-trace-parser.js";
+import { PYTHON_OUTBOUND_HTTP_PRELOAD_DIR } from "./outbound-http-instrumentation.js";
 export function createPythonRuntimeAdapter(options = {}) {
     const sourceLocationResolver = createPythonSourceLocationResolver();
     const stackTraceParser = createPythonStackTraceParser(sourceLocationResolver);
+    if (options.server !== undefined && options.logPatterns !== undefined) {
+        throw new Error("declare either `server` or `logPatterns`, not both -- `server: \"uvicorn\"` IS `logPatterns: [\"uvicorn\"]`, " +
+            "and merging them would silently give a caller an envelope with a pattern they did not ask for.");
+    }
+    const patternNames = options.logPatterns ?? (options.server === undefined ? null : [options.server]);
+    const registry = patternNames === null ? null : pythonLogPatternRegistry();
+    // Names are checked HERE, not inside `createBackendCollectors`. An unknown
+    // pattern name has to fail where the caller declared it: a misspelling that
+    // only threw once a process was already spawned, or -- worse -- that
+    // resolved to no envelope at all, would be silence exactly where this
+    // option exists to remove it. The envelope itself is still built per
+    // collector below, because it is stateful.
+    if (registry !== null && patternNames !== null)
+        registry.envelope(patternNames);
     function createBackendCollectors(sources) {
         return sources.map((source) => createLogCollector({
             source,
@@ -36,17 +51,33 @@ export function createPythonRuntimeAdapter(options = {}) {
             stackTraceParser,
             // One envelope per collector, never shared: it holds the current
             // record's fields, and two processes' output must not attribute
-            // each other's. Its whole contribution here is `startsRecord` —
-            // nothing is stripped from a Python traceback (RT-106).
-            ...(options.server === "uvicorn" ? { envelope: createUvicornLogEnvelope() } : {}),
+            // each other's. For uvicorn its whole contribution is `startsRecord`
+            // — nothing is stripped from a Python traceback (RT-106); for the
+            // console patterns it also strips the tag run.
+            ...(registry === null || patternNames === null ? {} : { envelope: registry.envelope(patternNames) }),
             ...(options.service !== undefined ? { service: options.service } : {}),
         }));
     }
+    /**
+     * CPython has no `--import`. It runs `sitecustomize.py` from anywhere on
+     * `PYTHONPATH` at startup, which is the earliest application-independent
+     * hook available, so the preload directory goes on `PYTHONPATH` --
+     * *prepended*, never replacing: a target whose own `PYTHONPATH` matters
+     * would otherwise stop finding its own modules, which is breaking the
+     * application in order to watch it.
+     */
+    function outboundHttpLaunch() {
+        return {
+            env: { PYTHONPATH: PYTHON_OUTBOUND_HTTP_PRELOAD_DIR },
+            prependToExisting: ["PYTHONPATH"],
+        };
+    }
     return {
         language: "python",
         stackTraceParser,
         sourceLocationResolver,
         createBackendCollectors,
+        outboundHttpLaunch,
     };
 }
 //# sourceMappingURL=python-runtime-adapter.js.map

package/dist/python-runtime-adapter.js.map

@@ -1 +1 @@
-{"version":3,"file":"python-runtime-adapter.js","sourceRoot":"","sources":["../src/python-runtime-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAE1E,OAAO,EAAE,0BAA0B,EAAE,MAAM,2BAA2B,CAAC;AACvE,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,EAAE,kCAAkC,EAAE,MAAM,sCAAsC,CAAC;AAC1F,OAAO,EAAE,4BAA4B,EAAE,MAAM,gCAAgC,CAAC;AAwB9E,MAAM,UAAU,0BAA0B,CAAC,UAAuC,EAAE;IAClF,MAAM,sBAAsB,GAAG,kCAAkC,EAAE,CAAC;IACpE,MAAM,gBAAgB,GAAG,4BAA4B,CAAC,sBAAsB,CAAC,CAAC;IAE9E,SAAS,uBAAuB,CAAC,OAAuC;QACtE,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAC5B,kBAAkB,CAAC;YACjB,MAAM;YACN,oEAAoE;YACpE,8DAA8D;YAC9D,UAAU,EAAE,0BAA0B,EAAE;YACxC,gBAAgB;YAChB,iEAAiE;YACjE,gEAAgE;YAChE,gEAAgE;YAChE,wDAAwD;YACxD,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,wBAAwB,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACjF,GAAG,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACvE,CAAC,CACH,CAAC;IACJ,CAAC;IAED,OAAO;QACL,QAAQ,EAAE,QAAQ;QAClB,gBAAgB;QAChB,sBAAsB;QACtB,uBAAuB;KACxB,CAAC;AACJ,CAAC"}
+{"version":3,"file":"python-runtime-adapter.js","sourceRoot":"","sources":["../src/python-runtime-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAE1E,OAAO,EAAE,0BAA0B,EAAE,MAAM,2BAA2B,CAAC;AACvE,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,EAAE,kCAAkC,EAAE,MAAM,sCAAsC,CAAC;AAC1F,OAAO,EAAE,4BAA4B,EAAE,MAAM,gCAAgC,CAAC;AAC9E,OAAO,EAAE,gCAAgC,EAAE,MAAM,oCAAoC,CAAC;AA+CtF,MAAM,UAAU,0BAA0B,CAAC,UAAuC,EAAE;IAClF,MAAM,sBAAsB,GAAG,kCAAkC,EAAE,CAAC;IACpE,MAAM,gBAAgB,GAAG,4BAA4B,CAAC,sBAAsB,CAAC,CAAC;IAE9E,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,IAAI,OAAO,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QACtE,MAAM,IAAI,KAAK,CACb,+GAA+G;YAC7G,gGAAgG,CACnG,CAAC;IACJ,CAAC;IACD,MAAM,YAAY,GAAG,OAAO,CAAC,WAAW,IAAI,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;IACrG,MAAM,QAAQ,GAAG,YAAY,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,wBAAwB,EAAE,CAAC;IAC3E,2EAA2E;IAC3E,4EAA4E;IAC5E,qEAAqE;IACrE,sEAAsE;IACtE,qEAAqE;IACrE,2CAA2C;IAC3C,IAAI,QAAQ,KAAK,IAAI,IAAI,YAAY,KAAK,IAAI;QAAE,QAAQ,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;IAEhF,SAAS,uBAAuB,CAAC,OAAuC;QACtE,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAC5B,kBAAkB,CAAC;YACjB,MAAM;YACN,oEAAoE;YACpE,8DAA8D;YAC9D,UAAU,EAAE,0BAA0B,EAAE;YACxC,gBAAgB;YAChB,iEAAiE;YACjE,gEAAgE;YAChE,qEAAqE;YACrE,kEAAkE;YAClE,+CAA+C;YAC/C,GAAG,CAAC,QAAQ,KAAK,IAAI,IAAI,YAAY,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC;YACpG,GAAG,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACvE,CAAC,CACH,CAAC;IACJ,CAAC;IAED;;;;;;;OAOG;IACH,SAAS,kBAAkB;QACzB,OAAO;YACL,GAAG,EAAE,EAAE,UAAU,EAAE,gCAAgC,EAAE;YACrD,iBAAiB,EAAE,CAAC,YAAY,CAAC;SAClC,CAAC;IACJ,CAAC;IAED,OAAO;QACL,QAAQ,EAAE,QAAQ;QAClB,gBAAgB;QAChB,sBAAsB;QACtB,uBAAuB;QACvB,kBAAkB;KACnB,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@descryy/runtime-adapter-python",
-  "version": "0.0.0",
+  "version": "0.1.0",
   "type": "module",
-  "description": "Python runtime adapter: CPython traceback parsing, self-contained source locations, the concrete RuntimeAdapter for Python.",
+  "description": "Python runtime adapter: CPython traceback parsing, self-contained source locations, outbound httpx call-site instrumentation, the concrete RuntimeAdapter for Python.",
   "license": "UNLICENSED",
   "engines": {
     "node": ">=22.5"
@@ -14,7 +14,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "python-preload"
   ],
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -24,7 +25,7 @@
     "build": "tsc -b"
   },
   "dependencies": {
-    "@descryy/runtime-contracts": "*",
-    "@descryy/runtime-backend-observation": "*"
+    "@descryy/runtime-contracts": "0.1.0",
+    "@descryy/runtime-backend-observation": "0.1.0"
   }
 }

package/python-preload/descry_outbound_http.py

@@ -0,0 +1,166 @@
+"""Descry's outbound-HTTP instrumentation for CPython — the `httpx` half of
+UAT phase 2 Phase 5's first checkbox, and the counterpart of
+`fetch-instrumentation.ts` for the other runtime.
+
+**Why this exists at all.** Runtime evidence could prove a line touched a
+function and never that a call reached a route, because an edge needs a
+caller and an endpoint named by ONE observation, and an HTTP access-log line
+carries no stack. The fix is not to parse harder; it is to capture the stack
+where it still exists, in the calling process, at the call site. That is what
+this file does for `httpx`, exactly as `fetch-instrumentation.ts` does for
+Node's global `fetch`.
+
+The UAT workspace is the reason `httpx` is first rather than `requests`: its
+own log says `[HTTP] Shared AsyncClient created`.
+
+## Read, never write
+
+`send` is called with the request object it was given, untouched. No header
+is added — in particular no trace header is injected, because injecting one
+would change what leaves the process and would also manufacture the very
+correlation the join is supposed to *observe*. Bodies are never read: the
+request's stream is not touched and the response's `status_code` is available
+off the framing without consuming content.
+
+## One line of structured JSON, same marker as every other collector
+
+`DESCRY_EXTERNAL_REQUEST {json}` on stdout, the exact shape
+`request-marker.ts` declares and `request-line-parser.ts` reads. The protocol
+is language-neutral on purpose: the parser did not need one line changed to
+read these.
+
+## The stack is emitted in CPython's own order, deliberately
+
+`traceback.format_stack()` yields oldest-call-first, the same order a real
+traceback prints, and `createPythonStackTraceParser` reverses it — its own
+doc calls that reversal "the load-bearing line in this file". Emitting
+already-reversed frames here would be corrected a second time and every
+consumer reading `frames[0]` would get the process entry point: a wrong
+answer with the right frames, the right count and no error anywhere. So this
+prints the banner CPython prints and lets the parser that already exists do
+the work.
+
+Frames belonging to this file are dropped **by file, not by count**: the
+primary frame must be the application's call site, and a surviving wrapper
+frame would point every downstream resolution at Descry instead of at the
+code under observation.
+
+## What it does not patch, named rather than silently absent
+
+`requests`, `urllib3`, `aiohttp`, `urllib.request`. Each is a different
+funnel and none of them has been run and measured here; adding one unmeasured
+is the guess this repository's own log-envelope files already refuse. `httpx`
+is patched at `Client.send` / `AsyncClient.send`, which is the single funnel
+every other httpx entry point (`httpx.get`, `client.post`, ...) goes through.
+"""
+
+import json
+import os
+import sys
+import time
+import traceback
+
+_MARKER = "DESCRY_EXTERNAL_REQUEST"
+_SELF = os.path.abspath(__file__)
+_PATCHED = "_descry_outbound_http_patched"
+
+# Directories whose frames are dispatch, not a call site. This file's own is
+# obvious. The instrumented library's is the one that had to be measured:
+# `Client.send` is not what an application calls -- `client.get(...)` goes
+# through `Client.get` and `Client.request` first, so the innermost surviving
+# frame was `httpx/_client.py`, and after the parser's reversal every consumer
+# reading `frames[0]` would have been told the caller is httpx. That is the
+# same failure dropping our own wrapper frame prevents, one library out, and
+# it gets the same treatment for the same reason: these frames exist because
+# of the patch point, not because of what the application did.
+_DISPATCH_DIRS = [os.path.dirname(_SELF)]
+
+
+def _call_site_stack():
+    """The application's own stack, CPython order, without dispatch frames."""
+    frames = [
+        entry
+        for entry in traceback.format_stack()
+        if not any(directory in entry for directory in _DISPATCH_DIRS)
+    ]
+    if not frames:
+        return None
+    return "Traceback (most recent call last):\n" + "".join(frames)
+
+
+def _emit(url, method, headers, status, duration_ms, success, error, stack):
+    payload = {
+        "url": url,
+        "method": method,
+        "requestHeaders": headers,
+        "status": status,
+        "durationMs": duration_ms,
+        "success": success,
+        "error": error,
+        "stack": stack,
+    }
+    # `sys.stdout.write` plus an explicit flush, never `print`: a piped stdout
+    # is block-buffered, and a marker line that arrives only at process exit is
+    # invisible to a live observation window.
+    sys.stdout.write("%s %s\n" % (_MARKER, json.dumps(payload)))
+    sys.stdout.flush()
+
+
+def _describe(request):
+    return str(request.url), request.method, {k.lower(): v for k, v in request.headers.items()}
+
+
+def _install(httpx):
+    if getattr(httpx, _PATCHED, False):
+        return
+    setattr(httpx, _PATCHED, True)
+    _DISPATCH_DIRS.append(os.path.dirname(os.path.abspath(httpx.__file__)))
+
+    original_send = httpx.Client.send
+    original_async_send = httpx.AsyncClient.send
+
+    def send(self, request, **kwargs):
+        url, method, headers = _describe(request)
+        stack = _call_site_stack()
+        started = time.perf_counter()
+        try:
+            response = original_send(self, request, **kwargs)
+        except BaseException as error:
+            _emit(url, method, headers, None, (time.perf_counter() - started) * 1000.0,
+                  False, "%s: %s" % (type(error).__name__, error), stack)
+            raise
+        _emit(url, method, headers, response.status_code,
+              (time.perf_counter() - started) * 1000.0, True, None, stack)
+        return response
+
+    async def async_send(self, request, **kwargs):
+        url, method, headers = _describe(request)
+        stack = _call_site_stack()
+        started = time.perf_counter()
+        try:
+            response = await original_async_send(self, request, **kwargs)
+        except BaseException as error:
+            _emit(url, method, headers, None, (time.perf_counter() - started) * 1000.0,
+                  False, "%s: %s" % (type(error).__name__, error), stack)
+            raise
+        _emit(url, method, headers, response.status_code,
+              (time.perf_counter() - started) * 1000.0, True, None, stack)
+        return response
+
+    httpx.Client.send = send
+    httpx.AsyncClient.send = async_send
+
+
+def install():
+    """Patch httpx if it is importable. Absent httpx is not an error.
+
+    An application that does not use httpx is not a failure to observe; it is
+    an application with no outbound httpx calls, and raising here would break
+    a process this module is only supposed to watch.
+    """
+    try:
+        import httpx
+    except ImportError:
+        return False
+    _install(httpx)
+    return True

package/python-preload/sitecustomize.py

@@ -0,0 +1,28 @@
+"""The CPython equivalent of `node --import <preload>`.
+
+CPython has no `--import`. `site` imports a module named `sitecustomize` at
+interpreter startup if one is importable, so prepending this directory to
+`PYTHONPATH` runs the instrumentation before the application's own code — the
+same before-the-app-runs guarantee the Node preload gets, through the hook
+CPython actually provides.
+
+**The disclosed cost.** `sitecustomize` is a single global name. If the target
+environment already has its own, this directory being first on `PYTHONPATH`
+shadows it, and that environment's own startup customisation silently stops
+running. That is a real risk of this mechanism rather than of this file, it is
+the mechanism every Python APM agent uses for the same reason, and it is
+stated here rather than discovered later. A caller that knows its target ships
+a `sitecustomize` should not use this.
+
+Failures here are swallowed on purpose and reported on stderr rather than
+raised: a broken observer must not stop the observed process from starting.
+"""
+
+import sys
+
+try:
+    from descry_outbound_http import install
+
+    install()
+except Exception as error:  # noqa: BLE001 - see the module docstring
+    sys.stderr.write("descry: outbound HTTP instrumentation not installed: %r\n" % (error,))