fetchnode 0.4.0__py3-none-any.whl

fetchnode/__init__.py

@@ -0,0 +1,50 @@
+default_app_config = "fetchnode.apps.FetchNodeConfig"
+
+from fetchnode.version import SDK_VERSION
+
+__version__ = SDK_VERSION
+
+from fetchnode.api import capture_exception, capture_message, track, track_event
+from fetchnode.capture import (
+    capture_context,
+    capture_django_task,
+    capture_exceptions,
+    capture_job,
+    capture_job_context,
+    capture_job_exception,
+    capture_management_command,
+    track_job_execution,
+)
+from fetchnode.excepthook import (
+    install_excepthook_instrumentation,
+    restore_excepthook,
+    uninstall_excepthook_instrumentation,
+)
+from fetchnode.scope import add_breadcrumb, clear_scope, set_context, set_tag, set_user
+from fetchnode.sender import flush, transport_stats
+
+__all__ = [
+    "__version__",
+    "capture_exception",
+    "capture_message",
+    "track",
+    "track_event",
+    "capture_exceptions",
+    "capture_context",
+    "capture_job_exception",
+    "capture_job_context",
+    "capture_job",
+    "capture_django_task",
+    "track_job_execution",
+    "capture_management_command",
+    "install_excepthook_instrumentation",
+    "uninstall_excepthook_instrumentation",
+    "restore_excepthook",
+    "add_breadcrumb",
+    "clear_scope",
+    "set_context",
+    "set_tag",
+    "set_user",
+    "flush",
+    "transport_stats",
+]

fetchnode/api.py

@@ -0,0 +1,309 @@
+import hashlib
+import uuid
+
+from fetchnode.conf import get_client_settings
+from fetchnode.scope import get_scope_data
+from fetchnode.scrub import extract_headers, extract_request_data, scrub_mapping, scrub_query_string, scrub_value
+from fetchnode.sender import send_payload
+from fetchnode.utils import build_exception_values, get_server_name, runtime_context, utc_now_iso
+from fetchnode.version import SDK_VERSION
+
+
+SDK_CONTEXT = {"name": "fetchnode.python", "version": SDK_VERSION}
+
+
+def _base_payload(*, level: str, logger_name: str = "", tags=None, contexts=None, breadcrumbs=None) -> dict:
+    config = get_client_settings()
+    scope = get_scope_data()
+    merged_tags = {**scope["tags"], **(tags or {})}
+    merged_contexts = {**runtime_context(), **scope["contexts"], **(contexts or {})}
+    return {
+        "event_id": uuid.uuid4().hex,
+        "timestamp": utc_now_iso(),
+        "level": level,
+        "logger": logger_name,
+        "environment": config["ENVIRONMENT"],
+        "release": config["RELEASE"],
+        "server_name": get_server_name(),
+        "sdk": SDK_CONTEXT,
+        "tags": scrub_mapping(merged_tags, sensitive_keys=config["SENSITIVE_KEYS"]),
+        "contexts": scrub_value(merged_contexts, sensitive_keys=config["SENSITIVE_KEYS"]),
+        "breadcrumbs": scrub_value([*scope["breadcrumbs"], *(breadcrumbs or [])][-100:], sensitive_keys=config["SENSITIVE_KEYS"]),
+        "request": {},
+        "user": scrub_mapping(scope["user"], sensitive_keys=config["SENSITIVE_KEYS"]),
+    }
+
+
+def _request_context(request, config: dict) -> dict:
+    resolver_match = getattr(request, "resolver_match", None)
+    safe_query = ""
+    if config["CAPTURE_QUERY_STRING"]:
+        safe_query = scrub_query_string(
+            request.META.get("QUERY_STRING", ""),
+            sensitive_keys=config["SENSITIVE_KEYS"],
+        )
+    try:
+        url = request.build_absolute_uri(request.path)
+    except Exception:
+        url = request.path
+    if safe_query:
+        url = f"{url}?{safe_query}"
+    return {
+        "method": request.method,
+        "path": request.path,
+        "url": url,
+        "route": getattr(resolver_match, "route", "") or "",
+        "view_name": getattr(resolver_match, "view_name", "") or "",
+        "query_string": safe_query,
+        "ip_address": (
+            request.META.get("HTTP_X_FORWARDED_FOR", "").split(",", 1)[0].strip()
+            or request.META.get("REMOTE_ADDR", "")
+        ) if config["CAPTURE_IP_ADDRESS"] else "",
+        "headers": extract_headers(
+            request,
+            capture_headers=config["CAPTURE_HEADERS"],
+            sensitive_headers=config["SENSITIVE_HEADERS"],
+        ),
+        "data": extract_request_data(
+            request,
+            capture_body=config["CAPTURE_BODY"],
+            sensitive_keys=config["SENSITIVE_KEYS"],
+            max_body_length=config["MAX_BODY_LENGTH"],
+        ),
+    }
+
+
+def _request_user(request, config: dict) -> dict:
+    auth_user = getattr(request, "user", None)
+    if auth_user is None or not getattr(auth_user, "is_authenticated", False):
+        return {}
+    user = {}
+    if config["CAPTURE_USER_ID"]:
+        user["id"] = getattr(auth_user, "pk", "")
+    if config["CAPTURE_USERNAME"]:
+        user["username"] = getattr(auth_user, "get_username", lambda: "")()
+    if config["CAPTURE_USER_EMAIL"]:
+        user["email"] = getattr(auth_user, "email", "")
+    return user
+
+
+def _attach_request_and_user(payload: dict, *, request=None, user=None) -> None:
+    config = get_client_settings()
+    if request is not None:
+        payload["request"] = _request_context(request, config)
+        request_id = getattr(request, "_fetchnode_request_id", "") or request.headers.get("X-Request-ID", "")
+        traceparent = request.headers.get("Traceparent", "")
+        trace_id = getattr(request, "_fetchnode_trace_id", "")
+        if request_id:
+            payload["tags"]["request_id"] = request_id[:255]
+            payload["request_id"] = request_id[:64]
+        if trace_id:
+            payload["trace_id"] = trace_id[:32]
+        if traceparent or trace_id:
+            payload["contexts"]["trace"] = {
+                "traceparent": traceparent[:255],
+                "trace_id": trace_id[:32],
+                "transaction_event_id": getattr(request, "_fetchnode_transaction_event_id", "")[:32],
+            }
+        payload["user"] = scrub_mapping(_request_user(request, config), sensitive_keys=config["SENSITIVE_KEYS"])
+    if user:
+        payload["user"] = scrub_mapping(user, sensitive_keys=config["SENSITIVE_KEYS"])
+
+
+def build_exception_payload(
+    exc: BaseException,
+    request=None,
+    *,
+    user=None,
+    tags=None,
+    contexts=None,
+    breadcrumbs=None,
+    extra=None,
+    queries=None,
+    logger_name="",
+    mechanism="generic",
+    handled=True,
+) -> dict:
+    payload = _base_payload(
+        level="error",
+        logger_name=logger_name,
+        tags=tags,
+        contexts=contexts,
+        breadcrumbs=breadcrumbs,
+    )
+    values = build_exception_values(exc, mechanism=mechanism, handled=handled)
+    primary = values[-1]
+    payload["exception"] = {
+        "type": primary["type"],
+        "message": primary["message"],
+        "frames": primary["frames"],
+        "values": values,
+    }
+    if extra:
+        payload["extra"] = scrub_value(extra, sensitive_keys=get_client_settings()["SENSITIVE_KEYS"])
+    if queries:
+        payload["queries"] = scrub_value(list(queries)[:100], sensitive_keys=get_client_settings()["SENSITIVE_KEYS"])
+    _attach_request_and_user(payload, request=request, user=user)
+    return payload
+
+
+def capture_exception(
+    exc: BaseException,
+    request=None,
+    *,
+    user=None,
+    tags=None,
+    contexts=None,
+    breadcrumbs=None,
+    extra=None,
+    queries=None,
+    logger_name="",
+    mechanism="generic",
+    handled=True,
+) -> str:
+    payload = build_exception_payload(
+        exc,
+        request=request,
+        user=user,
+        tags=tags,
+        contexts=contexts,
+        breadcrumbs=breadcrumbs,
+        extra=extra,
+        queries=queries,
+        logger_name=logger_name,
+        mechanism=mechanism,
+        handled=handled,
+    )
+    send_payload(payload)
+    return payload["event_id"]
+
+
+def capture_message(
+    message: str,
+    *,
+    level: str = "error",
+    request=None,
+    user=None,
+    tags=None,
+    contexts=None,
+    breadcrumbs=None,
+    logger_name="",
+) -> str:
+    payload = _base_payload(
+        level=level,
+        logger_name=logger_name,
+        tags=tags,
+        contexts=contexts,
+        breadcrumbs=breadcrumbs,
+    )
+    payload["exception"] = {
+        "type": "Message",
+        "message": str(message),
+        "frames": [],
+        "values": [{
+            "type": "Message",
+            "module": "",
+            "message": str(message),
+            "frames": [],
+            "mechanism": {"type": "message", "handled": True},
+        }],
+    }
+    _attach_request_and_user(payload, request=request, user=user)
+    send_payload(payload)
+    return payload["event_id"]
+
+
+def track_event(
+    name: str = "",
+    properties: dict | None = None,
+    *,
+    user_identifier: str = "",
+    visitor_id: str = "",
+    session_id: str = "",
+    path: str = "",
+    environment: str = "",
+    conversion: dict | bool | str | None = None,
+    idempotency_key: str = "",
+    request=None,
+    event: str = "",
+    user_id: str = "",
+    distinct_id: str = "",
+    payload: dict | None = None,
+) -> str:
+    """Track a server-side product milestone such as signup_completed or lead_submitted.
+
+    Usage:
+        fetchnode.track("lead_submitted", request=request, idempotency_key=str(lead.id))
+        fetchnode.track("signup_completed", conversion=True, request=request)
+    """
+    event_name = str(name or event or "")
+    if not event_name:
+        raise ValueError("Event name is required for track_event.")
+
+    config = get_client_settings()
+    stable_key = str(idempotency_key or "")
+    if len(stable_key) > 512:
+        raise ValueError("idempotency_key must contain at most 512 characters.")
+    event_id = (
+        hashlib.sha256(f"{event_name}\0{stable_key}".encode("utf-8")).hexdigest()[:32]
+        if stable_key
+        else uuid.uuid4().hex
+    )
+
+    if request is not None:
+        path = path or getattr(request, "path", "")
+        if not visitor_id:
+            cookies = getattr(request, "COOKIES", {}) or {}
+            headers = getattr(request, "headers", {}) or {}
+            visitor_id = (
+                headers.get("X-FetchNode-Visitor-ID", "")
+                or cookies.get("_fn_vid", "")
+                or str(distinct_id or "")
+            )
+        if not session_id:
+            cookies = getattr(request, "COOKIES", {}) or {}
+            headers = getattr(request, "headers", {}) or {}
+            session_id = (
+                headers.get("X-FetchNode-Session-ID", "")
+                or cookies.get("_fn_sid", "")
+            )
+        if not user_identifier:
+            req_user = getattr(request, "user", None)
+            if req_user and getattr(req_user, "is_authenticated", False):
+                user_identifier = str(getattr(req_user, "pk", ""))
+            elif user_id:
+                user_identifier = str(user_id)
+
+    event_properties = scrub_value(properties or payload or {}, sensitive_keys=config["SENSITIVE_KEYS"])
+    if conversion is not None:
+        if conversion is True:
+            conv_obj = {"name": event_name}
+        elif isinstance(conversion, str):
+            conv_obj = {"name": conversion}
+        elif isinstance(conversion, dict):
+            conv_obj = conversion
+        else:
+            conv_obj = {"name": event_name}
+        event_properties["_fetchnode_conversion"] = scrub_value(
+            conv_obj,
+            sensitive_keys=config["SENSITIVE_KEYS"],
+        )
+    send_payload({
+        "event_id": event_id,
+        "type": "custom",
+        "name": str(event_name),
+        "payload": event_properties,
+        "user_identifier": str(user_identifier),
+        "visitor_id": str(visitor_id),
+        "session_id": str(session_id),
+        "path": str(path),
+        "timestamp": utc_now_iso(),
+        "environment": environment or config["ENVIRONMENT"],
+        "sdk": SDK_CONTEXT,
+    })
+    return event_id
+
+
+# Intuitive shortcut alias:
+track = track_event
+

fetchnode/apps.py

@@ -0,0 +1,36 @@
+from django.apps import AppConfig
+
+
+class FetchNodeConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "fetchnode"
+    verbose_name = "FetchNode"
+
+    def ready(self):
+        from fetchnode.conf import get_client_settings
+        from fetchnode.api import track_event
+
+        # Ensure settings.fetchnode_track is available if needed by legacy code
+        try:
+            from django.conf import settings
+            setattr(settings, "fetchnode_track", track_event)
+            setattr(settings, "FETCHNODE_TRACK", track_event)
+        except Exception:
+            pass
+
+        config = get_client_settings()
+        if config["ENABLED"] and config["INSTRUMENT_LOGGING"]:
+            from fetchnode.handlers import install_logging_instrumentation
+            install_logging_instrumentation()
+
+        if config["INSTRUMENT_CELERY"]:
+            from fetchnode.celery import install_celery_instrumentation
+            install_celery_instrumentation()
+
+        if config["ENABLED"] and config["INSTRUMENT_EXCEPTHOOK"]:
+            from fetchnode.excepthook import install_excepthook_instrumentation
+            install_excepthook_instrumentation()
+
+
+# Backwards compatibility alias
+FetchNodeClientConfig = FetchNodeConfig

fetchnode/capture.py

@@ -0,0 +1,202 @@
+from contextlib import contextmanager
+from functools import wraps
+import time
+import uuid
+
+from fetchnode.api import capture_exception
+from fetchnode.conf import get_client_settings
+from fetchnode.scrub import scrub_value
+from fetchnode.sender import send_payload
+from fetchnode.utils import utc_now_iso
+
+
+def track_job_execution(
+    *,
+    task_name: str,
+    status: str,
+    duration_ms: float = 0,
+    queue_latency_ms: float = 0,
+    retry_count: int = 0,
+    task_id: str = "",
+    queue: str = "",
+    runtime: str = "generic",
+    trace_id: str = "",
+    parent_trace_id: str = "",
+    properties=None,
+) -> str:
+    config = get_client_settings()
+    event_id = uuid.uuid4().hex
+    if not config["CAPTURE_JOBS"]:
+        return event_id
+    send_payload({
+        "event_id": event_id,
+        "type": "job",
+        "timestamp": utc_now_iso(),
+        "task_id": str(task_id),
+        "task_name": str(task_name),
+        "queue": str(queue),
+        "runtime": str(runtime),
+        "status": str(status),
+        "duration_ms": round(max(0, float(duration_ms)), 2),
+        "queue_latency_ms": round(max(0, float(queue_latency_ms)), 2),
+        "retry_count": max(0, int(retry_count)),
+        "trace_id": trace_id or uuid.uuid4().hex,
+        "parent_trace_id": parent_trace_id,
+        "environment": config["ENVIRONMENT"],
+        "release": config["RELEASE"],
+        "payload": scrub_value(properties or {}, sensitive_keys=config["SENSITIVE_KEYS"]),
+    })
+    return event_id
+
+
+def capture_job_exception(
+    exc: Exception, *, job_name: str, queue: str = "", tags=None, logger_name="", record_execution=True
+) -> None:
+    merged_tags = {"capture_mode": "job", "job_name": job_name}
+    if queue:
+        merged_tags["queue"] = queue
+    if tags:
+        merged_tags.update(tags)
+    capture_exception(exc, tags=merged_tags, logger_name=logger_name or f"jobs.{job_name}")
+    if record_execution:
+        track_job_execution(task_name=job_name, queue=queue, status="failed")
+
+
+def capture_exceptions(*, tags=None, logger_name="", reraise=True):
+    def decorator(func):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            try:
+                return func(*args, **kwargs)
+            except Exception as exc:
+                merged_tags = {"capture_mode": "decorator", "callable": func.__name__}
+                if tags:
+                    merged_tags.update(tags)
+                capture_exception(exc, tags=merged_tags, logger_name=logger_name or func.__module__)
+                if reraise:
+                    raise
+                return None
+
+        return wrapper
+
+    return decorator
+
+
+def capture_job(*, job_name: str, queue: str = "", tags=None, logger_name="", reraise=True):
+    def decorator(func):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            started = time.monotonic()
+            trace_id = uuid.uuid4().hex
+            try:
+                result = func(*args, **kwargs)
+            except Exception as exc:
+                merged_tags = {"capture_mode": "job_decorator", "callable": func.__name__}
+                if tags:
+                    merged_tags.update(tags)
+                capture_job_exception(
+                    exc,
+                    job_name=job_name,
+                    queue=queue,
+                    tags=merged_tags,
+                    logger_name=logger_name or func.__module__,
+                    record_execution=False,
+                )
+                track_job_execution(
+                    task_name=job_name,
+                    queue=queue,
+                    status="failed",
+                    duration_ms=(time.monotonic() - started) * 1000,
+                    runtime="decorator",
+                    trace_id=trace_id,
+                    properties=merged_tags,
+                )
+                if reraise:
+                    raise
+                return None
+            track_job_execution(
+                task_name=job_name,
+                queue=queue,
+                status="succeeded",
+                duration_ms=(time.monotonic() - started) * 1000,
+                runtime="decorator",
+                trace_id=trace_id,
+                properties=tags,
+            )
+            return result
+
+        return wrapper
+
+    return decorator
+
+
+def capture_management_command(*, command_name: str, tags=None, logger_name="management", reraise=True):
+    merged_tags = {"runtime": "management_command", "command": command_name}
+    if tags:
+        merged_tags.update(tags)
+    return capture_context(tags=merged_tags, logger_name=logger_name, reraise=reraise)
+
+
+def capture_django_task(*, task_name: str, queue: str = "", tags=None, reraise=True):
+    """Instrument a Django 6 Tasks backend callable without depending on a backend."""
+    return capture_job(
+        job_name=task_name,
+        queue=queue,
+        tags={"runtime": "django.tasks", **(tags or {})},
+        logger_name=f"django.tasks.{task_name}",
+        reraise=reraise,
+    )
+
+
+@contextmanager
+def capture_job_context(*, job_name: str, queue: str = "", tags=None, logger_name="", reraise=True):
+    started = time.monotonic()
+    trace_id = uuid.uuid4().hex
+    try:
+        yield
+    except Exception as exc:
+        merged_tags = {"capture_mode": "job_context"}
+        if tags:
+            merged_tags.update(tags)
+        capture_job_exception(
+            exc,
+            job_name=job_name,
+            queue=queue,
+            tags=merged_tags,
+            logger_name=logger_name or f"jobs.{job_name}",
+            record_execution=False,
+        )
+        track_job_execution(
+            task_name=job_name,
+            queue=queue,
+            status="failed",
+            duration_ms=(time.monotonic() - started) * 1000,
+            runtime="contextmanager",
+            trace_id=trace_id,
+            properties=merged_tags,
+        )
+        if reraise:
+            raise
+    else:
+        track_job_execution(
+            task_name=job_name,
+            queue=queue,
+            status="succeeded",
+            duration_ms=(time.monotonic() - started) * 1000,
+            runtime="contextmanager",
+            trace_id=trace_id,
+            properties=tags,
+        )
+
+
+@contextmanager
+def capture_context(*, tags=None, logger_name="", reraise=True):
+    try:
+        yield
+    except Exception as exc:
+        merged_tags = {"capture_mode": "contextmanager"}
+        if tags:
+            merged_tags.update(tags)
+        capture_exception(exc, tags=merged_tags, logger_name=logger_name)
+        if reraise:
+            raise