from __future__ import annotations
import json
import platform
import re
import sys
from copy import deepcopy
from dataclasses import asdict
from datetime import datetime, timezone
from itertools import islice
from pathlib import Path
from typing import Any, Dict, Iterable, Optional
import smonitor
from smonitor._diagnostics import CODES as INTERNAL_CODES
from smonitor.config import load_project_config
from smonitor.core.manager import get_manager
_IDENTITY_BUNDLE_MAX_EVENTS = 100
_IDENTITY_BUNDLE_MAX_CODES = 128
_IDENTITY_CODE = re.compile(r"[A-Z][A-Z0-9-]{0,63}\Z")
_IDENTITY_FINGERPRINT = re.compile(r"[0-9a-f]{16}\Z")
_IDENTITY_LEVELS = frozenset({"DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"})
_IDENTITY_OMISSIONS = (
"smonitor_version",
"python",
"argv",
"platform",
"runtime",
"config",
"project_config",
"policy",
"codes",
"internal_codes",
"signals",
"providers",
"report",
"triage",
"redactions",
"event_messages",
"event_source",
"event_extra",
"event_context",
"event_human_summary",
)
def _parse_since(since: Optional[str]) -> Optional[datetime]:
if not since:
return None
try:
return datetime.fromisoformat(since)
except ValueError:
return None
def _redact_path(data: Dict[str, Any], path: str) -> None:
parts = path.split(".")
current: Any = data
for part in parts[:-1]:
if not isinstance(current, dict):
return
current = current.get(part)
if isinstance(current, dict) and parts[-1] in current:
current[parts[-1]] = "***"
def _sanitize_event(
event: Dict[str, Any],
*,
drop_extra: bool,
drop_context: bool,
redact_fields: Iterable[str],
) -> Dict[str, Any]:
sanitized = dict(event)
if drop_extra:
sanitized.pop("extra", None)
if drop_context:
sanitized.pop("context", None)
for field in redact_fields:
_redact_path(sanitized, field)
return sanitized
def _load_bundle(path: str | Path) -> Dict[str, Any]:
return json.loads(Path(path).read_text(encoding="utf-8"))
def _counter_delta(current: Dict[str, int], previous: Dict[str, int]) -> Dict[str, Dict[str, int]]:
keys = sorted(set(current) | set(previous))
delta: Dict[str, Dict[str, int]] = {}
for key in keys:
before = int(previous.get(key, 0))
after = int(current.get(key, 0))
delta[key] = {"before": before, "after": after, "delta": after - before}
return delta
def compare_bundles(current_path: str | Path, previous_path: str | Path) -> Dict[str, Any]:
current = _load_bundle(current_path)
previous = _load_bundle(previous_path)
current_triage = current.get("triage", {}) or {}
previous_triage = previous.get("triage", {}) or {}
current_fp = current_triage.get("events_by_fingerprint", {}) or {}
previous_fp = previous_triage.get("events_by_fingerprint", {}) or {}
current_codes = current_triage.get("events_by_code", {}) or {}
previous_codes = previous_triage.get("events_by_code", {}) or {}
current_fp_keys = set(current_fp)
previous_fp_keys = set(previous_fp)
return {
"current_bundle": str(current_path),
"previous_bundle": str(previous_path),
"new_fingerprints": sorted(current_fp_keys - previous_fp_keys),
"disappeared_fingerprints": sorted(previous_fp_keys - current_fp_keys),
"recurrent_fingerprints": sorted(current_fp_keys & previous_fp_keys),
"fingerprint_delta": _counter_delta(current_fp, previous_fp),
"code_delta": _counter_delta(current_codes, previous_codes),
"slow_signal_delta": {
"before": len(previous_triage.get("slow_signals_recent", []) or []),
"after": len(current_triage.get("slow_signals_recent", []) or []),
"delta": len(current_triage.get("slow_signals_recent", []) or [])
- len(previous_triage.get("slow_signals_recent", []) or []),
},
}
def format_bundle_comparison_markdown(diff: Dict[str, Any]) -> str:
lines = [
"# SMonitor Bundle Comparison",
"",
f"- current: `{diff['current_bundle']}`",
f"- previous: `{diff['previous_bundle']}`",
"",
"## Fingerprints",
f"- new: {len(diff['new_fingerprints'])}",
f"- disappeared: {len(diff['disappeared_fingerprints'])}",
f"- recurrent: {len(diff['recurrent_fingerprints'])}",
"",
"## Code delta",
]
changed = False
for key, payload in diff.get("code_delta", {}).items():
if payload["delta"] == 0:
continue
changed = True
lines.append(
f"- `{key}`: {payload['before']} -> {payload['after']} ({payload['delta']:+d})"
)
if not changed:
lines.append("- no code-count changes")
lines.extend(
[
"",
"## Slow-signal delta",
(
f"- {diff['slow_signal_delta']['before']} -> {diff['slow_signal_delta']['after']} "
f"({diff['slow_signal_delta']['delta']:+d})"
),
]
)
return "\n".join(lines)
[docs]
def collect_bundle(
*,
project_config: Optional[Dict[str, Any]] = None,
include_events: bool = True,
max_events: Optional[int] = None,
since: Optional[str] = None,
drop_extra: bool = False,
drop_context: bool = False,
redact_fields: Optional[Iterable[str]] = None,
) -> Dict[str, Any]:
manager = get_manager()
manager.flush_coalesced_warnings()
manager.flush_duplicate_summaries()
cfg = asdict(manager.config)
report = manager.report()
since_dt = _parse_since(since)
redact_fields = redact_fields or []
events = manager.recent_events(max_events) if include_events else []
if since_dt:
filtered = []
for event in events:
timestamp = event.get("timestamp")
try:
evt_dt = datetime.fromisoformat(timestamp) if isinstance(timestamp, str) else None
except ValueError:
evt_dt = None
if evt_dt and evt_dt >= since_dt:
filtered.append(event)
events = filtered
if include_events:
events = [
_sanitize_event(
event,
drop_extra=drop_extra,
drop_context=drop_context,
redact_fields=redact_fields,
)
for event in events
]
data = {
"generated_at": datetime.now(timezone.utc).isoformat(),
"smonitor_version": getattr(smonitor, "__version__", "0.0.0+unknown"),
"python": {
"version": platform.python_version(),
"implementation": platform.python_implementation(),
},
"platform": {
"system": platform.system(),
"release": platform.release(),
"machine": platform.machine(),
},
"argv": list(sys.argv),
"runtime": manager.get_runtime_identifiers(),
"config": cfg,
"policy": {
"routes": manager._policy.get_routes(),
"filters": manager._policy.get_filters(),
},
"codes": manager.get_codes(),
"internal_codes": deepcopy(INTERNAL_CODES),
"signals": manager.get_signals(),
"providers": {
identity: {
"package_root": record["package_root"],
"codes": sorted(record["codes"]),
"signals": sorted(record["signals"]),
}
for identity, record in manager.get_providers().items()
},
"report": report,
"triage": {
"events_by_code": report.get("events_by_code", {}),
"events_by_category": report.get("events_by_category", {}),
"events_by_fingerprint": report.get("events_by_fingerprint", {}),
"events_by_source": report.get("events_by_source", {}),
"events_by_resource": report.get("events_by_resource", {}),
"slow_signals_recent": report.get("slow_signals_recent", []),
"coalesced_warnings": report.get("coalesced_warnings", []),
"duplicate_summaries": report.get("duplicate_summaries", []),
"top_codes": report.get("top_codes", []),
"top_sources": report.get("top_sources", []),
"top_fingerprints": report.get("top_fingerprints", []),
"most_noisy_resources": report.get("most_noisy_resources", []),
"most_expensive_entries": report.get("most_expensive_entries", []),
"most_expensive_tags": report.get("most_expensive_tags", []),
"blocking_incidents": report.get("blocking_incidents", []),
"actionable_incidents": report.get("actionable_incidents", []),
"recurrent_incidents": report.get("recurrent_incidents", []),
},
"events": events,
"redactions": {
"drop_extra": drop_extra,
"drop_context": drop_context,
"redact_fields": list(redact_fields),
"since": since,
},
}
if project_config is not None:
data["project_config"] = project_config
return data
[docs]
def collect_identity_bundle(
*, max_events: int = _IDENTITY_BUNDLE_MAX_EVENTS, allowed_codes: Iterable[str] = ()
) -> Dict[str, Any]:
"""Collect a bounded, nonemitting snapshot of retained event identities.
This is an opt-in narrow support artifact, not a redaction of a rich bundle.
Only caller-approved code identifiers may appear as strings from events.
Retention, filtering, and pending summaries can make history incomplete.
"""
if type(max_events) is not int or max_events < 0 or type(allowed_codes) is str:
raise ValueError(INTERNAL_CODES["SMONITOR-BUNDLE-SELECTION-INVALID"]["message"])
try:
codes = list(islice(allowed_codes, _IDENTITY_BUNDLE_MAX_CODES + 1))
except TypeError as exc:
raise ValueError(INTERNAL_CODES["SMONITOR-BUNDLE-SELECTION-INVALID"]["message"]) from exc
if len(codes) > _IDENTITY_BUNDLE_MAX_CODES or any(
type(code) is not str or _IDENTITY_CODE.fullmatch(code) is None for code in codes
):
raise ValueError(INTERNAL_CODES["SMONITOR-BUNDLE-SELECTION-INVALID"]["message"])
approved = set(codes)
retained = get_manager().recent_events()
limit = min(max_events, _IDENTITY_BUNDLE_MAX_EVENTS)
selected = retained[-limit:] if limit else []
events = []
for event in selected:
level = event.get("level")
fingerprint = event.get("fingerprint")
code = event.get("code")
events.append(
{
"level": level if type(level) is str and level in _IDENTITY_LEVELS else None,
"fingerprint": (
fingerprint
if type(fingerprint) is str and _IDENTITY_FINGERPRINT.fullmatch(fingerprint)
else None
),
"code": code if type(code) is str and code in approved else None,
}
)
return {
"schema": "smonitor.identity-bundle@1",
"generated_at": datetime.now(timezone.utc).isoformat(),
"producer": "smonitor",
"coverage": {
"retained_events": len(retained),
"selected_events": len(events),
"limit": limit,
"omitted_before_selection": len(retained) - len(events),
"codes_omitted": sum(event["code"] is None for event in events),
"history_complete": False,
"pending_summaries_flushed": False,
},
"events": events,
"omitted": list(_IDENTITY_OMISSIONS),
}
[docs]
def export_identity_bundle(
path: str | Path,
*,
max_events: int = _IDENTITY_BUNDLE_MAX_EVENTS,
allowed_codes: Iterable[str] = (),
force: bool = False,
) -> Path:
"""Write one identity bundle JSON file without loading project configuration."""
path = Path(path)
if path.exists() and not force:
raise FileExistsError(path)
bundle = collect_identity_bundle(max_events=max_events, allowed_codes=allowed_codes)
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text(json.dumps(bundle, ensure_ascii=False, indent=2), encoding="utf-8")
return path
def write_bundle(
path: Path,
*,
project_config: Optional[Dict[str, Any]] = None,
include_events: bool = True,
max_events: Optional[int] = None,
since: Optional[str] = None,
drop_extra: bool = False,
drop_context: bool = False,
redact_fields: Optional[Iterable[str]] = None,
force: bool = False,
append_events: bool = False,
) -> Path:
path = Path(path)
if path.suffix in {".json", ".jsonl"}:
if path.exists() and not force:
raise FileExistsError(f"{path} already exists")
bundle = collect_bundle(
project_config=project_config,
include_events=include_events,
max_events=max_events,
since=since,
drop_extra=drop_extra,
drop_context=drop_context,
redact_fields=redact_fields,
)
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text(json.dumps(bundle, ensure_ascii=False, indent=2), encoding="utf-8")
return path
if path.exists() and not force:
raise FileExistsError(f"{path} already exists")
path.mkdir(parents=True, exist_ok=True)
bundle = collect_bundle(
project_config=project_config,
include_events=False,
max_events=max_events,
since=since,
drop_extra=drop_extra,
drop_context=drop_context,
redact_fields=redact_fields,
)
bundle_path = path / "bundle.json"
bundle_path.write_text(json.dumps(bundle, ensure_ascii=False, indent=2), encoding="utf-8")
if include_events:
events = collect_bundle(
project_config=project_config,
include_events=True,
max_events=max_events,
since=since,
drop_extra=drop_extra,
drop_context=drop_context,
redact_fields=redact_fields,
)["events"]
events_path = path / "events.jsonl"
mode = "a" if append_events else "w"
with events_path.open(mode, encoding="utf-8") as fh:
for event in events:
fh.write(json.dumps(event, ensure_ascii=False) + "\n")
return path
[docs]
def export_bundle(
path: str | Path,
*,
include_events: bool = True,
max_events: Optional[int] = None,
since: Optional[str] = None,
drop_extra: bool = False,
drop_context: bool = False,
redact_fields: Optional[Iterable[str]] = None,
force: bool = False,
append_events: bool = False,
config_base: Optional[Path] = None,
) -> Path:
project_config = load_project_config(config_base or Path.cwd())
return write_bundle(
Path(path),
project_config=project_config,
include_events=include_events,
max_events=max_events,
since=since,
drop_extra=drop_extra,
drop_context=drop_context,
redact_fields=redact_fields,
force=force,
append_events=append_events,
)