trigerr-logging 0.4.1__py3-none-any.whl

trigerr_logging/__init__.py

@@ -0,0 +1,568 @@
+"""Shared structured (JSON-line) logging for Trigerr services and the SDK itself.
+
+Kept schema-compatible with the legacy logging module it replaced, apart from
+this docstring and the contextvar names: both write into one Loki, so a query
+written against either has to work against the other. That compatibility is
+pinned by tests/fixtures/envelope.golden.json rather than by convention — the
+same file exists on both sides, and a drift in either fails that side's tests.
+(An earlier "keep the two in sync" comment did not survive contact with
+reality; the fixture is the enforcement.)
+
+Stdlib-only by design: this module is imported by every trigerr-* service repo
+but is also shipped in the pip-installable SDK, so it must not assume any
+platform infrastructure. Where log lines end up (a file, journald, stdout) is
+decided by the caller; a separate log-shipping agent (Grafana Alloy) is
+responsible for getting them into centralized storage.
+
+Every line carries the same identity block (IDENTITY_FIELDS) in the same
+order, blank where unknown, so a consumer can group by repo, host, market or
+environment without knowing which service wrote the line. Domain fields
+(request_id, mode, segment, job, ...) appear only on the repos that have
+those concepts — see _DOMAIN_ORDER.
+
+Usage:
+    from trigerr_logging import get_logger, bind, bound, clear_context
+
+    logger = get_logger("oms", log_file="logs/oms.jsonl",
+                        service="trigerr-oms")
+    bind(request_id=request_id, tenant=tenant)
+    logger.info("order placed", extra={"order_id": order_id})
+
+    with bound(request_id=request_id):
+        place_live_order(...)
+
+`service` names the repo and is passed by each repo's create_logger from its
+own SERVICE constant; `name` is the per-script or per-request logger name and
+appears as `logger`. Set LOG_FORMAT=text for a human-readable formatter
+during local development / tailing; the default is single-line JSON.
+"""
+__version__ = "0.4.1"
+
+import contextvars
+import json
+import logging
+import logging.handlers
+import os
+import re
+import socket
+import sys
+from contextlib import contextmanager
+
+# Keys that are part of the stdlib LogRecord and must not be treated as
+# user-supplied `extra` fields when flattening a record to JSON.
+_STD_RECORD_KEYS = frozenset(logging.makeLogRecord({}).__dict__.keys()) | {"message", "asctime"}
+
+# Bumped when IDENTITY_FIELDS changes. Emitted on every line so a format
+# change stays detectable across a fleet that is mid-rollout — repos and
+# instances pick up a new SDK at different times, and without this a query
+# cannot tell a line that predates the change from one that lost a field.
+SCHEMA_VERSION = "1"
+
+# The identity block: emitted on EVERY line, in this order, blank when
+# unknown. These answer "which repo, which part of it, which host, which
+# market, which environment, and what kind of line" — everything needed to
+# find and group logs without knowing in advance which repo wrote them. A
+# blank here means misconfigured, not "not applicable": every one of these
+# applies to every process.
+#
+# event/status are padded despite being blank on most lines because they are
+# the operational vocabulary — with them guaranteed present, one dashboard
+# panel works unchanged against every service.
+IDENTITY_FIELDS = (
+    "ts", "level", "schema", "service", "component", "env", "host",
+    "tenant", "market", "event", "status", "logger", "message",
+)
+
+# Computed from the record itself; never overridable by bind()/extra=.
+_INTRINSIC_FIELDS = frozenset({"ts", "level", "schema", "logger", "message"})
+
+# Distinguishes "key absent" from "key present with a falsy value" when
+# resolving a field: bind(market="") must win over MARKET=IN, the same way
+# bind(market="IN") does.
+_MISSING = object()
+
+# Identity fields that fall back to an environment variable before their
+# blank default. bind()/extra= still win over the environment — a per-request
+# bind(market="IN") must beat a process-wide MARKET=US.
+_ENV_FIELDS = {
+    "service": "SERVICE",
+    "env": "ENVIRONMENT",
+    "host": "HOSTNAME",
+    "tenant": "TENANT",
+    "market": "MARKET",
+}
+
+# Every deployment that ships logs is production; dev is the exception and
+# generally runs LOG_FORMAT=text without shipping at all. Defaulting to ""
+# instead would leave the field blank on every host forever, which is worse
+# than a wrong-but-visible value.
+_DEFAULT_ENV = "prod"
+
+# Domain fields: reserved names with fixed meanings, emitted ONLY when the
+# call site supplies them. Deliberately not blank-padded — a `request_id: ""`
+# on a data-collection line would be indistinguishable from a trading line
+# that failed to populate one, and data collection has no such concept at
+# all. Ordered here purely so output stays readable; anything not listed is
+# still emitted, just afterwards.
+_DOMAIN_ORDER = (
+    # Trading: trading-strategies, backtesting-strategies, orders-api,
+    # brokers-automation. request_id is the Mongo {mode}_requests._id and is
+    # never generated — batch work uses run_id below, so a query for one can
+    # never pick up the other.
+    "request_id", "mode", "strategy", "strategy_id", "user_id",
+    "order_id", "broker", "credential_id", "idempotency_key",
+    # Data collection.
+    "segment", "session", "symbol",
+    # Batch jobs (see jobs.job_run).
+    "job", "run_id", "duration_s",
+    # Long-running processes (see health.HealthReporter).
+    "pid", "uptime_s",
+    "exc",
+)
+
+_LOG_CTX: "contextvars.ContextVar[dict]" = contextvars.ContextVar("trigerr_log_ctx", default=None)
+_CURRENT_LOGGER: "contextvars.ContextVar[logging.Logger]" = contextvars.ContextVar("trigerr_current_logger", default=None)
+
+_loggers_configured = set()
+
+
+def get_current_logger():
+    """Returns the logger most recently passed to redirect_stdout_to() in
+    this context, or None if none has been set yet. Lets shared helper
+    modules that receive no logger argument (e.g. sts_common.py, called from
+    many different per-request scripts) still log at the correct level and
+    with structured extra= fields into whichever logger the caller is
+    currently using, instead of only being able to print()."""
+    return _CURRENT_LOGGER.get()
+
+
+# --------------------------------------------------------------------------
+# Context propagation
+# --------------------------------------------------------------------------
+
+def bind(**ctx):
+    """Merge keys into the current logging context (copy-on-write). None
+    values are dropped so callers can pass optional fields unconditionally,
+    e.g. bind(request_id=maybe_none)."""
+    current = dict(_LOG_CTX.get() or {})
+    for k, v in ctx.items():
+        if v is not None:
+            current[k] = v
+    _LOG_CTX.set(current)
+
+
+def clear_context():
+    """Reset the logging context to empty. Call at the start of each unit of
+    work (Celery task, HTTP request) so context never leaks across tasks
+    sharing a worker/thread — critical for `mode` (paper vs. real-money),
+    which must never bleed from one request's log lines into another's."""
+    _LOG_CTX.set({})
+
+
+def get_context():
+    """Read-only copy of the current logging context."""
+    return dict(_LOG_CTX.get() or {})
+
+
+@contextmanager
+def bound(**ctx):
+    """Bind keys for the duration of a with-block, restoring the prior
+    context on exit (including on exception)."""
+    token_ctx = dict(_LOG_CTX.get() or {})
+    bind(**ctx)
+    try:
+        yield
+    finally:
+        _LOG_CTX.set(token_ctx)
+
+
+# --------------------------------------------------------------------------
+# Scrubbing
+# --------------------------------------------------------------------------
+
+REDACT_KEYS = frozenset({
+    "api_key", "apikey", "x_api_key", "x-api-key", "api_secret",
+    "access_token", "refresh_token", "session_token", "session_token_key",
+    "auth_token", "token", "request_token",
+    "password", "passwd", "pin", "totp", "secret", "client_secret",
+    "authorization", "jwt", "aws_secret_access_key", "s3_access_secret",
+    "s3_secret", "private_key",
+})
+
+_REDACTED = "[REDACTED]"
+
+
+def _normalize_key(key):
+    return str(key).strip().lower().replace("-", "_")
+
+
+def _scrub_value(value, depth):
+    if depth <= 0:
+        return value
+    if isinstance(value, dict):
+        out = {}
+        for k, v in value.items():
+            if _normalize_key(k) in REDACT_KEYS:
+                out[k] = _REDACTED
+            else:
+                out[k] = _scrub_value(v, depth - 1)
+        return out
+    if isinstance(value, (list, tuple)):
+        return [_scrub_value(v, depth - 1) for v in value]
+    return value
+
+
+# Matches key=value, 'key': 'value', "key": "value" style occurrences of a
+# redacted key inside a formatted message string, e.g. an f-string dump of a
+# request dict. Value is any run of non-comma/non-brace/non-quote characters,
+# or a quoted string.
+_MSG_KEY_PATTERN = re.compile(
+    r"""(?P<prefix>['"]?\b(?:%s)\b['"]?\s*[:=]\s*)(?P<value>'[^']*'|"[^"]*"|[^,}\]\s]+)"""
+    % "|".join(re.escape(k) for k in sorted(REDACT_KEYS, key=len, reverse=True)),
+    re.IGNORECASE,
+)
+
+
+def _scrub_message(message):
+    return _MSG_KEY_PATTERN.sub(lambda m: m.group("prefix") + _REDACTED, message)
+
+
+class ScrubFilter(logging.Filter):
+    """Redacts credential-shaped values from both the rendered message and
+    any extra/context fields before a record is formatted. Defense-in-depth
+    only — call sites that handle real credentials must still avoid logging
+    them in the first place."""
+
+    def filter(self, record):
+        try:
+            record.msg = _scrub_message(record.getMessage())
+            record.args = None
+        except Exception:
+            pass
+        for key in list(record.__dict__.keys()):
+            if key in _STD_RECORD_KEYS:
+                continue
+            if _normalize_key(key) in REDACT_KEYS:
+                setattr(record, key, _REDACTED)
+            else:
+                setattr(record, key, _scrub_value(getattr(record, key), depth=4))
+        return True
+
+
+# --------------------------------------------------------------------------
+# Formatting
+# --------------------------------------------------------------------------
+
+def _format_time_iso(record):
+    import datetime
+    dt = datetime.datetime.fromtimestamp(record.created, tz=datetime.timezone.utc)
+    return dt.strftime("%Y-%m-%dT%H:%M:%S.") + f"{dt.microsecond // 1000:03d}Z"
+
+
+class JsonFormatter(logging.Formatter):
+    """Renders a record as the identity block (always, in a fixed order,
+    blank when unknown) followed by whatever domain fields the call site
+    supplied.
+
+    The identity block is what makes one Alloy config and one dashboard
+    panel work across every repo: a consumer can rely on those keys being
+    present without knowing which service wrote the line. Domain fields are
+    not padded — see _DOMAIN_ORDER."""
+
+    def __init__(self, service, defaults=None):
+        super().__init__()
+        self.service = service
+        # Per-logger identity values, e.g. {"segment": "options",
+        # "component": "stream_ticks.py"}. Held on the formatter rather than
+        # bound into the context on purpose: a new thread starts with an
+        # EMPTY contextvar context, and the data-collection repos run their
+        # tick handlers and processor workers on their own threads — a
+        # bind() in the main thread would silently vanish from exactly the
+        # lines that carry the data. A formatter attribute is read-only and
+        # shared, so every thread sees it.
+        self.defaults = dict(defaults or {})
+
+    def _identity_default(self, field, record):
+        if field == "ts":
+            return _format_time_iso(record)
+        if field == "level":
+            return record.levelname
+        if field == "schema":
+            return SCHEMA_VERSION
+        if field == "logger":
+            return record.name
+        if field == "message":
+            return record.getMessage()
+        # Below extra=/bind() (a per-line value must still win) but above the
+        # environment: a per-logger default is more specific than a
+        # process-wide env var.
+        if field in self.defaults:
+            return self.defaults[field]
+        if field == "service":
+            # The constructor argument is the fallback, not the authority:
+            # bind(service=...) and SERVICE both outrank it, handled by the
+            # precedence chain in format().
+            return self.service or ""
+        if field == "host":
+            # HOSTNAME is a shell variable and is frequently not exported to
+            # a Python process, so falling back to the env var alone would
+            # leave this blank on most hosts.
+            return os.environ.get("HOSTNAME") or socket.gethostname()
+        if field == "env":
+            return os.environ.get("ENVIRONMENT") or _DEFAULT_ENV
+        env_var = _ENV_FIELDS.get(field)
+        if env_var:
+            return os.environ.get(env_var) or ""
+        return ""
+
+    def format(self, record):
+        ctx = get_context()
+        extras = {k: v for k, v in record.__dict__.items() if k not in _STD_RECORD_KEYS}
+
+        out = {}
+        for field in IDENTITY_FIELDS:
+            # Consume the key from BOTH sources whichever one wins: the tail
+            # below is built from what's left, and a leftover copy there
+            # would overwrite the identity value via out.update(remaining)
+            # — silently reinstating a stale bound field over the extra=
+            # that was meant to override it for this one line.
+            from_extras = extras.pop(field, _MISSING)
+            from_ctx = ctx.pop(field, _MISSING)
+
+            if field in _INTRINSIC_FIELDS:
+                # Computed from the record; a call site cannot displace it.
+                # (stdlib already rejects extra={"message"/"asctime": ...},
+                # but "level", "logger" and "ts" are not names it guards.)
+                out[field] = self._identity_default(field, record)
+            elif from_extras is not _MISSING:
+                out[field] = from_extras
+            elif from_ctx is not _MISSING:
+                out[field] = from_ctx
+            else:
+                out[field] = self._identity_default(field, record)
+
+        if record.exc_info:
+            extras["exc"] = self.formatException(record.exc_info)
+
+        remaining = dict(ctx)
+        remaining.update(extras)
+
+        # Formatter defaults for non-identity fields (segment, ...). Blank
+        # ones are skipped rather than emitted: domain fields are never
+        # padded, so a top-level script with no segment must have no segment
+        # key at all, not segment="".
+        for key, value in self.defaults.items():
+            if key not in out and key not in remaining and value not in ("", None):
+                remaining[key] = value
+
+        for field in _DOMAIN_ORDER:
+            if field in remaining:
+                out[field] = remaining.pop(field)
+
+        # Free-form tail: anything the call site passed that isn't a reserved
+        # name. Emitted unchanged so per-strategy payloads keep working.
+        out.update(remaining)
+
+        return json.dumps(out, default=str)
+
+
+class TextFormatter(logging.Formatter):
+    """Human-readable formatter for local dev / `tail -f` — selected via
+    LOG_FORMAT=text. Bound context (request_id, mode, strategy, ...) is
+    appended so it stays visible without parsing JSON."""
+
+    def __init__(self):
+        super().__init__(fmt="%(asctime)s  %(levelname)-8s  %(name)s  %(message)s",
+                         datefmt="%Y-%m-%d %H:%M:%S")
+
+    def format(self, record):
+        base = super().format(record)
+        ctx = get_context()
+        if ctx:
+            ctx_str = " ".join(f"{k}={v}" for k, v in ctx.items())
+            base = f"{base}  [{ctx_str}]"
+        if record.exc_info:
+            base = f"{base}\n{self.formatException(record.exc_info)}"
+        return base
+
+
+def _make_formatter(service, defaults=None):
+    if os.environ.get("LOG_FORMAT", "json").lower() == "text":
+        return TextFormatter()
+    return JsonFormatter(service, defaults=defaults)
+
+
+# --------------------------------------------------------------------------
+# Logger factory
+# --------------------------------------------------------------------------
+
+def get_logger(name=None, log_file=None, stream=True, level=logging.INFO,
+               rotate_when="midnight", backup_count=14, service=None,
+               defaults=None):
+    """Return a logger named `name` configured to emit structured log lines.
+    Safe to call more than once for the same name — handlers are only
+    attached the first time.
+
+    name: the logger name, which appears as `logger` on every line. Callers
+        pass a per-script or per-request value here (e.g.
+        "syss_sha_eod-vt-<request_id>"). Defaults to `service` so the
+        pre-split call style — get_logger(service="oms", ...), used across
+        project-trigerr — keeps working unchanged.
+    service: which repo the line came from, e.g. "trigerr-data-collection".
+        Falls back to the SERVICE environment variable, then to `name`.
+        These were previously the same argument, so every line reported a
+        per-request logger name as its service and no query could group by
+        repo; each repo's create_logger now passes its own SERVICE constant.
+    defaults: identity fields every line from this logger should carry, e.g.
+        {"segment": "options", "component": "stream_ticks.py"}. Use this
+        rather than bind() for values fixed at logger-creation time in a
+        process that spawns threads: a new thread starts with an empty
+        contextvar context, so a bind() in the main thread never reaches the
+        worker that does the logging.
+    log_file: path to a rotating log file (created, including parent dirs).
+    stream: also emit to sys.__stderr__ (not sys.stderr — under Celery,
+        stdout/stderr are wrapped by a LoggingProxy, and if this handler's
+        output were itself redirected back into logging via
+        redirect_stdout_to() below, writing to the wrapped stream would
+        recurse infinitely).
+    """
+    name = name or service
+    if not name:
+        raise TypeError("get_logger() needs a name (or a service to name the logger after)")
+
+    logger = logging.getLogger(name)
+    logger.setLevel(level)
+    logger.propagate = False
+
+    if name in _loggers_configured:
+        return logger
+    _loggers_configured.add(name)
+
+    formatter = _make_formatter(service or os.environ.get("SERVICE") or name,
+                                defaults=defaults)
+    scrub = ScrubFilter()
+
+    if log_file:
+        os.makedirs(os.path.dirname(log_file) or ".", exist_ok=True)
+        file_handler = logging.handlers.TimedRotatingFileHandler(
+            log_file, when=rotate_when, backupCount=backup_count, utc=True)
+        file_handler.setFormatter(formatter)
+        file_handler.addFilter(scrub)
+        logger.addHandler(file_handler)
+
+    if stream:
+        stream_handler = logging.StreamHandler(sys.__stderr__)
+        stream_handler.setFormatter(formatter)
+        stream_handler.addFilter(scrub)
+        logger.addHandler(stream_handler)
+
+    return logger
+
+
+class _StdoutToLogger:
+    """File-like shim: routes writes to a logger, dropping whitespace-only
+    writes (print() always emits a trailing '\\n' as a separate write)."""
+
+    def __init__(self, logger, level=logging.INFO):
+        self._logger = logger
+        self._level = level
+
+    def write(self, message):
+        text = message.strip()
+        if text:
+            self._logger.log(self._level, text)
+
+    def flush(self):
+        pass
+
+    def isatty(self):
+        # Never a real terminal; libraries that probe this before deciding
+        # whether to color their output must get a real bool, not an
+        # AttributeError.
+        return False
+
+
+def redirect_stdout_to(logger, level=logging.INFO):
+    """Route sys.stdout.write() to the given logger, so existing print()
+    call sites are captured without editing them. Replaces the
+    `sys.stdout.write = logger.info` pattern used previously, which also
+    logged a blank record for every bare print()'s trailing newline."""
+    sys.stdout = _StdoutToLogger(logger, level=level)
+    _CURRENT_LOGGER.set(logger)
+
+
+def resolve_log_file(file_name, service, default_log_dir):
+    """LOG_DIR env var (falling back to default_log_dir) + service
+    subdirectory + the caller's basename only. Log files always land in one
+    directory this way — without it a log is written wherever the caller
+    pointed, which Alloy does not tail, so the service looks healthy while
+    its logs reach nothing."""
+    log_dir = os.environ.get("LOG_DIR") or default_log_dir
+    return os.path.join(log_dir, service, os.path.basename(file_name))
+
+
+def resolve_segmented_log_file(file_name, service, default_log_dir, repo_root):
+    """Data-collection variant of resolve_log_file(): several repos run the
+    same script name (stream_ticks.py) under multiple segment directories
+    (options/, futures/, stocks/, indices/), which would collide on one
+    flattened basename. Returns (log_file_path, segment, component) —
+    segment/component are meant to be passed as the formatter's defaults=,
+    since the filename that carried them is gone once Alloy tails the file
+    into Loki. file_name is expected in the form
+    f"{cwd}/logs/{name}.log", where cwd is the segment directory or the
+    repo root for top-level scripts."""
+    log_dir = os.environ.get("LOG_DIR") or default_log_dir
+    base = os.path.basename(file_name)
+    segment_dir = os.path.dirname(os.path.dirname(os.path.abspath(file_name)))
+    segment = "" if segment_dir == repo_root else os.path.basename(segment_dir)
+    stem = base[:-4] if base.endswith(".log") else base
+    component = f"{stem.split('-')[0]}.py"
+    if segment:
+        base = f"{segment}_{base}"
+    return os.path.join(log_dir, service, base), segment, component
+
+
+def resolve_log_level(default=logging.INFO):
+    """LOG_LEVEL env var (DEBUG/INFO/WARNING/ERROR/CRITICAL), resolved to a
+    logging constant. Unset or unrecognized falls back to `default`."""
+    name = os.environ.get("LOG_LEVEL", "").upper()
+    if not name:
+        return default
+    level = getattr(logging, name, None)
+    if isinstance(level, int) and not isinstance(level, bool):
+        return level
+    return default
+
+
+_service_name_warned = set()
+
+
+def check_service_name_drift(service, logger):
+    """Warn once if SERVICE_NAME disagrees with the repo's hardcoded SERVICE constant."""
+    env_value = os.environ.get("SERVICE_NAME")
+    if env_value and env_value != service and service not in _service_name_warned:
+        _service_name_warned.add(service)
+        logger.warning(
+            "SERVICE_NAME env var disagrees with this repo's SERVICE constant "
+            "— SERVICE_NAME is documentation only and is ignored; fix .env or "
+            "the constant so they agree",
+            extra={"service_name_env": env_value, "service": service},
+        )
+
+
+def create_service_logger(file_name, name, service, default_log_dir, stream=False,
+                          default_level=logging.INFO, defaults=None,
+                          rotate_when="midnight", backup_count=14):
+    """One-call replacement for resolve_log_file + resolve_log_level + get_logger."""
+    log_file = resolve_log_file(file_name, service, default_log_dir)
+    level = resolve_log_level(default=default_level)
+    logger = get_logger(name, log_file=log_file, stream=stream, level=level,
+                        service=service, defaults=defaults,
+                        rotate_when=rotate_when, backup_count=backup_count)
+    check_service_name_drift(service, logger)
+    return logger
+
+
+from trigerr_logging.health import HealthReporter
+from trigerr_logging.jobs import job_run, new_run_id
+

trigerr_logging/health.py

@@ -0,0 +1,251 @@
+"""Health reporting and heartbeat emitter for Trigerr data collection processes.
+
+Provides HealthReporter: a thread-safe counter bag and background daemon thread
+that periodically emits structured heartbeat events to Loki/Grafana.
+"""
+import atexit
+import os
+import signal
+import threading
+import time
+
+
+class HealthReporter:
+    """Emits process_start / heartbeat / process_stop for a long-running collector.
+
+    Holds its logger directly and guards counters with a Lock: the emitter runs on
+    its own daemon thread and callers bump counters from websocket/worker threads,
+    where contextvars are empty and a contextvar-based logger lookup returns None.
+    """
+
+    def __init__(self, logger, component, segment, interval_s=60,
+                 session_fn=None, stall_after_s=None):
+        self.logger = logger
+        self.component = component
+        self.segment = segment
+        self.interval_s = interval_s
+        self.session_fn = session_fn
+        self.stall_after_s = stall_after_s
+
+        self._lock = threading.Lock()
+        self._running = False
+        self._stopped = False
+        self._thread = None
+        self._start_time = None
+        self._last_activity_time = None
+        self._last_tick_time = None
+        self._last_message_time = None
+        self._last_candle_time = None
+
+        # Per-interval counters (reset on heartbeat)
+        self._ticks = 0
+        self._messages = 0
+        self._candles = 0
+        self._errors = 0
+        self._reconnects = 0
+        self._zero_sub_publishes = 0
+
+        # Persistent gauges
+        self._gauges = {}
+
+    def start(self):
+        with self._lock:
+            if self._running:
+                return
+            self._running = True
+            now = time.time()
+            self._start_time = now
+            self._last_activity_time = now
+            self._last_tick_time = now
+            self._last_message_time = now
+            self._last_candle_time = now
+
+        pid = os.getpid()
+        market = os.environ.get("MARKET")
+        extra = {
+            "event": "process_start",
+            "component": self.component,
+            "segment": self.segment,
+            "pid": pid,
+        }
+        if market:
+            extra["market"] = market
+
+        self.logger.info("process starting", extra=extra)
+
+        self._thread = threading.Thread(target=self._run_loop, name="health-reporter", daemon=True)
+        self._thread.start()
+
+        atexit.register(self._atexit_cleanup)
+        self._install_signal_handler()
+
+    def _atexit_cleanup(self):
+        self.stop(reason="shutdown")
+
+    def _install_signal_handler(self):
+        """ atexit alone does not run on SIGTERM — only on normal interpreter
+        exit or an unhandled exception in the main thread — so a plain
+        `kill <pid>` (the usual way these long-running collectors are
+        stopped) would otherwise leave no process_stop record. Chains to
+        whatever handler was previously installed so other shutdown logic
+        still runs. """
+        try:
+            previous = signal.getsignal(signal.SIGTERM)
+
+            def _handler(signum, frame):
+                self.stop(reason="sigterm")
+                if callable(previous) and previous not in (signal.SIG_DFL, signal.SIG_IGN):
+                    previous(signum, frame)
+                else:
+                    raise SystemExit(0)
+
+            signal.signal(signal.SIGTERM, _handler)
+        except (ValueError, OSError):
+            # signal.signal() only works in the main thread — skip silently
+            # elsewhere rather than crashing the caller's startup path.
+            pass
+
+    def mark_tick(self, n=1):
+        now = time.time()
+        with self._lock:
+            self._ticks += n
+            self._last_tick_time = now
+            self._last_activity_time = now
+
+    def mark_message(self, n=1):
+        now = time.time()
+        with self._lock:
+            self._messages += n
+            self._last_message_time = now
+            self._last_activity_time = now
+
+    def mark_candle(self, n=1):
+        """ Called by processors (process_ticks.py etc.) when a candle is
+        completed and written. Counts as activity for stall detection the
+        same way mark_tick()/mark_message() do — a processor that only
+        produces candles would otherwise never refresh
+        last_activity_time and would eventually report stalled=True even
+        while working correctly. """
+        now = time.time()
+        with self._lock:
+            self._candles += n
+            self._last_candle_time = now
+            self._last_activity_time = now
+
+    def mark_error(self, n=1):
+        with self._lock:
+            self._errors += n
+
+    def mark_reconnect(self):
+        with self._lock:
+            self._reconnects += 1
+
+    def mark_zero_subscribers(self):
+        with self._lock:
+            self._zero_sub_publishes += 1
+
+    def set_gauge(self, name, value):
+        with self._lock:
+            self._gauges[name] = value
+
+    def _run_loop(self):
+        while self._running:
+            time.sleep(self.interval_s)
+            if self._running:
+                self._emit_heartbeat()
+
+    def _emit_heartbeat(self):
+        now = time.time()
+        with self._lock:
+            ticks = self._ticks
+            messages = self._messages
+            candles = self._candles
+            errors = self._errors
+            reconnects = self._reconnects
+            zero_subs = self._zero_sub_publishes
+            gauges = dict(self._gauges)
+
+            # Reset per-interval counters
+            self._ticks = 0
+            self._messages = 0
+            self._candles = 0
+            self._errors = 0
+            self._reconnects = 0
+            self._zero_sub_publishes = 0
+
+            start_time = self._start_time
+            last_activity = self._last_activity_time
+            last_tick_time = self._last_tick_time
+            last_message_time = self._last_message_time
+            last_candle_time = self._last_candle_time
+
+        uptime_s = int(now - start_time) if start_time else 0
+        last_activity_age_s = round(now - last_activity, 1) if last_activity else 0.0
+
+        session = "unknown"
+        if self.session_fn:
+            try:
+                session = self.session_fn() or "unknown"
+            except Exception:
+                session = "unknown"
+
+        status = "ok"
+        if session == "open" and self.stall_after_s and last_activity_age_s > self.stall_after_s:
+            status = "stalled"
+        elif errors > 0 or reconnects > 0:
+            status = "degraded"
+
+        extra = {
+            "event": "health",
+            "component": self.component,
+            "segment": self.segment,
+            "status": status,
+            "session": session,
+            "uptime_s": uptime_s,
+            "errors": errors,
+        }
+
+        # Include tick or message fields depending on usage
+        if ticks > 0 or last_tick_time != start_time or "symbols_subscribed" in gauges:
+            extra["ticks"] = ticks
+            extra["last_tick_age_s"] = round(now - last_tick_time, 1) if last_tick_time else 0.0
+            extra["reconnects"] = reconnects
+            extra["zero_sub_publishes"] = zero_subs
+
+        if messages > 0 or last_message_time != start_time or "candles_written" in gauges:
+            extra["messages"] = messages
+            extra["last_message_age_s"] = round(now - last_message_time, 1) if last_message_time else 0.0
+
+        if candles > 0 or last_candle_time != start_time:
+            extra["candles"] = candles
+            extra["last_candle_age_s"] = round(now - last_candle_time, 1) if last_candle_time else 0.0
+
+        extra.update(gauges)
+
+        msg = f"heartbeat status={status}"
+        if status != "ok":
+            self.logger.warning(msg, extra=extra)
+        else:
+            self.logger.info(msg, extra=extra)
+
+    def stop(self, reason="shutdown"):
+        with self._lock:
+            if self._stopped:
+                return
+            self._stopped = True
+            self._running = False
+            start_time = self._start_time
+
+        uptime_s = int(time.time() - start_time) if start_time else 0
+        extra = {
+            "event": "process_stop",
+            "component": self.component,
+            "segment": self.segment,
+            "reason": reason,
+            "uptime_s": uptime_s,
+        }
+        market = os.environ.get("MARKET")
+        if market:
+            extra["market"] = market
+
+        self.logger.info("process stopping", extra=extra)

trigerr_logging/jobs.py

@@ -0,0 +1,73 @@
+"""Lifecycle events for batch work — cron jobs, screeners, db/S3 syncs.
+
+Promotes a pattern that was hand-rolled identically in every batch script
+(job_start / job_complete / job_failed emitted around a try/except). Doing it
+in one place means every job emits the same three events with the same field
+names, so "did last night's sync run, and how long did it take" is one query
+regardless of which repo owns the job.
+
+Usage:
+    from trigerr_logging import get_logger, job_run
+
+    logger = get_logger("s3_sync", log_file=..., service="trigerr-data-collection-in")
+
+    with job_run(logger, "s3_sync"):
+        sync_bucket()
+
+A failure re-raises after logging, so a cron job still exits non-zero and
+whatever supervises it still sees the failure.
+"""
+import time
+import uuid
+from contextlib import contextmanager
+
+from trigerr_logging import bound
+
+
+def new_run_id():
+    """Short, time-ordered id for one execution of a batch job.
+
+    Deliberately not called request_id: that name is the Mongo
+    {mode}_requests._id in the trading repos and is never generated. Keeping
+    the two names distinct means a query for one can never pick up the
+    other."""
+    return f"{int(time.time())}-{uuid.uuid4().hex[:8]}"
+
+
+@contextmanager
+def job_run(logger, job, run_id=None, **ctx):
+    """Emit job_start / job_complete / job_failed around a batch job.
+
+    Binds `job` and `run_id` for the duration so every line the job logs in
+    between carries them too — without that, the start and end events are
+    correlated but everything the job actually did is not.
+
+    Restores the prior context on exit (including on failure) so a script
+    running several jobs in sequence doesn't leak one job's id into the
+    next."""
+    run_id = run_id or new_run_id()
+
+    with bound(job=job, run_id=run_id, **ctx):
+        started = time.monotonic()
+        logger.info(f"job started: {job}", extra={"event": "job_start"})
+
+        try:
+            yield run_id
+        except BaseException as exc:
+            # BaseException, not Exception: a job killed by SIGTERM (how
+            # these are usually stopped) raises SystemExit/KeyboardInterrupt,
+            # and those runs would otherwise leave a job_start with no
+            # terminal event — indistinguishable from a job still running.
+            logger.exception(f"job failed: {job}", extra={
+                "event": "job_failed",
+                "status": "failed",
+                "duration_s": round(time.monotonic() - started, 3),
+                "reason": type(exc).__name__,
+            })
+            raise
+        else:
+            logger.info(f"job complete: {job}", extra={
+                "event": "job_complete",
+                "status": "ok",
+                "duration_s": round(time.monotonic() - started, 3),
+            })

trigerr_logging-0.4.1.dist-info/METADATA

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: trigerr-logging
+Version: 0.4.1
+Summary: Structured JSON-line logging for Trigerr services and the Trigerr SDK.
+Author: Anurag Singh Kushwah
+License-Expression: MIT
+Project-URL: Homepage, https://gitlab.com/trigerr/trigerr-logging
+Project-URL: Repository, https://gitlab.com/trigerr/trigerr-logging
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: System :: Logging
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# trigerr-logging
+
+Structured (JSON-line) logging for Trigerr services and SDK.
+
+Extracted from `trigerr/trigerr/logging_utils.py` as a standalone, zero-dependency package matching `sysstra-logging`'s architecture.
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+## Usage
+
+```python
+from trigerr_logging import get_logger, bind, bound, clear_context
+
+logger = get_logger("oms", log_file="logs/oms.jsonl", service="trigerr-oms")
+bind(request_id="req-123", tenant="trigerr")
+logger.info("order placed", extra={"order_id": "ord-456"})
+```

trigerr_logging-0.4.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+trigerr_logging/__init__.py,sha256=2nV9Z_66HOFMImNBYvR8qSnRwvQscgEa9wcCnI_Ghcc,23858
+trigerr_logging/health.py,sha256=XU0kLMi_0ZG33XZaWziFWExqwWCLZBmJW_UhGs3QDRc,8539
+trigerr_logging/jobs.py,sha256=GBBLoZYCTRG4wV1FjkZ7IiYhzRAjW7xt9Ka1kbf0mQc,2797
+trigerr_logging-0.4.1.dist-info/licenses/LICENSE,sha256=xVcn09gavE9240rU0PB6S3eqrHr89eahfhdNhALNju4,1077
+trigerr_logging-0.4.1.dist-info/METADATA,sha256=fGiTryI0gshc2BzvK53dD76-rDYX2MAvv7mgY_aoE1o,1305
+trigerr_logging-0.4.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+trigerr_logging-0.4.1.dist-info/top_level.txt,sha256=A1UWSv3i5BRE9j8haSCXMv_a4ihVEcsoyP-8wEf9VcM,16
+trigerr_logging-0.4.1.dist-info/RECORD,,

trigerr_logging-0.4.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

trigerr_logging-0.4.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anurag Singh Kushwah
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

trigerr_logging-0.4.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+trigerr_logging