clue-python-sdk-core 0.0.1__py3-none-any.whl

clue_python_sdk_core/client.py

@@ -0,0 +1,335 @@
+from __future__ import annotations
+
+import json
+import threading
+import uuid
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass
+from urllib.request import Request, urlopen
+
+from .adapters import JsonValue, build_backend_envelope
+from .contracts import EVENT_CATEGORY_OUTBOUND_REQUEST, EVENT_CATEGORY_REQUEST
+from .event_size import DEFAULT_MAX_EVENT_BYTES, normalize_event_for_size
+
+DEFAULT_MAX_PAYLOAD_BYTES = 256 * 1024
+DEFAULT_FLUSH_THRESHOLD_BYTES = 220 * 1024
+DEFAULT_MAX_BUFFER_BYTES = 2 * 1024 * 1024
+DEFAULT_MAX_BUFFER_EVENTS = 10_000
+DEFAULT_FLUSH_INTERVAL_MS = 180_000
+
+
+def _json_bytes(value: Mapping[str, JsonValue]) -> bytes:
+	return json.dumps(value, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
+
+
+@dataclass(frozen=True)
+class _BatchMetadata:
+	batch_id: str
+	idempotency_key: str
+	sent_at: str
+
+
+def _backend_ingest_url(endpoint: str) -> str:
+	if endpoint.endswith("/ingest/backend"):
+		return endpoint
+	if endpoint.endswith("/api/v1"):
+		return f"{endpoint}/ingest/backend"
+	return f"{endpoint}/api/v1/ingest/backend"
+
+
+class CluePythonClient:
+	def __init__(
+		self,
+		*,
+		endpoint: str,
+		project_key: str,
+		environment: str,
+		producer_id: str = "python-service",
+		api_key: str | None = None,
+		timeout_seconds: float = 5.0,
+		max_event_bytes: int | None = DEFAULT_MAX_EVENT_BYTES,
+		max_payload_bytes: int = DEFAULT_MAX_PAYLOAD_BYTES,
+		flush_threshold_bytes: int = DEFAULT_FLUSH_THRESHOLD_BYTES,
+		max_buffer_bytes: int = DEFAULT_MAX_BUFFER_BYTES,
+		max_buffer_events: int = DEFAULT_MAX_BUFFER_EVENTS,
+		flush_interval_ms: int = DEFAULT_FLUSH_INTERVAL_MS,
+		auto_flush: bool = False,
+		opener: Callable[..., object] | None = None,
+	) -> None:
+		self._endpoint = endpoint.rstrip("/")
+		self._project_key = project_key
+		self._environment = environment
+		self._producer_id = producer_id
+		self._api_key = api_key
+		self._timeout_seconds = timeout_seconds
+		self._max_event_bytes = max_event_bytes
+		self._max_payload_bytes = max(1024, max_payload_bytes)
+		self._flush_threshold_bytes = max(1024, min(flush_threshold_bytes, self._max_payload_bytes))
+		self._max_buffer_bytes = max(1024, max_buffer_bytes)
+		self._max_buffer_events = max(1, max_buffer_events)
+		self._flush_interval_ms = max(1, flush_interval_ms)
+		self._auto_flush = auto_flush
+		self._opener = opener or urlopen
+		self._buffer: list[Mapping[str, JsonValue]] = []
+		self._buffer_bytes = 0
+		self._failed_batches: list[tuple[_BatchMetadata, list[Mapping[str, JsonValue]]]] = []
+		self._idle_timer: threading.Timer | None = None
+		self._lock = threading.RLock()
+		self._dropped_oversized_count = 0
+		self._parameter_snapshot_oversized_dropped = 0
+		self._dropped_buffer_full_count = 0
+		self._events_summarized_count = 0
+		self._sampling_dropped_count = 0
+		self._flush_failed_count = 0
+		self._flush_retry_count = 0
+		self._last_flush_status = "skipped"
+
+	def add_event(self, event: Mapping[str, JsonValue]) -> bool:
+		normalized_event = normalize_event_for_size(event, self._max_event_bytes)
+		if normalized_event is None:
+			self._dropped_oversized_count += 1
+			if event.get("event_category") in {
+				EVENT_CATEGORY_REQUEST,
+				EVENT_CATEGORY_OUTBOUND_REQUEST,
+			}:
+				self._parameter_snapshot_oversized_dropped += 1
+			return False
+
+		event_bytes = self._measure_event_bytes(normalized_event)
+		with self._lock:
+			while self._buffer and (
+				len(self._buffer) >= self._max_buffer_events
+				or self._buffer_bytes + event_bytes > self._max_buffer_bytes
+			):
+				dropped = self._buffer.pop(0)
+				self._buffer_bytes = max(
+					0,
+					self._buffer_bytes - self._measure_event_bytes(dropped),
+				)
+				self._dropped_buffer_full_count += 1
+
+			if (
+				len(self._buffer) >= self._max_buffer_events
+				or self._buffer_bytes + event_bytes > self._max_buffer_bytes
+			):
+				self._dropped_buffer_full_count += 1
+				return False
+
+			self._buffer.append(normalized_event)
+			self._buffer_bytes += event_bytes
+
+			if self._auto_flush and self._buffer_bytes >= self._flush_threshold_bytes:
+				self._cancel_idle_timer()
+				should_flush = True
+			else:
+				self._schedule_idle_flush_locked()
+				should_flush = False
+
+		if should_flush:
+			try:
+				self.flush()
+			except Exception:
+				return True
+		return True
+
+	def record_events_summarized(self, count: int = 1) -> None:
+		self._events_summarized_count += max(0, int(count))
+
+	def record_sampling_dropped(self, count: int = 1) -> None:
+		self._sampling_dropped_count += max(0, int(count))
+
+	def build_envelope(
+		self,
+		events: Sequence[Mapping[str, JsonValue]] | None = None,
+		metadata: _BatchMetadata | None = None,
+	) -> dict[str, JsonValue]:
+		resolved_metadata = metadata or self._create_batch_metadata()
+		return build_backend_envelope(
+			project_key=self._project_key,
+			environment=self._environment,
+			producer_id=self._producer_id,
+			api_key=self._api_key,
+			batch_id=resolved_metadata.batch_id,
+			idempotency_key=resolved_metadata.idempotency_key,
+			sent_at=resolved_metadata.sent_at,
+			events=events if events is not None else self.pending_events(),
+		)
+
+	def flush(self, timeout_seconds: float | None = None) -> dict[str, JsonValue]:
+		self._cancel_idle_timer()
+		result: dict[str, JsonValue] = {}
+		while True:
+			batch = self._next_batch()
+			if batch is None:
+				return result
+			metadata, events = batch
+			envelope = self.build_envelope(events=events, metadata=metadata)
+			result = self._send_envelope(
+				envelope,
+				timeout_seconds=timeout_seconds or self._timeout_seconds,
+				on_failure=lambda: self._restore_failed_batch(metadata, events),
+			)
+
+	def _send_envelope(
+		self,
+		envelope: Mapping[str, JsonValue],
+		*,
+		timeout_seconds: float,
+		on_failure: Callable[[], None],
+	) -> dict[str, JsonValue]:
+		request = Request(
+			url=_backend_ingest_url(self._endpoint),
+			data=_json_bytes(envelope),
+			headers={
+				"content-type": "application/json",
+				"x-clue-project-key": self._project_key,
+				**({"x-clue-api-key": self._api_key} if self._api_key else {}),
+			},
+			method="POST",
+		)
+
+		try:
+			response = self._opener(request, timeout=timeout_seconds)
+			body = response.read()
+		except Exception:
+			self._flush_failed_count += 1
+			self._last_flush_status = "failed"
+			on_failure()
+			raise
+		self._last_flush_status = "success"
+		if not body:
+			return {}
+		return json.loads(body.decode("utf-8"))
+
+	def pending_events(self) -> Sequence[Mapping[str, JsonValue]]:
+		with self._lock:
+			failed_events = [
+				event
+				for _metadata, events in self._failed_batches
+				for event in events
+			]
+			return tuple([*failed_events, *self._buffer])
+
+	def drain_events(self) -> Sequence[Mapping[str, JsonValue]]:
+		with self._lock:
+			events = tuple(self._buffer)
+			self._buffer.clear()
+			self._buffer_bytes = 0
+			self._cancel_idle_timer()
+			return events
+
+	def close(self) -> None:
+		self._cancel_idle_timer()
+
+	def internal_metrics(self) -> dict[str, JsonValue]:
+		queue_size = len(self.pending_events())
+		return {
+			"events_dropped_count": (
+				self._dropped_oversized_count + self._dropped_buffer_full_count
+			),
+			"events_summarized_count": self._events_summarized_count,
+			"sampling_dropped_count": self._sampling_dropped_count,
+			"oversized_event_count": self._dropped_oversized_count,
+			"snapshot_truncated_count": self._parameter_snapshot_oversized_dropped,
+			"flush_failed_count": self._flush_failed_count,
+			"flush_retry_count": self._flush_retry_count,
+			"queue_size": queue_size,
+			"queue_bytes": self._buffer_bytes,
+			"max_payload_bytes": self._max_payload_bytes,
+			"flush_threshold_bytes": self._flush_threshold_bytes,
+			"last_flush_status": self._last_flush_status,
+			"dropped_oversized_count": self._dropped_oversized_count,
+			"parameter_snapshot_oversized_dropped": self._parameter_snapshot_oversized_dropped,
+			"dropped_buffer_full_count": self._dropped_buffer_full_count,
+			"flush_interval_ms": self._flush_interval_ms,
+		}
+
+	def _create_batch_metadata(self) -> _BatchMetadata:
+		batch_id = str(uuid.uuid4())
+		return _BatchMetadata(
+			batch_id=f"batch_{batch_id}",
+			idempotency_key=f"idem_{batch_id}",
+			sent_at=self._now_iso(),
+		)
+
+	def _next_batch(self) -> tuple[_BatchMetadata, list[Mapping[str, JsonValue]]] | None:
+		with self._lock:
+			if self._failed_batches:
+				return self._failed_batches.pop(0)
+			if not self._buffer:
+				return None
+
+			metadata = self._create_batch_metadata()
+			batch: list[Mapping[str, JsonValue]] = []
+			while self._buffer:
+				candidate = [*batch, self._buffer[0]]
+				if batch and self._measure_envelope_bytes(candidate, metadata) > self._max_payload_bytes:
+					break
+				event = self._buffer.pop(0)
+				self._buffer_bytes = max(
+					0,
+					self._buffer_bytes - self._measure_event_bytes(event),
+				)
+				batch.append(event)
+
+			if not batch:
+				event = self._buffer.pop(0)
+				self._buffer_bytes = max(
+					0,
+					self._buffer_bytes - self._measure_event_bytes(event),
+				)
+				self._dropped_oversized_count += 1
+				return None
+			return metadata, batch
+
+	def _restore_failed_batch(
+		self,
+		metadata: _BatchMetadata,
+		events: list[Mapping[str, JsonValue]],
+	) -> None:
+		with self._lock:
+			self._failed_batches.insert(0, (metadata, events))
+			if self._auto_flush:
+				self._schedule_idle_flush_locked()
+
+	def _schedule_idle_flush_locked(self) -> None:
+		if not self._auto_flush:
+			return
+		if self._idle_timer is not None:
+			self._idle_timer.cancel()
+		self._idle_timer = threading.Timer(
+			self._flush_interval_ms / 1000,
+			self._flush_from_timer,
+		)
+		self._idle_timer.daemon = True
+		self._idle_timer.start()
+
+	def _cancel_idle_timer(self) -> None:
+		if self._idle_timer is not None:
+			self._idle_timer.cancel()
+			self._idle_timer = None
+
+	def _flush_from_timer(self) -> None:
+		with self._lock:
+			self._idle_timer = None
+		try:
+			self.flush()
+		except Exception:
+			return
+
+	def _measure_event_bytes(self, event: Mapping[str, JsonValue]) -> int:
+		return len(_json_bytes(event))
+
+	def _measure_envelope_bytes(
+		self,
+		events: Sequence[Mapping[str, JsonValue]],
+		metadata: _BatchMetadata,
+	) -> int:
+		return len(
+			_json_bytes(self.build_envelope(events=events, metadata=metadata))
+		)
+
+	def _now_iso(self) -> str:
+		from datetime import datetime, timezone
+
+		return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")

clue_python_sdk_core/contracts.py

@@ -0,0 +1,224 @@
+from __future__ import annotations
+
+BACKEND_STATUS_OBSERVED = "observed"
+BACKEND_STATUS_STARTED = "started"
+BACKEND_STATUS_FINISHED = "finished"
+BACKEND_STATUS_FAILED = "failed"
+BACKEND_STATUSES = (
+	BACKEND_STATUS_OBSERVED,
+	BACKEND_STATUS_STARTED,
+	BACKEND_STATUS_FINISHED,
+	BACKEND_STATUS_FAILED,
+)
+
+BACKEND_SDK_TYPE = "backend"
+BACKEND_SDK_VERSION = "0.0.1"
+BACKEND_SDK_SCHEMA_VERSION = 1
+BACKEND_RUNTIME_LANGUAGE = "python"
+
+SDK_COLLECTION_MODE_STANDARD = "standard"
+SDK_COLLECTION_MODE_DIAGNOSTIC = "diagnostic"
+SDK_COLLECTION_MODES = (
+	SDK_COLLECTION_MODE_STANDARD,
+	SDK_COLLECTION_MODE_DIAGNOSTIC,
+)
+
+EVENT_CATEGORY_REQUEST = "request"
+EVENT_CATEGORY_OUTBOUND_REQUEST = "outbound_request"
+EVENT_CATEGORY_ERROR = "error"
+EVENT_CATEGORY_JOB = "job"
+EVENT_CATEGORY_TOOL_CALL = "tool_call"
+EVENT_CATEGORY_DOMAIN_COMMAND = "domain_command"
+EVENT_CATEGORY_REPOSITORY_MUTATION = "repository_mutation"
+EVENT_CATEGORY_STATE_TRANSITION = "state_transition"
+EVENT_CATEGORY_CUSTOM = "custom"
+BACKEND_EVENT_CATEGORIES = (
+	EVENT_CATEGORY_REQUEST,
+	EVENT_CATEGORY_ERROR,
+	EVENT_CATEGORY_OUTBOUND_REQUEST,
+	EVENT_CATEGORY_JOB,
+	EVENT_CATEGORY_TOOL_CALL,
+	EVENT_CATEGORY_DOMAIN_COMMAND,
+	EVENT_CATEGORY_REPOSITORY_MUTATION,
+	EVENT_CATEGORY_STATE_TRANSITION,
+	EVENT_CATEGORY_CUSTOM,
+)
+PYTHON_RUNTIME_EVENT_CATEGORIES = (
+	EVENT_CATEGORY_REQUEST,
+	EVENT_CATEGORY_OUTBOUND_REQUEST,
+	EVENT_CATEGORY_ERROR,
+	EVENT_CATEGORY_JOB,
+	EVENT_CATEGORY_TOOL_CALL,
+	EVENT_CATEGORY_DOMAIN_COMMAND,
+	EVENT_CATEGORY_REPOSITORY_MUTATION,
+	EVENT_CATEGORY_STATE_TRANSITION,
+	EVENT_CATEGORY_CUSTOM,
+)
+
+REQUEST_EVENT_STARTED = "request_started"
+REQUEST_EVENT_FINISHED = "request_finished"
+REQUEST_EVENT_FAILED = "request_failed"
+
+OUTBOUND_REQUEST_EVENT_STARTED = "outbound_request_started"
+OUTBOUND_REQUEST_EVENT_FINISHED = "outbound_request_finished"
+OUTBOUND_REQUEST_EVENT_FAILED = "outbound_request_failed"
+
+JOB_EVENT_STARTED = "job_started"
+JOB_EVENT_FINISHED = "job_finished"
+JOB_EVENT_FAILED = "job_failed"
+
+TOOL_CALL_EVENT_STARTED = "tool_call_started"
+TOOL_CALL_EVENT_FINISHED = "tool_call_finished"
+TOOL_CALL_EVENT_FAILED = "tool_call_failed"
+
+DOMAIN_COMMAND_EVENT_STARTED = "domain_command_started"
+DOMAIN_COMMAND_EVENT_FINISHED = "domain_command_finished"
+DOMAIN_COMMAND_EVENT_FAILED = "domain_command_failed"
+
+REPOSITORY_MUTATION_EVENT_STARTED = "repository_mutation_started"
+REPOSITORY_MUTATION_EVENT_FINISHED = "repository_mutation_finished"
+REPOSITORY_MUTATION_EVENT_FAILED = "repository_mutation_failed"
+
+STATE_TRANSITION_EVENT_STARTED = "state_transition_started"
+STATE_TRANSITION_EVENT_FINISHED = "state_transition_finished"
+STATE_TRANSITION_EVENT_FAILED = "state_transition_failed"
+
+BACKEND_ERROR_EVENT = "backend_error"
+CUSTOM_EVENT_EMITTED = "custom_emitted"
+REPOSITORY_MUTATION_SUMMARY_EVENT = "repository_mutation_summary"
+QUEUE_LIFECYCLE_SUMMARY_EVENT = "queue_lifecycle_summary"
+DEPENDENCY_SUMMARY_EVENT = "dependency_summary"
+CACHE_OPERATION_SUMMARY_EVENT = "cache_operation_summary"
+APPLICATION_LOG_SUMMARY_EVENT = "application_log_summary"
+SDK_DIAGNOSTIC_EVENT = "sdk_diagnostic_observed"
+CUSTOM_EVENT_SDK_INITIALIZED = "sdk_initialized"
+CUSTOM_EVENT_IDENTITY_IDENTIFIED = "identity_identified"
+CUSTOM_EVENT_ACCOUNT_ASSOCIATED = "account_associated"
+CUSTOM_EVENT_IDENTITY_LOGGED_OUT = "identity_logged_out"
+BACKEND_OFFICIAL_CUSTOM_EVENT_NAMES = (
+	CUSTOM_EVENT_SDK_INITIALIZED,
+	CUSTOM_EVENT_IDENTITY_IDENTIFIED,
+	CUSTOM_EVENT_ACCOUNT_ASSOCIATED,
+	CUSTOM_EVENT_IDENTITY_LOGGED_OUT,
+)
+
+JOB_EVENT_BY_STATUS = {
+	BACKEND_STATUS_STARTED: JOB_EVENT_STARTED,
+	BACKEND_STATUS_FINISHED: JOB_EVENT_FINISHED,
+	BACKEND_STATUS_FAILED: JOB_EVENT_FAILED,
+}
+
+TOOL_CALL_EVENT_BY_STATUS = {
+	BACKEND_STATUS_STARTED: TOOL_CALL_EVENT_STARTED,
+	BACKEND_STATUS_FINISHED: TOOL_CALL_EVENT_FINISHED,
+	BACKEND_STATUS_FAILED: TOOL_CALL_EVENT_FAILED,
+}
+
+DOMAIN_COMMAND_EVENT_BY_STATUS = {
+	BACKEND_STATUS_STARTED: DOMAIN_COMMAND_EVENT_STARTED,
+	BACKEND_STATUS_FINISHED: DOMAIN_COMMAND_EVENT_FINISHED,
+	BACKEND_STATUS_FAILED: DOMAIN_COMMAND_EVENT_FAILED,
+}
+
+REPOSITORY_MUTATION_EVENT_BY_STATUS = {
+	BACKEND_STATUS_STARTED: REPOSITORY_MUTATION_EVENT_STARTED,
+	BACKEND_STATUS_FINISHED: REPOSITORY_MUTATION_EVENT_FINISHED,
+	BACKEND_STATUS_FAILED: REPOSITORY_MUTATION_EVENT_FAILED,
+}
+
+STATE_TRANSITION_EVENT_BY_STATUS = {
+	BACKEND_STATUS_STARTED: STATE_TRANSITION_EVENT_STARTED,
+	BACKEND_STATUS_FINISHED: STATE_TRANSITION_EVENT_FINISHED,
+	BACKEND_STATUS_FAILED: STATE_TRANSITION_EVENT_FAILED,
+}
+
+PYTHON_RUNTIME_EVENT_NAMES = (
+	REQUEST_EVENT_STARTED,
+	REQUEST_EVENT_FINISHED,
+	REQUEST_EVENT_FAILED,
+	OUTBOUND_REQUEST_EVENT_STARTED,
+	OUTBOUND_REQUEST_EVENT_FINISHED,
+	OUTBOUND_REQUEST_EVENT_FAILED,
+	JOB_EVENT_STARTED,
+	JOB_EVENT_FINISHED,
+	JOB_EVENT_FAILED,
+	TOOL_CALL_EVENT_STARTED,
+	TOOL_CALL_EVENT_FINISHED,
+	TOOL_CALL_EVENT_FAILED,
+	DOMAIN_COMMAND_EVENT_STARTED,
+	DOMAIN_COMMAND_EVENT_FINISHED,
+	DOMAIN_COMMAND_EVENT_FAILED,
+	REPOSITORY_MUTATION_EVENT_STARTED,
+	REPOSITORY_MUTATION_EVENT_FINISHED,
+	REPOSITORY_MUTATION_EVENT_FAILED,
+	STATE_TRANSITION_EVENT_STARTED,
+	STATE_TRANSITION_EVENT_FINISHED,
+	STATE_TRANSITION_EVENT_FAILED,
+	BACKEND_ERROR_EVENT,
+	CUSTOM_EVENT_EMITTED,
+)
+BACKEND_EVENT_NAMES = (
+	REQUEST_EVENT_STARTED,
+	REQUEST_EVENT_FINISHED,
+	REQUEST_EVENT_FAILED,
+	OUTBOUND_REQUEST_EVENT_STARTED,
+	OUTBOUND_REQUEST_EVENT_FINISHED,
+	OUTBOUND_REQUEST_EVENT_FAILED,
+	JOB_EVENT_STARTED,
+	JOB_EVENT_FINISHED,
+	JOB_EVENT_FAILED,
+	TOOL_CALL_EVENT_STARTED,
+	TOOL_CALL_EVENT_FINISHED,
+	TOOL_CALL_EVENT_FAILED,
+	DOMAIN_COMMAND_EVENT_STARTED,
+	DOMAIN_COMMAND_EVENT_FINISHED,
+	DOMAIN_COMMAND_EVENT_FAILED,
+	REPOSITORY_MUTATION_EVENT_STARTED,
+	REPOSITORY_MUTATION_EVENT_FINISHED,
+	REPOSITORY_MUTATION_EVENT_FAILED,
+	STATE_TRANSITION_EVENT_STARTED,
+	STATE_TRANSITION_EVENT_FINISHED,
+	STATE_TRANSITION_EVENT_FAILED,
+	BACKEND_ERROR_EVENT,
+	REPOSITORY_MUTATION_SUMMARY_EVENT,
+	QUEUE_LIFECYCLE_SUMMARY_EVENT,
+	DEPENDENCY_SUMMARY_EVENT,
+	CACHE_OPERATION_SUMMARY_EVENT,
+	APPLICATION_LOG_SUMMARY_EVENT,
+	SDK_DIAGNOSTIC_EVENT,
+	CUSTOM_EVENT_EMITTED,
+)
+
+SURFACE_TYPE_API = "api"
+SURFACE_TYPE_SERVICE = "service"
+SURFACE_TYPE_JOB = "job"
+BACKEND_SURFACE_TYPES = (
+	SURFACE_TYPE_API,
+	SURFACE_TYPE_SERVICE,
+	SURFACE_TYPE_JOB,
+)
+
+CAPTURE_MODE_ALLOWED_PLAINTEXT = "allowed_plaintext"
+CAPTURE_MODE_MASKED_FINGERPRINT = "masked_fingerprint"
+CAPTURE_MODE_FORBIDDEN = "forbidden"
+CAPTURE_MODE_TRUNCATED = "truncated"
+BACKEND_CAPTURE_MODES = (
+	CAPTURE_MODE_ALLOWED_PLAINTEXT,
+	CAPTURE_MODE_MASKED_FINGERPRINT,
+	CAPTURE_MODE_FORBIDDEN,
+	CAPTURE_MODE_TRUNCATED,
+)
+
+BACKEND_LIFECYCLE_MARKERS = (
+	"start",
+	"finish",
+	"fail",
+)
+
+BACKEND_MUTATION_KINDS = (
+	"create",
+	"update",
+	"delete",
+	"upsert",
+	"bulk_write",
+)

clue_python_sdk_core/event_size.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+
+from .contracts import (
+	CAPTURE_MODE_TRUNCATED,
+	EVENT_CATEGORY_OUTBOUND_REQUEST,
+	EVENT_CATEGORY_REQUEST,
+)
+from .privacy import JsonValue
+
+DEFAULT_MAX_EVENT_BYTES = 128 * 1024
+TRUNCATED_PARAMETER_VALUE = "__truncated__"
+PARAMETER_SNAPSHOT_FIELDS = (
+	"request_parameters_snapshot_json",
+	"response_parameters_snapshot_json",
+)
+
+
+def measure_event_bytes(event: Mapping[str, JsonValue]) -> int:
+	return len(
+		json.dumps(event, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
+	)
+
+
+def _is_parameter_leaf(value: JsonValue) -> bool:
+	return (
+		isinstance(value, dict)
+		and isinstance(value.get("type"), str)
+		and isinstance(value.get("capture_mode"), str)
+		and "value" in value
+	)
+
+
+def _truncate_parameter_snapshot(value: JsonValue) -> JsonValue:
+	if isinstance(value, list):
+		return [_truncate_parameter_snapshot(entry) for entry in value]
+
+	if _is_parameter_leaf(value):
+		return {
+			"type": value.get("type"),
+			"value": TRUNCATED_PARAMETER_VALUE,
+			"capture_mode": CAPTURE_MODE_TRUNCATED,
+		}
+
+	if isinstance(value, dict):
+		return {
+			str(key): _truncate_parameter_snapshot(child)
+			for key, child in value.items()
+		}
+
+	return value
+
+
+def _is_parameter_snapshot_event(event: Mapping[str, JsonValue]) -> bool:
+	return event.get("event_category") in {
+		EVENT_CATEGORY_REQUEST,
+		EVENT_CATEGORY_OUTBOUND_REQUEST,
+	}
+
+
+def normalize_event_for_size(
+	event: Mapping[str, JsonValue],
+	max_event_bytes: int | None,
+) -> dict[str, JsonValue] | None:
+	normalized = dict(event)
+	if max_event_bytes is None or max_event_bytes <= 0:
+		return normalized
+
+	if measure_event_bytes(normalized) <= max_event_bytes:
+		return normalized
+
+	if not _is_parameter_snapshot_event(normalized):
+		return None
+
+	has_snapshot = any(field in normalized for field in PARAMETER_SNAPSHOT_FIELDS)
+	if not has_snapshot:
+		return None
+
+	truncated = dict(normalized)
+	for field in PARAMETER_SNAPSHOT_FIELDS:
+		value = truncated.get(field)
+		if value is not None:
+			truncated[field] = _truncate_parameter_snapshot(value)
+
+	if isinstance(truncated.get("properties"), dict):
+		properties = dict(truncated["properties"])
+		properties["degradation_stage"] = "parameter_snapshot_truncated"
+		truncated["properties"] = properties
+	else:
+		truncated["properties"] = {
+			"degradation_stage": "parameter_snapshot_truncated",
+		}
+
+	return truncated if measure_event_bytes(truncated) <= max_event_bytes else None