statoss 0.1.0__tar.gz → 0.2.0__tar.gz

statoss-0.1.0/README.md → statoss-0.2.0/PKG-INFO

@@ -1,8 +1,31 @@
+Metadata-Version: 2.4
+Name: statoss
+Version: 0.2.0
+Summary: Error tracking and logs for StatOSS: sentry-sdk with your app's own levels, categories and fields.
+Keywords: statoss,errors,error-tracking,logs,sentry,monitoring
+Author: StatOSS
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Dist: sentry-sdk>=2.35.0,<3
+Requires-Dist: typing-extensions>=4.12
+Requires-Python: >=3.9
+Project-URL: Homepage, https://statoss.com
+Project-URL: Source, https://github.com/kroqdotdev/statoss/tree/main/sdk-python
+Description-Content-Type: text/markdown
+
 # statoss
 
-Error tracking for [StatOSS](https://statoss.com) in Python: a thin layer
-over [`sentry-sdk`](https://pypi.org/project/sentry-sdk/) that adds your
-app's own levels, categories and fields. Python 3.9 or later, sentry-sdk 2.
+Error tracking and logs for [StatOSS](https://statoss.com) in Python: a
+thin layer over [`sentry-sdk`](https://pypi.org/project/sentry-sdk/) that
+adds your app's own levels, categories and fields. Python 3.9 or later,
+sentry-sdk 2.35 or later.
 
 ## Install
 
@@ -84,6 +107,39 @@ statoss.set_category("billing")  # every later event in this scope
   `sentry_sdk.capture_message` may leave it, is sent the same way, after your
   `before_send`.
 
+## Logs
+
+With `enable_logs=True`, `statoss.logger` sends log lines through
+sentry-sdk's logger, which StatOSS's Logs area searches. Without it they
+are dropped.
+
+```python
+statoss.init(dsn=os.environ["STATOSS_DSN"], schema=schema, enable_logs=True)
+
+statoss.logger.info("Order {order_id} paid", order_id=7, attributes={"amount": 12.5})
+statoss.logger.log("payment-failed", "Card declined", attributes={"order_id": 7})
+# level "error", attributes statoss.level=payment-failed, order_id=7
+```
+
+- `trace`, `debug`, `info`, `warning`, `error` and `fatal` take a template
+  and its values as sentry-sdk's do: `"Paid {amount}"` with `amount=12`
+  sends "Paid 12", the template and each value as attributes.
+  `attributes=` adds more.
+- `log(level, template, ...)` takes a level by name: one of the six (`warn`
+  too), a Sentry level, or one of the schema's. A schema level is sent at
+  its range's level (`trace` stays `trace`), with its severity as
+  `sentry.severity_number` when the schema gives one, and its name as the
+  attribute `statoss.level`. A name the schema does not hold is sent as
+  `error` and, with `debug=True`, logged.
+- `client.logger` from `init` takes only the schema's levels when they are
+  typed (see [Typing](#typing)).
+- Lines are sent in batches by sentry-sdk; `statoss.flush()` sends what
+  waits. sentry-sdk's `before_send_log` sees each line, `statoss.level`
+  included.
+- Records of Python's `logging` module at INFO and up go as log lines too
+  with `enable_logs=True`, except on sentry-sdk 2.68.0, where they need
+  `LoggingIntegration(capture_sentry_logs=True)`.
+
 ## The schema
 
 `define_schema` checks everything as StatOSS does and raises `SchemaError`
@@ -139,11 +195,14 @@ client = statoss.init(dsn=os.environ["STATOSS_DSN"], schema=schema)
 
 client.capture_exception(error, level="payment-failed", category="billing")
 client.capture_exception(error, level="payment-faild")  # error: not a LevelName
+client.logger.log("slow-query", "Search took {ms} ms", ms=2400)
+client.logger.log("slow-qeury", "Search took {ms} ms", ms=2400)  # error: not a LevelName
 ```
 
 `init` returns a `statoss.Client[LevelName, CategoryName]` whose
-`capture_exception`, `capture_message` and `set_category` take only those
-names and Sentry's levels. The module functions take any name.
+`capture_exception`, `capture_message`, `set_category` and `logger.log`
+take only those names and Sentry's levels. The module functions and
+`statoss.logger` take any name.
 
 ## Developing
 

statoss-0.1.0/PKG-INFO → statoss-0.2.0/README.md

@@ -1,30 +1,9 @@
-Metadata-Version: 2.4
-Name: statoss
-Version: 0.1.0
-Summary: Error tracking for StatOSS: sentry-sdk with your app's own levels, categories and fields.
-Keywords: statoss,errors,error-tracking,sentry,monitoring
-Author: StatOSS
-License-Expression: MIT
-License-File: LICENSE
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Developers
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Topic :: System :: Monitoring
-Classifier: Typing :: Typed
-Requires-Dist: sentry-sdk>=2.0.0,<3
-Requires-Dist: typing-extensions>=4.12
-Requires-Python: >=3.9
-Project-URL: Homepage, https://statoss.com
-Project-URL: Source, https://github.com/kroqdotdev/statoss/tree/main/sdk-python
-Description-Content-Type: text/markdown
-
 # statoss
 
-Error tracking for [StatOSS](https://statoss.com) in Python: a thin layer
-over [`sentry-sdk`](https://pypi.org/project/sentry-sdk/) that adds your
-app's own levels, categories and fields. Python 3.9 or later, sentry-sdk 2.
+Error tracking and logs for [StatOSS](https://statoss.com) in Python: a
+thin layer over [`sentry-sdk`](https://pypi.org/project/sentry-sdk/) that
+adds your app's own levels, categories and fields. Python 3.9 or later,
+sentry-sdk 2.35 or later.
 
 ## Install
 
@@ -106,6 +85,39 @@ statoss.set_category("billing")  # every later event in this scope
   `sentry_sdk.capture_message` may leave it, is sent the same way, after your
   `before_send`.
 
+## Logs
+
+With `enable_logs=True`, `statoss.logger` sends log lines through
+sentry-sdk's logger, which StatOSS's Logs area searches. Without it they
+are dropped.
+
+```python
+statoss.init(dsn=os.environ["STATOSS_DSN"], schema=schema, enable_logs=True)
+
+statoss.logger.info("Order {order_id} paid", order_id=7, attributes={"amount": 12.5})
+statoss.logger.log("payment-failed", "Card declined", attributes={"order_id": 7})
+# level "error", attributes statoss.level=payment-failed, order_id=7
+```
+
+- `trace`, `debug`, `info`, `warning`, `error` and `fatal` take a template
+  and its values as sentry-sdk's do: `"Paid {amount}"` with `amount=12`
+  sends "Paid 12", the template and each value as attributes.
+  `attributes=` adds more.
+- `log(level, template, ...)` takes a level by name: one of the six (`warn`
+  too), a Sentry level, or one of the schema's. A schema level is sent at
+  its range's level (`trace` stays `trace`), with its severity as
+  `sentry.severity_number` when the schema gives one, and its name as the
+  attribute `statoss.level`. A name the schema does not hold is sent as
+  `error` and, with `debug=True`, logged.
+- `client.logger` from `init` takes only the schema's levels when they are
+  typed (see [Typing](#typing)).
+- Lines are sent in batches by sentry-sdk; `statoss.flush()` sends what
+  waits. sentry-sdk's `before_send_log` sees each line, `statoss.level`
+  included.
+- Records of Python's `logging` module at INFO and up go as log lines too
+  with `enable_logs=True`, except on sentry-sdk 2.68.0, where they need
+  `LoggingIntegration(capture_sentry_logs=True)`.
+
 ## The schema
 
 `define_schema` checks everything as StatOSS does and raises `SchemaError`
@@ -161,11 +173,14 @@ client = statoss.init(dsn=os.environ["STATOSS_DSN"], schema=schema)
 
 client.capture_exception(error, level="payment-failed", category="billing")
 client.capture_exception(error, level="payment-faild")  # error: not a LevelName
+client.logger.log("slow-query", "Search took {ms} ms", ms=2400)
+client.logger.log("slow-qeury", "Search took {ms} ms", ms=2400)  # error: not a LevelName
 ```
 
 `init` returns a `statoss.Client[LevelName, CategoryName]` whose
-`capture_exception`, `capture_message` and `set_category` take only those
-names and Sentry's levels. The module functions take any name.
+`capture_exception`, `capture_message`, `set_category` and `logger.log`
+take only those names and Sentry's levels. The module functions and
+`statoss.logger` take any name.
 
 ## Developing
 

{statoss-0.1.0 → statoss-0.2.0}/pyproject.toml

@@ -1,19 +1,20 @@
 [project]
 name = "statoss"
-version = "0.1.0"
-description = "Error tracking for StatOSS: sentry-sdk with your app's own levels, categories and fields."
+version = "0.2.0"
+description = "Error tracking and logs for StatOSS: sentry-sdk with your app's own levels, categories and fields."
 readme = "README.md"
 license = "MIT"
 license-files = ["LICENSE"]
 requires-python = ">=3.9"
 dependencies = [
-    "sentry-sdk>=2.0.0,<3",
+    "sentry-sdk>=2.35.0,<3",
     "typing-extensions>=4.12",
 ]
 keywords = [
     "statoss",
     "errors",
     "error-tracking",
+    "logs",
     "sentry",
     "monitoring",
 ]

{statoss-0.1.0 → statoss-0.2.0}/pyproject.toml.orig

@@ -1,14 +1,14 @@
 [project]
 name = "statoss"
-version = "0.1.0"
-description = "Error tracking for StatOSS: sentry-sdk with your app's own levels, categories and fields."
+version = "0.2.0"
+description = "Error tracking and logs for StatOSS: sentry-sdk with your app's own levels, categories and fields."
 readme = "README.md"
 license = "MIT"
 license-files = ["LICENSE"]
 authors = [{ name = "StatOSS" }]
 requires-python = ">=3.9"
-dependencies = ["sentry-sdk>=2.0.0,<3", "typing-extensions>=4.12"]
-keywords = ["statoss", "errors", "error-tracking", "sentry", "monitoring"]
+dependencies = ["sentry-sdk>=2.35.0,<3", "typing-extensions>=4.12"]
+keywords = ["statoss", "errors", "error-tracking", "logs", "sentry", "monitoring"]
 classifiers = [
     "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",

{statoss-0.1.0 → statoss-0.2.0}/src/statoss/__init__.py

@@ -1,4 +1,4 @@
-"""Error tracking for StatOSS: sentry-sdk with the app's own levels, categories and fields."""
+"""Error tracking and logs for StatOSS: sentry-sdk with the app's own levels, categories, fields."""
 
 from sentry_sdk import add_breadcrumb, flush, set_context, set_tag, set_user
 
@@ -10,6 +10,8 @@ from ._client import (
     init,
     set_category,
 )
+from ._client import default_logger as logger
+from ._logs import Logger, LogLevel
 from ._schema import (
     CATEGORY_TAG,
     LEVEL_TAG,
@@ -28,7 +30,7 @@ from ._schema import (
     define_schema,
 )
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 
 __all__ = [
     "CATEGORY_TAG",
@@ -40,6 +42,8 @@ __all__ = [
     "FieldValue",
     "Level",
     "Like",
+    "LogLevel",
+    "Logger",
     "Rule",
     "RuleMatch",
     "RuleSubject",
@@ -53,6 +57,7 @@ __all__ = [
     "define_schema",
     "flush",
     "init",
+    "logger",
     "set_category",
     "set_context",
     "set_tag",

{statoss-0.1.0 → statoss-0.2.0}/src/statoss/_client.py

@@ -22,6 +22,7 @@ from typing import (
 
 import sentry_sdk
 
+from ._logs import Logger
 from ._schema import (
     BUILTIN_LEVELS,
     CATEGORY_TAG,
@@ -71,6 +72,8 @@ class Client(Generic[L, C]):
 
     def __init__(self, schema: Optional[Schema[L, C]] = None) -> None:
         self.schema = schema
+        #: Log lines at the schema's levels; sent when init has enable_logs=True.
+        self.logger: Logger[L] = Logger(lambda: self)
 
     def _level(self, level: Optional[str]) -> Tuple[Optional[str], Dict[str, str]]:
         """The Sentry level to send, and the tag naming the app's own level."""
@@ -229,8 +232,9 @@ def init(
 ) -> Client[Any, Any]:
     """sentry_sdk.init, and the capture functions for the schema's levels.
 
-    The options are sentry-sdk's. The DSN is on the app's setup page in
-    StatOSS: https://<key>@ingest.statoss.com/<app number>.
+    The options are sentry-sdk's; enable_logs=True sends log lines. The DSN
+    is on the app's setup page in StatOSS:
+    https://<key>@ingest.statoss.com/<app number>.
     """
     global _current
     client: Client[Any, Any] = Client(schema)
@@ -282,3 +286,7 @@ def capture_message(
 def set_category(category: Optional[str], scope: Optional[sentry_sdk.Scope] = None) -> None:
     """Gives later events a category; None takes it off."""
     _current.set_category(category, scope)
+
+
+default_logger: Logger[str] = Logger(lambda: _current)
+"""Log lines at any level, read against the schema init was given."""

statoss-0.2.0/src/statoss/_logs.py

@@ -0,0 +1,174 @@
+"""Log lines: sentry-sdk's logger, with the app's own levels.
+
+A line at one of the app's own levels is sent at its range's level, with
+its severity when the schema gives one, and its name as the attribute
+statoss.level, as @statoss/sdk sends it (sdk/src/logs.ts).
+"""
+
+from __future__ import annotations
+
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Dict,
+    Generic,
+    Literal,
+    Mapping,
+    Optional,
+    Tuple,
+    Union,
+    get_args,
+)
+
+import sentry_sdk
+from sentry_sdk import logger as sentry_logger
+
+from ._schema import LEVEL_TAG, SEVERITY_RANGES, L, SentryLevel, is_level_name
+
+if TYPE_CHECKING:
+    from ._client import Client
+
+LogLevel = Literal["trace", "debug", "info", "warn", "warning", "error", "fatal"]
+"""The levels of a log line: OpenTelemetry's six ranges, warn also written warning."""
+
+LOG_LEVELS: Tuple[str, ...] = get_args(LogLevel)
+
+#: The range a level name or a schema's `like` is logged at.
+_RANGE: Dict[str, str] = {
+    "trace": "trace",
+    "debug": "debug",
+    "info": "info",
+    "warn": "warning",
+    "warning": "warning",
+    "error": "error",
+    "fatal": "fatal",
+    "critical": "fatal",
+}
+
+#: sentry-sdk's logger function for each range.
+_SEND: Dict[str, Callable[..., None]] = {
+    "trace": sentry_logger.trace,
+    "debug": sentry_logger.debug,
+    "info": sentry_logger.info,
+    "warning": sentry_logger.warning,
+    "error": sentry_logger.error,
+    "fatal": sentry_logger.fatal,
+}
+
+SEVERITY_ATTRIBUTE = "sentry.severity_number"
+
+
+def _first(like: str) -> int:
+    return SEVERITY_RANGES[like][0]
+
+
+def logs_enabled() -> bool:
+    """Whether init turned logs on (enable_logs=True, or in _experiments)."""
+    try:
+        options = sentry_sdk.get_client().options
+    except Exception:
+        return False
+    experiments = options.get("_experiments") or {}
+    return bool(options.get("enable_logs") or experiments.get("enable_logs"))
+
+
+class Logger(Generic[L]):
+    """sentry-sdk's logger, with a schema's levels.
+
+    Templates take named values as sentry-sdk's do:
+    `logger.info("Paid {amount}", amount=12)` sends "Paid 12" with the
+    template and each value as attributes. `attributes=` adds more.
+    Nothing is sent unless init has enable_logs=True.
+    """
+
+    def __init__(self, client: Callable[[], Client[Any, Any]]) -> None:
+        self._client = client
+
+    def trace(
+        self, template: str, /, *, attributes: Optional[Mapping[str, Any]] = None, **params: Any
+    ) -> None:
+        self._send("trace", _first("trace"), None, template, attributes, params)
+
+    def debug(
+        self, template: str, /, *, attributes: Optional[Mapping[str, Any]] = None, **params: Any
+    ) -> None:
+        self._send("debug", _first("debug"), None, template, attributes, params)
+
+    def info(
+        self, template: str, /, *, attributes: Optional[Mapping[str, Any]] = None, **params: Any
+    ) -> None:
+        self._send("info", _first("info"), None, template, attributes, params)
+
+    def warning(
+        self, template: str, /, *, attributes: Optional[Mapping[str, Any]] = None, **params: Any
+    ) -> None:
+        self._send("warning", _first("warning"), None, template, attributes, params)
+
+    def error(
+        self, template: str, /, *, attributes: Optional[Mapping[str, Any]] = None, **params: Any
+    ) -> None:
+        self._send("error", _first("error"), None, template, attributes, params)
+
+    def fatal(
+        self, template: str, /, *, attributes: Optional[Mapping[str, Any]] = None, **params: Any
+    ) -> None:
+        self._send("fatal", _first("fatal"), None, template, attributes, params)
+
+    def log(
+        self,
+        level: Union[L, LogLevel, SentryLevel],
+        template: str,
+        /,
+        *,
+        attributes: Optional[Mapping[str, Any]] = None,
+        **params: Any,
+    ) -> None:
+        """A line at a level by name: one of the six, a Sentry level, or one
+        of the app's own, sent at its range's level with statoss.level."""
+        like, severity, own = self._level(level)
+        self._send(like, severity, own, template, attributes, params)
+
+    def _level(self, level: object) -> Tuple[str, int, Optional[str]]:
+        """The range a line goes at, its severity, and the app's own level."""
+        from ._client import _warn
+
+        if isinstance(level, str) and level in _RANGE:
+            return _RANGE[level], _first(_RANGE[level]), None
+        if not isinstance(level, str) or not is_level_name(level):
+            _warn(
+                "Logged %r as info: use trace, debug, info, warning, error, fatal or a "
+                "level name of 1 to 32 lowercase letters, digits, dots, dashes or underscores.",
+                level,
+            )
+            return "info", _first("info"), None
+        schema = self._client().schema
+        found = schema.levels.get(level) if schema is not None else None
+        like = found.ranks_like if found is not None else None
+        if found is None or like is None:
+            if schema is not None:
+                _warn("Level %r is not in the schema, so the line is logged as error.", level)
+            return "error", _first("error"), level
+        severity = found.severity
+        low, high = SEVERITY_RANGES[like]
+        if severity is None or not low <= severity <= high:
+            severity = low
+        return like, severity, level
+
+    def _send(
+        self,
+        like: str,
+        severity: int,
+        own: Optional[str],
+        template: str,
+        attributes: Optional[Mapping[str, Any]],
+        params: Dict[str, Any],
+    ) -> None:
+        if not logs_enabled():
+            return
+        attrs: Dict[str, Any] = dict(attributes or {})
+        if severity != _first(like):
+            attrs[SEVERITY_ATTRIBUTE] = severity
+        if own is not None:
+            attrs[LEVEL_TAG] = own
+        _SEND[like](template, attributes=attrs, **params)