loki-reader-core 0.0.1__tar.gz → 0.2.0__tar.gz

{loki_reader_core-0.0.1 → loki_reader_core-0.2.0}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: loki-reader-core
-Version: 0.0.1
+Version: 0.2.0
 Summary: Python library for querying Grafana Loki logs via REST API
 Project-URL: Homepage, https://github.com/jmazzahacks/loki-reader-core
 Project-URL: Issues, https://github.com/jmazzahacks/loki-reader-core/issues
-Author-email: Jason Byteforge <jmazzahacks@gmail.com>
+Author-email: Jason Byteforge <jason@mzmail.me>
 License: MIT License
 Keywords: grafana,logging,logs,loki,observability
 Classifier: License :: OSI Approved :: MIT License
@@ -30,7 +30,7 @@ A lightweight Python library for querying Grafana Loki logs via REST API.
 
 ## Installation
 
-From PyPI (coming soon):
+From PyPI:
 
 ```bash
 pip install loki-reader-core
@@ -158,12 +158,6 @@ source bin/activate
 pytest tests/ -v
 ```
 
-### Building and Publishing
-
-```bash
-./build-publish.sh
-```
-
 ## License
 
 MIT

{loki_reader_core-0.0.1 → loki_reader_core-0.2.0}/README.md

@@ -14,7 +14,7 @@ A lightweight Python library for querying Grafana Loki logs via REST API.
 
 ## Installation
 
-From PyPI (coming soon):
+From PyPI:
 
 ```bash
 pip install loki-reader-core
@@ -142,12 +142,6 @@ source bin/activate
 pytest tests/ -v
 ```
 
-### Building and Publishing
-
-```bash
-./build-publish.sh
-```
-
 ## License
 
 MIT

{loki_reader_core-0.0.1 → loki_reader_core-0.2.0}/pyproject.toml

@@ -1,8 +1,8 @@
 [project]
 name = "loki-reader-core"
-version = "0.0.1"
+version = "0.2.0"
 authors = [
-  { name="Jason Byteforge", email="jmazzahacks@gmail.com" },
+  { name="Jason Byteforge", email="jason@mzmail.me" },
 ]
 description = "Python library for querying Grafana Loki logs via REST API"
 keywords = ["loki", "grafana", "logging", "logs", "observability"]

{loki_reader_core-0.0.1 → loki_reader_core-0.2.0}/src/loki_reader_core/__init__.py

@@ -4,14 +4,16 @@ Python library for querying Grafana Loki logs via REST API
 
 from .client import LokiClient
 from .exceptions import LokiAuthError, LokiConnectionError, LokiError, LokiQueryError
-from .models import LogEntry, LogStream, QueryResult, QueryStats
+from .models import LogEntry, LogStream, MetricSample, MetricSeries, QueryResult, QueryStats
 
-__version__ = "0.0.1"
+__version__ = "0.2.0"
 
 __all__ = [
     "LokiClient",
     "LogEntry",
     "LogStream",
+    "MetricSample",
+    "MetricSeries",
     "QueryResult",
     "QueryStats",
     "LokiError",

{loki_reader_core-0.0.1 → loki_reader_core-0.2.0}/src/loki_reader_core/client.py

@@ -8,7 +8,102 @@ import requests
 
 from .exceptions import LokiAuthError, LokiConnectionError, LokiQueryError
 from .models import QueryResult
-from .utils import now_ns
+from .utils import now_ns, NANOSECONDS_PER_MINUTE, NANOSECONDS_PER_HOUR
+
+APP_LABEL_NAMES = ["application", "app", "job", "service", "service_name", "logger"]
+SEVERITY_LABEL_NAMES = ["level", "severity", "log_level", "loglevel"]
+SEVERITY_TIERS = ["trace", "debug", "info", "warn", "warning", "error", "fatal", "critical"]
+
+
+def _is_metric_query(logql: str) -> bool:
+    """Check if a LogQL query is a metric query (vs a log selector).
+
+    Metric queries start with aggregation functions and return numeric
+    results via the instant endpoint. Log selectors return log streams
+    and need the range endpoint.
+
+    Args:
+        logql: LogQL query string.
+
+    Returns:
+        True if the query is a metric/aggregation query.
+    """
+    metric_prefixes = [
+        "count_over_time", "rate", "bytes_over_time", "bytes_rate",
+        "sum", "avg", "min", "max", "stddev", "stdvar",
+        "quantile_over_time", "first_over_time", "last_over_time",
+        "absent_over_time", "rate_counter", "topk", "bottomk",
+        "sort", "sort_desc", "label_replace", "label_join",
+    ]
+    stripped = logql.strip().lower()
+    for prefix in metric_prefixes:
+        if stripped.startswith(prefix + "(") or stripped.startswith(prefix + " ("):
+            return True
+    return False
+
+
+def _build_severity_regex(min_severity: str) -> str:
+    """Build regex matching min_severity and all higher severity tiers.
+
+    Canonical order (low to high): trace, debug, info, warn, error, fatal.
+    Aliases: "warning" maps to "warn", "critical" maps to "fatal".
+
+    Args:
+        min_severity: Minimum severity level to include.
+
+    Returns:
+        Pipe-separated regex string (e.g. "error|fatal|critical").
+
+    Raises:
+        ValueError: If min_severity is not a recognized level.
+    """
+    normalized = min_severity.strip().lower()
+
+    if normalized == "warning":
+        normalized = "warn"
+    if normalized == "critical":
+        normalized = "fatal"
+
+    canonical = ["trace", "debug", "info", "warn", "error", "fatal"]
+    idx = canonical.index(normalized)  # raises ValueError if invalid
+    selected = canonical[idx:]
+
+    expanded = []
+    for level in selected:
+        expanded.append(level)
+        if level == "warn":
+            expanded.append("warning")
+        elif level == "fatal":
+            expanded.append("critical")
+
+    return "|".join(expanded)
+
+
+def _resolve_since(
+    since_minutes: Optional[int],
+    since_hours: Optional[int],
+    since_days: Optional[int],
+) -> Optional[tuple[int, int]]:
+    """Resolve relative time params into a (start_ns, end_ns) tuple.
+
+    Priority: since_minutes > since_hours > since_days.
+
+    Args:
+        since_minutes: Number of minutes to look back.
+        since_hours: Number of hours to look back.
+        since_days: Number of days to look back.
+
+    Returns:
+        Tuple of (start_ns, end_ns) or None if all params are None.
+    """
+    end = now_ns()
+    if since_minutes is not None:
+        return (end - since_minutes * NANOSECONDS_PER_MINUTE, end)
+    if since_hours is not None:
+        return (end - since_hours * NANOSECONDS_PER_HOUR, end)
+    if since_days is not None:
+        return (end - since_days * NANOSECONDS_PER_HOUR * 24, end)
+    return None
 
 
 class LokiClient:
@@ -22,12 +117,7 @@ class LokiClient:
             org_id="tenant-1"
         )
 
-        result = client.query_range(
-            logql='{job="api"} |= "error"',
-            start=hours_ago_ns(1),
-            end=now_ns(),
-            limit=500
-        )
+        result = client.query(app="my-api", severity="error", since_hours=1)
     """
 
     def __init__(
@@ -58,6 +148,8 @@ class LokiClient:
         self.timeout = timeout
 
         self._session: Optional[requests.Session] = None
+        self._app_label_cache: dict[str, str] = {}
+        self._severity_label_cache: Optional[str] = None
 
     @property
     def session(self) -> requests.Session:
@@ -139,33 +231,126 @@ class LokiClient:
 
         return data
 
+    def _find_app_label(self, app_value: str) -> str:
+        """Discover which label name contains the given app value.
+
+        Checks a prioritized list of common label names and returns the
+        first one that contains the app value. Results are cached.
+
+        Args:
+            app_value: Application name to search for.
+
+        Returns:
+            The label name that contains the app value.
+
+        Raises:
+            ValueError: If app_value is not found in any common label.
+        """
+        if app_value in self._app_label_cache:
+            return self._app_label_cache[app_value]
+
+        for label_name in APP_LABEL_NAMES:
+            values = self.get_label_values(label_name)
+            if app_value in values:
+                self._app_label_cache[app_value] = label_name
+                return label_name
+
+        raise ValueError(
+            f"Could not find '{app_value}' in any common label "
+            f"({', '.join(APP_LABEL_NAMES)}). Use logql param for custom labels."
+        )
+
+    def _find_severity_label(self) -> Optional[str]:
+        """Discover which label name is used for severity/level.
+
+        Checks a prioritized list of common severity label names and
+        returns the first one that has values. Result is cached.
+
+        Returns:
+            The severity label name, or None if not found.
+        """
+        if self._severity_label_cache is not None:
+            return self._severity_label_cache
+
+        for label_name in SEVERITY_LABEL_NAMES:
+            values = self.get_label_values(label_name)
+            if values:
+                self._severity_label_cache = label_name
+                return label_name
+
+        return None
+
     def query(
         self,
-        logql: str,
-        time: Optional[int] = None,
-        limit: int = 100
+        logql: Optional[str] = None,
+        app: Optional[str] = None,
+        severity: Optional[str] = None,
+        limit: int = 100,
+        since_minutes: Optional[int] = None,
+        since_hours: Optional[int] = None,
+        since_days: Optional[int] = None,
     ) -> QueryResult:
         """
-        Execute an instant query at a single point in time.
+        Query Loki logs by application name or LogQL expression.
+
+        For app-based queries, auto-discovers the correct label name and
+        builds the LogQL selector. For raw LogQL, passes through directly.
+
+        Metric queries (count_over_time, rate, etc.) use the instant endpoint.
+        All other queries use the range endpoint with a time window.
 
         Args:
-            logql: LogQL query string (e.g., '{job="api"} |= "error"').
-            time: Optional timestamp in nanoseconds. Defaults to now.
+            logql: Raw LogQL query string. Mutually exclusive with app.
+            app: Application name to search for. Auto-discovers the label.
+            severity: Minimum severity level (trace/debug/info/warn/error/fatal).
             limit: Maximum number of entries to return.
+            since_minutes: Look back N minutes from now.
+            since_hours: Look back N hours from now.
+            since_days: Look back N days from now.
 
         Returns:
-            QueryResult containing matching log streams.
-        """
-        params = {
-            "query": logql,
-            "limit": limit
-        }
+            QueryResult containing matching log streams or metric results.
 
-        if time is not None:
-            params["time"] = str(time)
+        Raises:
+            ValueError: If both logql and app are provided, or neither.
+        """
+        if logql is not None and app is not None:
+            raise ValueError("Cannot combine 'logql' with 'app'")
+        if logql is None and app is None:
+            raise ValueError("Must provide either 'logql' or 'app'")
+
+        if app is not None:
+            label_name = self._find_app_label(app)
+            selector = f'{label_name}="{app}"'
+            if severity is not None:
+                sev_label = self._find_severity_label()
+                if sev_label:
+                    regex = _build_severity_regex(severity)
+                    selector += f', {sev_label}=~"{regex}"'
+            logql = "{" + selector + "}"
+
+        has_since = any(
+            p is not None for p in [since_minutes, since_hours, since_days]
+        )
 
-        response = self._request("GET", "/loki/api/v1/query", params)
-        return QueryResult.from_loki_response(response)
+        if _is_metric_query(logql) and not has_since:
+            params = {"query": logql, "limit": limit}
+            response = self._request("GET", "/loki/api/v1/query", params)
+            return QueryResult.from_loki_response(response)
+
+        time_range = _resolve_since(since_minutes, since_hours, since_days)
+        if time_range is None:
+            end = now_ns()
+            start = end - (30 * 24 * NANOSECONDS_PER_HOUR)
+            time_range = (start, end)
+
+        return self.query_range(
+            logql=logql,
+            start=time_range[0],
+            end=time_range[1],
+            limit=limit,
+            direction="backward",
+        )
 
     def query_range(
         self,

loki_reader_core-0.2.0/src/loki_reader_core/models/__init__.py

@@ -0,0 +1,19 @@
+"""
+Data models for loki-reader-core.
+"""
+
+from .log_entry import LogEntry
+from .log_stream import LogStream
+from .metric_sample import MetricSample
+from .metric_series import MetricSeries
+from .query_stats import QueryStats
+from .query_result import QueryResult
+
+__all__ = [
+    "LogEntry",
+    "LogStream",
+    "MetricSample",
+    "MetricSeries",
+    "QueryStats",
+    "QueryResult",
+]

loki_reader_core-0.2.0/src/loki_reader_core/models/metric_sample.py

@@ -0,0 +1,75 @@
+"""
+MetricSample model representing a single numeric datapoint from a Loki metric query.
+"""
+
+from dataclasses import dataclass
+
+import math
+
+from ..utils import NANOSECONDS_PER_SECOND
+
+
+@dataclass
+class MetricSample:
+    """
+    A single metric datapoint from a Loki metric query.
+
+    Attributes:
+        timestamp: Unix timestamp in nanoseconds when the sample was recorded.
+        value: The numeric value of the metric at this timestamp.
+    """
+
+    timestamp: int
+    value: float
+
+    def to_dict(self) -> dict:
+        """
+        Convert to dictionary for serialization.
+
+        Returns:
+            Dictionary with timestamp and value.
+        """
+        return {
+            "timestamp": self.timestamp,
+            "value": self.value
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "MetricSample":
+        """
+        Create MetricSample from dictionary.
+
+        Args:
+            data: Dictionary with timestamp and value keys.
+
+        Returns:
+            MetricSample instance.
+        """
+        return cls(
+            timestamp=int(data["timestamp"]),
+            value=float(data["value"])
+        )
+
+    @classmethod
+    def from_loki_value(cls, value: list) -> "MetricSample":
+        """
+        Create MetricSample from Loki's [timestamp, value] format.
+
+        Loki returns metric values as [unix_seconds_float, "string_value"].
+        The timestamp is in seconds (possibly fractional) and the value is a string.
+
+        Args:
+            value: List of [timestamp_seconds, value_string] from Loki API.
+
+        Returns:
+            MetricSample instance with timestamp converted to nanoseconds.
+        """
+        timestamp_seconds = float(value[0])
+        whole_seconds = math.floor(timestamp_seconds)
+        fractional = timestamp_seconds - whole_seconds
+        timestamp_ns = (whole_seconds * NANOSECONDS_PER_SECOND
+                        + round(fractional * NANOSECONDS_PER_SECOND))
+        return cls(
+            timestamp=timestamp_ns,
+            value=float(value[1])
+        )

loki_reader_core-0.2.0/src/loki_reader_core/models/metric_series.py

@@ -0,0 +1,90 @@
+"""
+MetricSeries model representing a series of metric datapoints with common labels.
+"""
+
+from dataclasses import dataclass
+
+from .metric_sample import MetricSample
+
+
+@dataclass
+class MetricSeries:
+    """
+    A series of metric datapoints sharing common labels.
+
+    Returned by Loki for metric queries like count_over_time, rate, etc.
+
+    Attributes:
+        labels: Dictionary of label key-value pairs identifying this series.
+        samples: List of MetricSample objects with timestamp/value pairs.
+    """
+
+    labels: dict[str, str]
+    samples: list[MetricSample]
+
+    def to_dict(self) -> dict:
+        """
+        Convert to dictionary for serialization.
+
+        Returns:
+            Dictionary with labels and samples.
+        """
+        return {
+            "labels": self.labels,
+            "samples": [sample.to_dict() for sample in self.samples]
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "MetricSeries":
+        """
+        Create MetricSeries from dictionary.
+
+        Args:
+            data: Dictionary with labels and samples keys.
+
+        Returns:
+            MetricSeries instance.
+        """
+        samples = [MetricSample.from_dict(s) for s in data.get("samples", [])]
+        return cls(
+            labels=data["labels"],
+            samples=samples
+        )
+
+    @classmethod
+    def from_loki_matrix(cls, data: dict) -> "MetricSeries":
+        """
+        Create MetricSeries from Loki matrix result format.
+
+        Matrix results have multiple timestamp/value pairs per series.
+        Format: {"metric": {labels}, "values": [[ts, val], ...]}
+
+        Args:
+            data: Dictionary with 'metric' (labels) and 'values' (datapoints).
+
+        Returns:
+            MetricSeries instance.
+        """
+        labels = data.get("metric", {})
+        values = data.get("values", [])
+        samples = [MetricSample.from_loki_value(v) for v in values]
+        return cls(labels=labels, samples=samples)
+
+    @classmethod
+    def from_loki_vector(cls, data: dict) -> "MetricSeries":
+        """
+        Create MetricSeries from Loki vector result format.
+
+        Vector results have a single timestamp/value pair per series.
+        Format: {"metric": {labels}, "value": [ts, val]}
+
+        Args:
+            data: Dictionary with 'metric' (labels) and 'value' (single datapoint).
+
+        Returns:
+            MetricSeries instance with one sample.
+        """
+        labels = data.get("metric", {})
+        value = data.get("value", [])
+        samples = [MetricSample.from_loki_value(value)] if value else []
+        return cls(labels=labels, samples=samples)

loki_reader_core-0.2.0/src/loki_reader_core/models/query_result.py

@@ -0,0 +1,134 @@
+"""
+QueryResult model representing the result of a Loki query.
+"""
+
+from dataclasses import dataclass, field
+
+from .log_stream import LogStream
+from .metric_series import MetricSeries
+from .query_stats import QueryStats
+
+
+@dataclass
+class QueryResult:
+    """
+    Result of a Loki query containing streams, metric series, and statistics.
+
+    Attributes:
+        status: Response status from Loki (typically "success").
+        streams: List of LogStream objects (populated for log queries).
+        stats: Optional QueryStats with execution statistics.
+        result_type: Loki result type ("streams", "matrix", or "vector").
+        metric_series: List of MetricSeries objects (populated for metric queries).
+    """
+
+    status: str
+    streams: list[LogStream]
+    stats: QueryStats | None
+    result_type: str = "streams"
+    metric_series: list[MetricSeries] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        """
+        Convert to dictionary for serialization.
+
+        Returns:
+            Dictionary with status, streams, metric_series, and stats.
+        """
+        return {
+            "status": self.status,
+            "result_type": self.result_type,
+            "streams": [stream.to_dict() for stream in self.streams],
+            "metric_series": [s.to_dict() for s in self.metric_series],
+            "stats": self.stats.to_dict() if self.stats else None
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "QueryResult":
+        """
+        Create QueryResult from dictionary.
+
+        Args:
+            data: Dictionary with status, streams, metric_series, and stats keys.
+
+        Returns:
+            QueryResult instance.
+        """
+        streams = [LogStream.from_dict(s) for s in data.get("streams", [])]
+        metric_series = [
+            MetricSeries.from_dict(s) for s in data.get("metric_series", [])
+        ]
+        stats = QueryStats.from_dict(data["stats"]) if data.get("stats") else None
+        return cls(
+            status=data["status"],
+            streams=streams,
+            stats=stats,
+            result_type=data.get("result_type", "streams"),
+            metric_series=metric_series,
+        )
+
+    @classmethod
+    def from_loki_response(cls, response_data: dict) -> "QueryResult":
+        """
+        Create QueryResult from Loki API response format.
+
+        Handles all three Loki result types:
+        - streams: log lines with labels
+        - matrix: time series of numeric values (from rate, count_over_time, etc.)
+        - vector: instant numeric values
+
+        Args:
+            response_data: Full response from Loki query API.
+
+        Returns:
+            QueryResult instance.
+        """
+        status = response_data.get("status", "unknown")
+        data = response_data.get("data", {})
+        result_type = data.get("resultType", "streams")
+        result_list = data.get("result", [])
+
+        stats_data = data.get("stats")
+        stats = QueryStats.from_loki_stats(stats_data) if stats_data else None
+
+        streams: list[LogStream] = []
+        metric_series: list[MetricSeries] = []
+
+        if result_type == "matrix":
+            metric_series = [
+                MetricSeries.from_loki_matrix(r) for r in result_list
+            ]
+        elif result_type == "vector":
+            metric_series = [
+                MetricSeries.from_loki_vector(r) for r in result_list
+            ]
+        else:
+            streams = [LogStream.from_loki_stream(s) for s in result_list]
+
+        return cls(
+            status=status,
+            streams=streams,
+            stats=stats,
+            result_type=result_type,
+            metric_series=metric_series,
+        )
+
+    @property
+    def total_entries(self) -> int:
+        """
+        Get total number of log entries across all streams.
+
+        Returns:
+            Total entry count.
+        """
+        return sum(len(stream.entries) for stream in self.streams)
+
+    @property
+    def total_samples(self) -> int:
+        """
+        Get total number of metric samples across all series.
+
+        Returns:
+            Total sample count.
+        """
+        return sum(len(series.samples) for series in self.metric_series)