tigrcorn-observability 0.3.16.dev12__tar.gz → 0.3.17.dev1__tar.gz

{tigrcorn_observability-0.3.16.dev12 → tigrcorn_observability-0.3.17.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tigrcorn-observability
-Version: 0.3.16.dev12
+Version: 0.3.17.dev1
 Summary: Logging, metrics, tracing, DoS warning events, and release-evidence metadata for the Tigrcorn Python web server.
 Author-email: Jacob Stewart <jacob@swarmauri.com>
 License: Apache License
@@ -186,8 +186,8 @@ Classifier: Typing :: Typed
 Requires-Python: <3.15,>=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: tigrcorn-core==0.3.16.dev12
-Requires-Dist: tigrcorn-config==0.3.16.dev12
+Requires-Dist: tigrcorn-core==0.3.17.dev1
+Requires-Dist: tigrcorn-config==0.3.17.dev1
 Dynamic: license-file
 
 <div align="center">

{tigrcorn_observability-0.3.16.dev12 → tigrcorn_observability-0.3.17.dev1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tigrcorn-observability"
-version = "0.3.16.dev12"
+version = "0.3.17.dev1"
 description = "Logging, metrics, tracing, DoS warning events, and release-evidence metadata for the Tigrcorn Python web server."
 readme = "README.md"
 requires-python = ">=3.10,<3.15"
@@ -29,8 +29,8 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-  "tigrcorn-core==0.3.16.dev12",
-  "tigrcorn-config==0.3.16.dev12",
+  "tigrcorn-core==0.3.17.dev1",
+  "tigrcorn-config==0.3.17.dev1",
 ]
 
 [tool.setuptools]

tigrcorn_observability-0.3.17.dev1/src/tigrcorn_observability/__init__.py

@@ -0,0 +1,35 @@
+"""Logging, metrics, tracing helpers."""
+
+from tigrcorn_observability.protocol import (
+    ObservabilityRecord,
+    ProtocolLabels,
+    ProtocolObservabilityError,
+    certification_evidence_links,
+    lifecycle_event,
+    make_observability_record,
+    protocol_label_schema,
+    protocol_transport_labels,
+    propagate_otel_context,
+    quic_operational_labels,
+    redact_and_bound_labels,
+    redact_mapping,
+    tls_alpn_labels,
+    validate_label_config,
+)
+
+__all__ = [
+    "ObservabilityRecord",
+    "ProtocolLabels",
+    "ProtocolObservabilityError",
+    "certification_evidence_links",
+    "lifecycle_event",
+    "make_observability_record",
+    "protocol_label_schema",
+    "protocol_transport_labels",
+    "propagate_otel_context",
+    "quic_operational_labels",
+    "redact_and_bound_labels",
+    "redact_mapping",
+    "tls_alpn_labels",
+    "validate_label_config",
+]

{tigrcorn_observability-0.3.16.dev12 → tigrcorn_observability-0.3.17.dev1}/src/tigrcorn_observability/logging.py

@@ -10,6 +10,7 @@ from pathlib import Path
 from typing import Any, Mapping
 
 from tigrcorn_config.files import ConfigFileError, load_config_source
+from tigrcorn_observability.protocol import make_observability_record
 
 
 class LoggingConfigError(RuntimeError):
@@ -164,23 +165,132 @@ class AccessLogger:
         self.logger = logger
         self.enabled = enabled
         self.fmt = fmt or '{peer} "{method} {path} {proto}" {status}'
+        self.observability_records: list[dict[str, Any]] = []
 
     def _peer(self, client: tuple[str, int] | None) -> str:
         return f"{client[0]}:{client[1]}" if client else '-'
 
-    def log_http(self, client: tuple[str, int] | None, method: str, path: str, status: int, proto: str) -> None:
+    def log_http(
+        self,
+        client: tuple[str, int] | None,
+        method: str,
+        path: str,
+        status: int,
+        proto: str,
+        *,
+        request_headers: list[tuple[bytes, bytes]] | tuple[tuple[bytes, bytes], ...] | None = None,
+        tls_version: str | None = None,
+        alpn: str | None = None,
+        transport: str | None = None,
+    ) -> None:
         if not self.enabled:
             return
         peer = self._peer(client)
         message = self.fmt.format(peer=peer, method=method, path=path, status=status, proto=proto)
-        self.logger.info(message, extra={'event': 'access.http', 'peer': peer, 'method': method, 'path': path, 'status': status, 'proto': proto})
+        observability = self._http_observability_record(
+            peer=peer,
+            method=method,
+            path=path,
+            status=status,
+            proto=proto,
+            request_headers=request_headers,
+            tls_version=tls_version,
+            alpn=alpn,
+            transport=transport,
+        )
+        self.observability_records.append(observability)
+        self.logger.info(
+            message,
+            extra={
+                'event': 'access.http',
+                'peer': peer,
+                'method': method,
+                'path': path,
+                'status': status,
+                'proto': proto,
+                'observability': observability,
+            },
+        )
 
     def log_ws(self, client: tuple[str, int] | None, path: str, result: str) -> None:
         if not self.enabled:
             return
         peer = self._peer(client)
         message = f'{peer} "WEBSOCKET {path}" {result}'
-        self.logger.info(message, extra={'event': 'access.websocket', 'peer': peer, 'path': path, 'result': result})
+        observability = make_observability_record(
+            kind='event',
+            name=f'websocket.{result}',
+            labels={
+                'protocol': 'websocket',
+                'transport': 'tcp',
+                'lifecycle': result,
+                'peer': peer,
+                'path': path,
+            },
+            attributes={'result': result},
+        )
+        self.observability_records.append(observability)
+        self.logger.info(
+            message,
+            extra={
+                'event': 'access.websocket',
+                'peer': peer,
+                'path': path,
+                'result': result,
+                'observability': observability,
+            },
+        )
+
+    def _http_observability_record(
+        self,
+        *,
+        peer: str,
+        method: str,
+        path: str,
+        status: int,
+        proto: str,
+        request_headers: list[tuple[bytes, bytes]] | tuple[tuple[bytes, bytes], ...] | None,
+        tls_version: str | None,
+        alpn: str | None,
+        transport: str | None,
+    ) -> dict[str, Any]:
+        protocol = _protocol_from_http_proto(proto)
+        labels: dict[str, Any] = {
+            'protocol': protocol,
+            'transport': transport or ('quic' if protocol == 'http3' else 'tcp'),
+            'peer': peer,
+            'path': path,
+        }
+        if tls_version is not None:
+            labels['tls_version'] = tls_version
+        if alpn is not None:
+            labels['alpn'] = alpn
+        return make_observability_record(
+            kind='event',
+            name='http.request',
+            labels=labels,
+            attributes={
+                'headers': _headers_to_mapping(request_headers or ()),
+                'method': method,
+                'status': int(status),
+            },
+        )
+
+
+def _protocol_from_http_proto(proto: str) -> str:
+    normalized = str(proto).lower()
+    if normalized.endswith('/3'):
+        return 'http3'
+    if normalized.endswith('/2'):
+        return 'http2'
+    return 'http1'
+
+
+def _headers_to_mapping(headers: list[tuple[bytes, bytes]] | tuple[tuple[bytes, bytes], ...]) -> dict[str, str]:
+    result: dict[str, str] = {}
+    for name, value in headers:
+        result[name.decode('latin1').lower()] = value.decode('latin1', 'replace')
+    return result
 
 
 def _coerce_level(level: str) -> int:

tigrcorn_observability-0.3.17.dev1/src/tigrcorn_observability/protocol.py

@@ -0,0 +1,225 @@
+from __future__ import annotations
+
+import hashlib
+import re
+from dataclasses import dataclass, field
+from typing import Any, Mapping
+
+
+class ProtocolObservabilityError(ValueError):
+    """Raised when protocol-aware observability would emit unsafe telemetry."""
+
+
+PROTOCOL_LABEL_SCHEMA: tuple[tuple[str, str], ...] = (
+    ("protocol", "low-cardinality protocol name"),
+    ("transport", "low-cardinality transport domain"),
+    ("tls_version", "safe TLS protocol version"),
+    ("alpn", "safe negotiated ALPN token"),
+    ("profile", "deployment profile"),
+    ("listener_id", "bounded listener identifier"),
+    ("lifecycle", "protocol lifecycle event"),
+)
+
+_ALLOWED_LABELS = {name for name, _description in PROTOCOL_LABEL_SCHEMA} | {
+    "event_kind",
+    "metric",
+    "quic_loss_packets",
+    "quic_migration",
+    "quic_rtt_ms",
+    "span_id",
+    "trace_id",
+}
+_SENSITIVE_PATTERN = re.compile(r"(authorization|certificate|cookie|key|password|private|qlog|secret|token)", re.I)
+_HIGH_CARDINALITY = {"client_ip", "connection_id", "path", "peer", "peer_id", "qlog_connection_id", "session_id"}
+
+
+@dataclass(frozen=True, slots=True)
+class ProtocolLabels:
+    protocol: str
+    transport: str
+    tls_version: str | None = None
+    alpn: str | None = None
+    profile: str | None = None
+    listener_id: str | None = None
+    lifecycle: str | None = None
+
+    def as_dict(self) -> dict[str, str | None]:
+        return {
+            "alpn": self.alpn,
+            "lifecycle": self.lifecycle,
+            "listener_id": self.listener_id,
+            "profile": self.profile,
+            "protocol": self.protocol,
+            "tls_version": self.tls_version,
+            "transport": self.transport,
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class ObservabilityRecord:
+    kind: str
+    name: str
+    labels: dict[str, Any]
+    attributes: dict[str, Any] = field(default_factory=dict)
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "attributes": _stable_mapping(self.attributes),
+            "kind": self.kind,
+            "labels": _stable_mapping(self.labels),
+            "name": self.name,
+            "schema_version": 1,
+        }
+
+
+def protocol_label_schema() -> dict[str, Any]:
+    return {
+        "cardinality": {
+            "bounded": tuple(sorted(_ALLOWED_LABELS)),
+            "hashed": tuple(sorted(_HIGH_CARDINALITY)),
+        },
+        "labels": tuple({"name": name, "description": description} for name, description in PROTOCOL_LABEL_SCHEMA),
+        "redaction": tuple(sorted(("authorization", "certificate", "cookie", "key", "password", "private", "qlog", "secret", "token"))),
+        "schema_version": 1,
+    }
+
+
+def make_observability_record(
+    *,
+    kind: str,
+    name: str,
+    labels: Mapping[str, Any],
+    attributes: Mapping[str, Any] | None = None,
+) -> dict[str, Any]:
+    validated = validate_label_config(labels)
+    return ObservabilityRecord(
+        kind=kind,
+        name=name,
+        labels=redact_and_bound_labels(validated),
+        attributes=redact_mapping(attributes or {}),
+    ).as_dict()
+
+
+def protocol_transport_labels(*, protocol: str, transport: str, profile: str = "default") -> dict[str, Any]:
+    return ProtocolLabels(protocol=protocol, transport=transport, profile=profile).as_dict()
+
+
+def tls_alpn_labels(*, protocol: str, transport: str, tls_version: str, alpn: str) -> dict[str, Any]:
+    return ProtocolLabels(
+        protocol=protocol,
+        transport=transport,
+        tls_version=tls_version,
+        alpn=alpn,
+    ).as_dict()
+
+
+def lifecycle_event(*, protocol: str, transport: str, lifecycle: str, session_id: str | None = None) -> dict[str, Any]:
+    labels = ProtocolLabels(protocol=protocol, transport=transport, lifecycle=lifecycle).as_dict()
+    if session_id is not None:
+        labels["session_id"] = session_id
+    return make_observability_record(kind="event", name=f"{protocol}.{lifecycle}", labels=labels)
+
+
+def propagate_otel_context(context: Mapping[str, str], labels: Mapping[str, Any]) -> dict[str, Any]:
+    trace_id = context.get("traceparent", "").split("-")[1] if context.get("traceparent", "").count("-") >= 3 else None
+    span_id = context.get("traceparent", "").split("-")[2] if context.get("traceparent", "").count("-") >= 3 else None
+    merged = dict(labels)
+    if trace_id:
+        merged["trace_id"] = trace_id
+    if span_id:
+        merged["span_id"] = span_id
+    return make_observability_record(kind="trace", name="otel.context", labels=merged)
+
+
+def quic_operational_labels(*, rtt_ms: float, loss_packets: int, migration: str, qlog_secret: str | None = None) -> dict[str, Any]:
+    labels: dict[str, Any] = {
+        "protocol": "quic",
+        "transport": "quic",
+        "quic_loss_packets": max(0, int(loss_packets)),
+        "quic_migration": migration,
+        "quic_rtt_ms": round(float(rtt_ms), 3),
+    }
+    attributes: dict[str, Any] = {}
+    if qlog_secret is not None:
+        attributes["qlog_secret"] = qlog_secret
+    return make_observability_record(kind="metric", name="quic.operational", labels=labels, attributes=attributes)
+
+
+def redact_mapping(payload: Mapping[str, Any]) -> dict[str, Any]:
+    result: dict[str, Any] = {}
+    for key in sorted(payload):
+        value = payload[key]
+        if _SENSITIVE_PATTERN.search(str(key)):
+            result[key] = "[redacted]"
+        elif isinstance(value, Mapping):
+            result[key] = redact_mapping(value)
+        else:
+            result[key] = value
+    return result
+
+
+def redact_and_bound_labels(labels: Mapping[str, Any]) -> dict[str, Any]:
+    result: dict[str, Any] = {}
+    for key in sorted(labels):
+        value = labels[key]
+        if _SENSITIVE_PATTERN.search(str(key)):
+            result[key] = "[redacted]"
+        elif key in _HIGH_CARDINALITY:
+            result[f"{key}_hash"] = _hash_label(value)
+        else:
+            result[key] = value
+    return result
+
+
+def validate_label_config(labels: Mapping[str, Any]) -> dict[str, Any]:
+    for key, value in labels.items():
+        if _SENSITIVE_PATTERN.search(str(key)):
+            continue
+        if key in _HIGH_CARDINALITY:
+            continue
+        if key not in _ALLOWED_LABELS:
+            raise ProtocolObservabilityError(f"unsafe observability label: {key}")
+        if isinstance(value, str) and len(value) > 128:
+            raise ProtocolObservabilityError(f"unsafe observability label value: {key}")
+    return dict(labels)
+
+
+def certification_evidence_links(
+    *,
+    evidence_id: str,
+    protocol_claim_ids: tuple[str, ...],
+    transport_claim_ids: tuple[str, ...],
+) -> dict[str, Any]:
+    if not protocol_claim_ids or not transport_claim_ids:
+        raise ProtocolObservabilityError("observability evidence requires protocol and transport claim links")
+    return {
+        "evidence_id": evidence_id,
+        "protocol_claim_ids": tuple(sorted(protocol_claim_ids)),
+        "transport_claim_ids": tuple(sorted(transport_claim_ids)),
+    }
+
+
+def _hash_label(value: Any) -> str:
+    return hashlib.sha256(str(value).encode("utf-8")).hexdigest()[:16]
+
+
+def _stable_mapping(payload: Mapping[str, Any]) -> dict[str, Any]:
+    return {key: payload[key] for key in sorted(payload)}
+
+
+__all__ = [
+    "ProtocolLabels",
+    "ProtocolObservabilityError",
+    "ObservabilityRecord",
+    "certification_evidence_links",
+    "lifecycle_event",
+    "make_observability_record",
+    "protocol_label_schema",
+    "protocol_transport_labels",
+    "propagate_otel_context",
+    "quic_operational_labels",
+    "redact_and_bound_labels",
+    "redact_mapping",
+    "tls_alpn_labels",
+    "validate_label_config",
+]

{tigrcorn_observability-0.3.16.dev12 → tigrcorn_observability-0.3.17.dev1}/src/tigrcorn_observability.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tigrcorn-observability
-Version: 0.3.16.dev12
+Version: 0.3.17.dev1
 Summary: Logging, metrics, tracing, DoS warning events, and release-evidence metadata for the Tigrcorn Python web server.
 Author-email: Jacob Stewart <jacob@swarmauri.com>
 License: Apache License
@@ -186,8 +186,8 @@ Classifier: Typing :: Typed
 Requires-Python: <3.15,>=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: tigrcorn-core==0.3.16.dev12
-Requires-Dist: tigrcorn-config==0.3.16.dev12
+Requires-Dist: tigrcorn-core==0.3.17.dev1
+Requires-Dist: tigrcorn-config==0.3.17.dev1
 Dynamic: license-file
 
 <div align="center">

{tigrcorn_observability-0.3.16.dev12 → tigrcorn_observability-0.3.17.dev1}/src/tigrcorn_observability.egg-info/SOURCES.txt

@@ -5,6 +5,7 @@ src/tigrcorn_observability/__init__.py
 src/tigrcorn_observability/events.py
 src/tigrcorn_observability/logging.py
 src/tigrcorn_observability/metrics.py
+src/tigrcorn_observability/protocol.py
 src/tigrcorn_observability/py.typed
 src/tigrcorn_observability/tracing.py
 src/tigrcorn_observability.egg-info/PKG-INFO

tigrcorn_observability-0.3.17.dev1/src/tigrcorn_observability.egg-info/requires.txt

@@ -0,0 +1,2 @@
+tigrcorn-core==0.3.17.dev1
+tigrcorn-config==0.3.17.dev1

tigrcorn_observability-0.3.16.dev12/src/tigrcorn_observability/__init__.py

@@ -1 +0,0 @@
-"""Logging, metrics, tracing helpers."""

tigrcorn_observability-0.3.16.dev12/src/tigrcorn_observability.egg-info/requires.txt

@@ -1,2 +0,0 @@
-tigrcorn-core==0.3.16.dev12
-tigrcorn-config==0.3.16.dev12