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

clue_python_sdk_core/requests_instrumentation.py

@@ -0,0 +1,341 @@
+from __future__ import annotations
+
+import time
+from importlib import import_module
+
+from .adapters import (
+	build_summary_event,
+	build_outbound_request_failed_event,
+	build_outbound_request_finished_event,
+	build_outbound_request_started_event,
+)
+from .contracts import DEPENDENCY_SUMMARY_EVENT, SDK_COLLECTION_MODE_STANDARD
+from .http_extraction import _safe_urlsplit, to_path_template
+from .otel_bridge import annotate_current_otel_span, build_otel_request_span_id, resolve_current_otel_span_context
+from .runtime import (
+	add_event,
+	create_request_span_id,
+	create_span_id,
+	get_current_client,
+	get_current_context,
+	load_settings,
+)
+
+_patched = False
+_original_request = None
+
+
+def _read_context_string(context: object, key: str) -> str | None:
+	if isinstance(context, dict):
+		value = context.get(key)
+		return value if isinstance(value, str) and value else None
+	return None
+
+
+def _with_propagation_headers(
+	headers: object,
+	*,
+	context: object,
+	span_id: str,
+	request_span_id: str,
+) -> dict[str, str]:
+	propagated: dict[str, str] = {}
+	if isinstance(headers, dict):
+		propagated.update({str(key): str(value) for key, value in headers.items()})
+
+	def set_if_absent(name: str, value: str | None) -> None:
+		if not value:
+			return
+		if any(existing.lower() == name.lower() for existing in propagated):
+			return
+		propagated[name] = value
+
+	set_if_absent("x-clue-trace-id", _read_context_string(context, "trace_id"))
+	set_if_absent("x-clue-parent-span-id", span_id)
+	set_if_absent("x-clue-request-id", _read_context_string(context, "request_id"))
+	set_if_absent("x-clue-request-span-id", request_span_id)
+	set_if_absent("x-clue-interaction-id", _read_context_string(context, "interaction_id"))
+	set_if_absent("x-clue-session-id", _read_context_string(context, "session_id"))
+	set_if_absent("x-clue-anonymous-id", _read_context_string(context, "anonymous_id"))
+	set_if_absent("x-clue-user-id", _read_context_string(context, "user_id"))
+	set_if_absent("x-clue-account-id", _read_context_string(context, "account_id"))
+	set_if_absent("x-clue-tab-id", _read_context_string(context, "tab_id"))
+	return propagated
+
+
+def _status_class(status_code: int) -> str:
+	if status_code >= 500:
+		return "5xx"
+	if status_code >= 400:
+		return "4xx"
+	if status_code >= 300:
+		return "3xx"
+	if status_code >= 200:
+		return "2xx"
+	return "unknown"
+
+
+def _duration_bucket(duration_ms: int) -> str:
+	if duration_ms < 100:
+		return "lt_100ms"
+	if duration_ms < 500:
+		return "100_499ms"
+	if duration_ms < 2_000:
+		return "500_1999ms"
+	if duration_ms < 5_000:
+		return "2000_4999ms"
+	return "gte_5000ms"
+
+
+def _dependency_context(
+	context: object,
+	*,
+	span_id: str,
+	parent_span_id: str | None,
+	request_span_id: str,
+) -> dict[str, object]:
+	event_context = dict(context) if isinstance(context, dict) else {}
+	event_context["span_id"] = span_id
+	event_context["parent_span_id"] = parent_span_id
+	event_context["request_span_id"] = request_span_id
+	return event_context
+
+
+def _build_dependency_summary_event(
+	*,
+	context: object,
+	method: str,
+	url: str,
+	status_code: int,
+	duration_ms: int,
+	span_id: str,
+	parent_span_id: str | None,
+	request_span_id: str,
+	denied_keys: tuple[str, ...],
+):
+	scheme, host, path, _query = _safe_urlsplit(url)
+	path_template = to_path_template(path)
+	return build_summary_event(
+		context=_dependency_context(
+			context,
+			span_id=span_id,
+			parent_span_id=parent_span_id,
+			request_span_id=request_span_id,
+		),
+		event_name=DEPENDENCY_SUMMARY_EVENT,
+		collector_name="requests",
+		aggregation_kind="request",
+		summary_window_ms=0,
+		summary_count=1,
+		budget_window_ms=60_000,
+		rate_limit_key=f"dependency:{host or 'unknown'}:{_status_class(status_code)}",
+		properties={
+			"target_service": host or None,
+			"method": method.upper(),
+			"path_template": path_template,
+			"protocol": scheme or None,
+			"status_class": _status_class(status_code),
+			"duration_bucket": _duration_bucket(duration_ms),
+		},
+		metrics={
+			"status_code": status_code,
+			"duration_ms": duration_ms,
+			"normal_success_count": 1 if 200 <= status_code < 500 else 0,
+		},
+		denied_keys=denied_keys,
+	)
+
+
+def _record_summary_metric(client: object, count: int = 1) -> None:
+	record = getattr(client, "record_events_summarized", None)
+	if callable(record):
+		record(count)
+
+
+def instrument_requests() -> bool:
+	global _patched
+	global _original_request
+
+	if _patched:
+		return True
+
+	settings = load_settings()
+	if not settings.enabled or not settings.capture_outbound_requests:
+		return False
+
+	try:
+		sessions_module = import_module("requests.sessions")
+	except ImportError:
+		return False
+
+	session_class = getattr(sessions_module, "Session", None)
+	if session_class is None:
+		return False
+
+	original_request = getattr(session_class, "request", None)
+	if not callable(original_request):
+		return False
+
+	def wrapped_request(self, method, url, **kwargs):
+		context = get_current_context()
+		if context is None:
+			return original_request(self, method, url, **kwargs)
+
+		otel_span = resolve_current_otel_span_context("CLIENT")
+		parent_span_id = (
+			otel_span.get("parent_span_id") or None
+			if otel_span is not None
+			else (
+				context.get("span_id")
+				if isinstance(context.get("span_id"), str)
+				else None
+			)
+		)
+		span_id = (
+			otel_span["span_id"]
+			if otel_span is not None and otel_span.get("span_id")
+			else create_span_id()
+		)
+		request_span_id = (
+			build_otel_request_span_id(otel_span["trace_id"], otel_span["span_id"])
+			if otel_span is not None
+			else create_request_span_id()
+		)
+		annotate_current_otel_span(
+			{
+				"clue.request_span_id": request_span_id,
+			},
+			expected_kind="CLIENT",
+		)
+		request_headers = _with_propagation_headers(
+			kwargs.get("headers"),
+			context=context,
+			span_id=span_id,
+			request_span_id=request_span_id,
+		)
+		request_kwargs = {**kwargs, "headers": request_headers}
+		started_at = time.perf_counter()
+		if settings.sdk_collection_mode != SDK_COLLECTION_MODE_STANDARD:
+			add_event(
+				build_outbound_request_started_event(
+					context=context,
+					method=str(method),
+					url=str(url),
+					request_body=request_kwargs.get("json", request_kwargs.get("data")),
+					request_headers=request_headers,
+					timeout_ms=_timeout_ms(request_kwargs.get("timeout")),
+					allowed_value_paths=settings.allowed_value_paths,
+					denied_keys=settings.denied_keys,
+					span_id=span_id,
+					parent_span_id=parent_span_id,
+					request_span_id=request_span_id,
+				)
+			)
+		try:
+			response = original_request(self, method, url, **request_kwargs)
+		except Exception as exc:
+			add_event(
+				build_outbound_request_failed_event(
+					context=context,
+					method=str(method),
+					url=str(url),
+					failure_type=exc.__class__.__name__,
+					duration_ms=int((time.perf_counter() - started_at) * 1000),
+					status_code=0,
+					request_body=request_kwargs.get("json", request_kwargs.get("data")),
+					request_headers=request_headers,
+					allowed_value_paths=settings.allowed_value_paths,
+					denied_keys=settings.denied_keys,
+					timeout_ms=_timeout_ms(request_kwargs.get("timeout")),
+					span_id=span_id,
+					parent_span_id=parent_span_id,
+					request_span_id=request_span_id,
+				)
+			)
+			raise
+
+		status_code = int(getattr(response, "status_code", 0) or 0)
+		duration_ms = int((time.perf_counter() - started_at) * 1000)
+		if (
+			settings.sdk_collection_mode == SDK_COLLECTION_MODE_STANDARD
+			and status_code < 500
+			and duration_ms < 2_000
+		):
+			summary_event = _build_dependency_summary_event(
+				context=context,
+				method=str(method),
+				url=str(url),
+				status_code=status_code,
+				duration_ms=duration_ms,
+				span_id=span_id,
+				parent_span_id=parent_span_id,
+				request_span_id=request_span_id,
+				denied_keys=settings.denied_keys,
+			)
+			if add_event(summary_event):
+				_record_summary_metric(get_current_client())
+		else:
+			add_event(
+				build_outbound_request_finished_event(
+					context=context,
+					method=str(method),
+					url=str(url),
+					status_code=status_code,
+					duration_ms=duration_ms,
+					request_body=request_kwargs.get("json", request_kwargs.get("data")),
+					request_headers=request_headers,
+					response_body=_response_body(response),
+					response_headers=getattr(response, "headers", None),
+					allowed_value_paths=settings.allowed_value_paths,
+					denied_keys=settings.denied_keys,
+					timeout_ms=_timeout_ms(request_kwargs.get("timeout")),
+					span_id=span_id,
+					parent_span_id=parent_span_id,
+					request_span_id=request_span_id,
+				)
+			)
+		return response
+
+	_original_request = original_request
+	session_class.request = wrapped_request
+	_patched = True
+	return True
+
+
+def reset_requests_instrumentation() -> None:
+	global _patched
+	global _original_request
+
+	if not _patched or _original_request is None:
+		return
+
+	try:
+		sessions_module = import_module("requests.sessions")
+	except ImportError:
+		return
+
+	session_class = getattr(sessions_module, "Session", None)
+	if session_class is None:
+		return
+
+	session_class.request = _original_request
+	_original_request = None
+	_patched = False
+
+
+def _timeout_ms(value: object) -> int | None:
+	if isinstance(value, (int, float)):
+		return int(float(value) * 1000)
+	if isinstance(value, tuple) and value:
+		first = value[0]
+		if isinstance(first, (int, float)):
+			return int(float(first) * 1000)
+	return None
+
+
+def _response_body(response: object) -> object:
+	if hasattr(response, "content"):
+		return getattr(response, "content")
+	if hasattr(response, "text"):
+		return getattr(response, "text")
+	return None

clue_python_sdk_core/resources.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class CluePythonResourceConfig:
+	service_name: str
+	project_key: str
+	environment: str
+	deployment_environment: str
+	service_type: str
+	producer_id: str = "python-service"
+	service_version: str | None = None
+	service_namespace: str | None = None
+
+
+def build_resource_attributes(
+	config: CluePythonResourceConfig,
+) -> dict[str, str]:
+	attributes = {
+		"service.name": config.service_name,
+		"clue.producer_id": config.producer_id,
+		"deployment.environment": config.deployment_environment,
+		"clue.project_key": config.project_key,
+		"clue.environment": config.environment,
+		"clue.runtime_language": "python",
+		"clue.service_type": config.service_type,
+	}
+
+	if config.service_version:
+		attributes["service.version"] = config.service_version
+	if config.service_namespace:
+		attributes["service.namespace"] = config.service_namespace
+
+	return attributes
+
+
+def serialize_resource_attributes(attributes: dict[str, str]) -> str:
+	return ",".join(
+		f"{key}={value}"
+		for key, value in sorted(attributes.items())
+		if value
+	)