synapse/synapse/synapse_rust/logcontext.pyi

# This file is licensed under the Affero General Public License (AGPL) version 3.
#
# Copyright (C) 2026 Element Creations Ltd
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU Affero General Public License as
# published by the Free Software Foundation, either version 3 of the
# License, or (at your option) any later version.
#
# See the GNU Affero General Public License for more details:
# <https://www.gnu.org/licenses/agpl-3.0.html>.

from types import TracebackType
from typing import TYPE_CHECKING, Optional

from synapse.logging.context import ContextRequest

if TYPE_CHECKING:
    from synapse.logging.scopecontextmanager import _LogContextScope

DEBUG_LOGGER_NAME: str
"""Name of the opt-in logger for debugging when the logcontext switches
(`synapse.logging.context.debug`). Shared with the Rust `debug!` target so the
names stay in sync."""

class ContextResourceUsage:
    """Tracks the resources used by a log context.

    The attributes, operators and `repr` format are relied on by Python callers
    (`Measure`, request and background-process metrics, the task scheduler,
    etc). Implemented in Rust so that `set_current_context` can update the
    counters without allocating a Python object each time.
    """

    ru_stime: float
    """System CPU time, in seconds."""
    ru_utime: float
    """User CPU time, in seconds."""
    db_txn_count: int
    """Number of database transactions done."""
    db_txn_duration_sec: float
    """Time spent doing database transactions (excluding scheduling), in seconds."""
    db_sched_duration_sec: float
    """Time spent waiting for a database connection, in seconds."""
    evt_db_fetch_count: int
    """Number of events requested from the database."""

    def __init__(self, copy_from: "Optional[ContextResourceUsage]" = None) -> None:
        """If `copy_from` is given, copy its stats; otherwise start at zero."""

    def copy(self) -> "ContextResourceUsage":
        """Return a copy of this object."""

    def reset(self) -> None:
        """Reset all stats to zero."""

    def __iadd__(self, other: "ContextResourceUsage") -> "ContextResourceUsage":
        """`self += other`, mutating in place."""

    def __isub__(self, other: "ContextResourceUsage") -> "ContextResourceUsage":
        """`self -= other`, mutating in place."""

    def __add__(self, other: "ContextResourceUsage") -> "ContextResourceUsage":
        """`self + other`, returning a new object."""

    def __sub__(self, other: "ContextResourceUsage") -> "ContextResourceUsage":
        """`self - other`, returning a new object."""

class LoggingContext:
    """Additional context for log formatting. Contexts are scoped within a
    "with" block.

    If a parent is given when creating a new context, then:
        - logging fields are copied from the parent to the new context on entry
        - when the new context exits, the cpu usage stats are copied from the
          child to the parent
    """

    # The context that was current when this one was created. None means the
    # sentinel.
    previous_context: Optional[LoggingContext]
    name: str
    server_name: str
    parent_context: "Optional[LoggingContext]"
    main_thread: int
    finished: bool
    request: Optional[ContextRequest]
    # Narrower than the runtime: the setter also accepts None (see the Rust
    # field docs for why), but all in-tree code treats this as str.
    tag: str
    scope: "Optional[_LogContextScope]"

    def __init__(
        self,
        *,
        name: str,
        server_name: str,
        parent_context: "Optional[LoggingContext]" = None,
        request: Optional[ContextRequest] = None,
    ) -> None:
        """
        Args:
            name: Name for the context for logging.
            server_name: The name of the server this context is associated with
                (`config.server.server_name` or `hs.hostname`).
            parent_context: The parent of the new context.
            request: Synapse Request Context object. Useful to associate all the
                logs happening to a given request.
        """

    def __str__(self) -> str: ...
    def __enter__(self) -> "LoggingContext": ...
    def __exit__(
        self,
        type: Optional[type[BaseException]],
        value: Optional[BaseException],
        traceback: Optional[TracebackType],
    ) -> None: ...
    def start(self, rusage: "Optional[tuple[float, float]]") -> None:
        """Record that this logcontext is currently running.

        Should not be called directly: use `set_current_context`.

        Args:
            rusage: The thread CPU usage `(ru_utime, ru_stime)` at the point of
                switching to this context, or None if the platform doesn't
                track it.
        """

    def stop(self, rusage: "Optional[tuple[float, float]]") -> None:
        """Record that this logcontext is no longer running.

        Should not be called directly: use `set_current_context`.

        Args:
            rusage: The thread CPU usage `(ru_utime, ru_stime)` at the point of
                switching away from this context, or None if the platform
                doesn't track it.
        """

    def get_resource_usage(self) -> ContextResourceUsage:
        """Get the resources used by this logcontext so far.

        Returns:
            A *copy* of the object tracking resource usage so far.
        """

    def add_cputime(self, utime_delta: float, stime_delta: float) -> None:
        """Update the CPU time usage of this context (and any parents, recursively)."""

    def add_database_transaction(self, duration_sec: float) -> None:
        """Record the use of a database transaction and how long it took."""

    def add_database_scheduled(self, sched_sec: float) -> None:
        """Record a use of the database pool (the time taken to get a connection)."""

    def record_event_fetch(self, event_count: int) -> None:
        """Record a number of events being fetched from the db."""

def current_context() -> Optional[LoggingContext]:
    """Get the current logging context, or None for the sentinel.

    This is not the Python-facing API.
    `synapse.logging.context.current_context` wraps this and returns
    `SENTINEL_CONTEXT` instead of `None`.
    """

def set_current_context(
    context: Optional[LoggingContext],
) -> Optional[LoggingContext]:
    """Set the current logging context, returning the context that was
    previously current. `None` means the sentinel, in both directions.

    This is not the Python-facing API.
    `synapse.logging.context.set_current_context` wraps this, converting between
    `SENTINEL_CONTEXT` and `None`.
    """