gcp-observability 0.1.0__tar.gz

gcp_observability-0.1.0/.claude/settings.local.json

@@ -0,0 +1,17 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(gcloud config *)",
+      "Bash(gcloud projects *)",
+      "Bash(.venv/bin/python *)",
+      "Bash(git commit *)",
+      "Bash(git -C /Users/javad/Desktop/gcp_observability add gcp_observability/logs/ main.py)",
+      "Bash(git -C /Users/javad/Desktop/gcp_observability commit -m ' *)",
+      "Bash(git -C /Users/javad/Desktop/gcp_observability push)",
+      "Bash(git -C /Users/javad/Desktop/gcp_observability add gcp_observability/discovery/cloud_run.py)",
+      "Bash(.venv/bin/pytest *)",
+      "Bash(git config *)",
+      "Bash(uv build *)"
+    ]
+  }
+}

gcp_observability-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+.DS_Store
+inventory.json
+*.egg-info/
+.ruff_cache/

gcp_observability-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

gcp_observability-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 javadebadi
+
+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.

gcp_observability-0.1.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: gcp-observability
+Version: 0.1.0
+Summary: Programmatic query builder for Google Cloud Logging filter language
+Project-URL: Repository, https://github.com/javadebadi/gcp-observability
+Author-email: javadebadi <javad.ebadi.1990@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: cloud-logging,gcp,google-cloud,logging,observability,query-builder
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Logging
+Requires-Python: >=3.11
+Requires-Dist: google-cloud-logging>=3.16.0
+Description-Content-Type: text/markdown
+
+# GCP Observability
+
+Python toolkit for Google Cloud observability — starting with a programmatic Cloud Logging query builder.
+
+## Cloud Logging Query Builder
+
+Build Cloud Logging filter strings in Python instead of writing them by hand.
+The output is identical to what you'd type in the **"Build query"** panel of the Cloud Logging console.
+
+### Installation
+
+```bash
+pip install -e .
+```
+
+### Example — find errors containing "ValueError: Bad"
+
+```python
+from datetime import datetime
+from gcp_observability.logging import QueryBuilder, Severity, F
+
+query = (
+    QueryBuilder()
+    .severity_gte(Severity.ERROR)
+    .time_range(
+        start=datetime(2026, 7, 9, 10, 0, 0),   # 2026-07-09T10:00:00Z
+        end=datetime(2026, 7, 9, 10, 30, 0),    # 2026-07-09T10:30:00Z
+    )
+    .where(
+        F("textPayload").has("ValueError: Bad")
+        | F("jsonPayload.message").has("ValueError: Bad")
+    )
+    .build()
+)
+
+print(query)
+```
+
+Output — paste this directly into the Cloud Logging console or pass to `gcloud`:
+
+```
+severity>=ERROR
+timestamp>="2026-07-09T10:00:00Z"
+timestamp<"2026-07-09T10:30:00Z"
+(textPayload:"ValueError: Bad") OR (jsonPayload.message:"ValueError: Bad")
+```
+
+### Use with the Cloud Logging client
+
+```python
+import google.cloud.logging
+
+client = google.cloud.logging.Client(project="my-gcp-project")
+entries = client.list_entries(filter_=query)
+
+for entry in entries:
+    print(entry.timestamp, entry.payload)
+```
+
+### Use with gcloud CLI
+
+```bash
+gcloud logging read 'severity>=ERROR
+timestamp>="2026-07-09T10:00:00Z"
+timestamp<"2026-07-09T10:30:00Z"
+(textPayload:"ValueError: Bad") OR (jsonPayload.message:"ValueError: Bad")'
+```
+
+---
+
+## API reference
+
+### `QueryBuilder` methods
+
+| Method | Description |
+|---|---|
+| `.resource_type(type)` | Filter by resource type (e.g. `cloud_run_revision`) |
+| `.resource_label(key, value)` | Filter by a resource label |
+| `.project(project_id)` | Restrict to a GCP project |
+| `.log_name(name)` | Exact `logName` match |
+| `.severity(op, level)` | Severity with explicit operator (`=`, `>=`, etc.) |
+| `.severity_eq(level)` | `severity=LEVEL` |
+| `.severity_gte(level)` | `severity>=LEVEL` |
+| `.severity_range(low, high)` | `severity>=LOW` and `severity<=HIGH` |
+| `.time_range(start, end)` | Timestamp window (str or `datetime`, end is exclusive) |
+| `.since(hours, minutes, days)` | Relative window from now |
+| `.text_payload(value)` | Substring match on `textPayload` |
+| `.json_payload(field, op, value)` | Filter on a `jsonPayload` sub-field |
+| `.json_payload_has(field, value)` | Substring match on a `jsonPayload` sub-field |
+| `.proto_payload(field, op, value)` | Filter on a `protoPayload` sub-field |
+| `.http_method(method)` | HTTP request method |
+| `.http_status(op, status)` | HTTP response status code |
+| `.http_url(value)` | Substring match on request URL |
+| `.http_latency_gte(seconds)` | Requests slower than N seconds |
+| `.label(key, value)` | Log entry label (special chars in key auto-quoted) |
+| `.trace(trace_id)` | Filter by trace ID |
+| `.span_id(span_id)` | Filter by span ID |
+| `.where(expr)` | Add a raw `F()`-built expression |
+| `.raw(filter_str)` | Add a verbatim filter string |
+| `.build()` | Return the complete filter string |
+
+### `F()` — low-level expression builder
+
+```python
+from gcp_observability.logging import F
+
+# Comparisons
+F("severity") >= "ERROR"
+F("resource.type") == "cloud_run_revision"
+F("httpRequest.status") >= 500
+
+# Substring / has-field
+F("textPayload").has("panic")
+F("jsonPayload.message").has("timeout")
+
+# Chained dot access
+F("resource").labels.zone == "us-central1-a"
+
+# Labels with special characters
+F("labels")["k8s-pod/app"] == "my-service"
+
+# Boolean operators
+expr_a & expr_b   # AND
+expr_a | expr_b   # OR
+~expr_a           # NOT
+```
+
+### Constants
+
+```python
+from gcp_observability.logging import Severity, ResourceType
+
+Severity.DEBUG, Severity.INFO, Severity.NOTICE
+Severity.WARNING, Severity.ERROR, Severity.CRITICAL
+
+ResourceType.CLOUD_RUN_REVISION
+ResourceType.GKE_CONTAINER
+ResourceType.GCE_INSTANCE
+ResourceType.LOAD_BALANCER
+# ... see constants.py for full list
+```

gcp_observability-0.1.0/README.md

@@ -0,0 +1,141 @@
+# GCP Observability
+
+Python toolkit for Google Cloud observability — starting with a programmatic Cloud Logging query builder.
+
+## Cloud Logging Query Builder
+
+Build Cloud Logging filter strings in Python instead of writing them by hand.
+The output is identical to what you'd type in the **"Build query"** panel of the Cloud Logging console.
+
+### Installation
+
+```bash
+pip install -e .
+```
+
+### Example — find errors containing "ValueError: Bad"
+
+```python
+from datetime import datetime
+from gcp_observability.logging import QueryBuilder, Severity, F
+
+query = (
+    QueryBuilder()
+    .severity_gte(Severity.ERROR)
+    .time_range(
+        start=datetime(2026, 7, 9, 10, 0, 0),   # 2026-07-09T10:00:00Z
+        end=datetime(2026, 7, 9, 10, 30, 0),    # 2026-07-09T10:30:00Z
+    )
+    .where(
+        F("textPayload").has("ValueError: Bad")
+        | F("jsonPayload.message").has("ValueError: Bad")
+    )
+    .build()
+)
+
+print(query)
+```
+
+Output — paste this directly into the Cloud Logging console or pass to `gcloud`:
+
+```
+severity>=ERROR
+timestamp>="2026-07-09T10:00:00Z"
+timestamp<"2026-07-09T10:30:00Z"
+(textPayload:"ValueError: Bad") OR (jsonPayload.message:"ValueError: Bad")
+```
+
+### Use with the Cloud Logging client
+
+```python
+import google.cloud.logging
+
+client = google.cloud.logging.Client(project="my-gcp-project")
+entries = client.list_entries(filter_=query)
+
+for entry in entries:
+    print(entry.timestamp, entry.payload)
+```
+
+### Use with gcloud CLI
+
+```bash
+gcloud logging read 'severity>=ERROR
+timestamp>="2026-07-09T10:00:00Z"
+timestamp<"2026-07-09T10:30:00Z"
+(textPayload:"ValueError: Bad") OR (jsonPayload.message:"ValueError: Bad")'
+```
+
+---
+
+## API reference
+
+### `QueryBuilder` methods
+
+| Method | Description |
+|---|---|
+| `.resource_type(type)` | Filter by resource type (e.g. `cloud_run_revision`) |
+| `.resource_label(key, value)` | Filter by a resource label |
+| `.project(project_id)` | Restrict to a GCP project |
+| `.log_name(name)` | Exact `logName` match |
+| `.severity(op, level)` | Severity with explicit operator (`=`, `>=`, etc.) |
+| `.severity_eq(level)` | `severity=LEVEL` |
+| `.severity_gte(level)` | `severity>=LEVEL` |
+| `.severity_range(low, high)` | `severity>=LOW` and `severity<=HIGH` |
+| `.time_range(start, end)` | Timestamp window (str or `datetime`, end is exclusive) |
+| `.since(hours, minutes, days)` | Relative window from now |
+| `.text_payload(value)` | Substring match on `textPayload` |
+| `.json_payload(field, op, value)` | Filter on a `jsonPayload` sub-field |
+| `.json_payload_has(field, value)` | Substring match on a `jsonPayload` sub-field |
+| `.proto_payload(field, op, value)` | Filter on a `protoPayload` sub-field |
+| `.http_method(method)` | HTTP request method |
+| `.http_status(op, status)` | HTTP response status code |
+| `.http_url(value)` | Substring match on request URL |
+| `.http_latency_gte(seconds)` | Requests slower than N seconds |
+| `.label(key, value)` | Log entry label (special chars in key auto-quoted) |
+| `.trace(trace_id)` | Filter by trace ID |
+| `.span_id(span_id)` | Filter by span ID |
+| `.where(expr)` | Add a raw `F()`-built expression |
+| `.raw(filter_str)` | Add a verbatim filter string |
+| `.build()` | Return the complete filter string |
+
+### `F()` — low-level expression builder
+
+```python
+from gcp_observability.logging import F
+
+# Comparisons
+F("severity") >= "ERROR"
+F("resource.type") == "cloud_run_revision"
+F("httpRequest.status") >= 500
+
+# Substring / has-field
+F("textPayload").has("panic")
+F("jsonPayload.message").has("timeout")
+
+# Chained dot access
+F("resource").labels.zone == "us-central1-a"
+
+# Labels with special characters
+F("labels")["k8s-pod/app"] == "my-service"
+
+# Boolean operators
+expr_a & expr_b   # AND
+expr_a | expr_b   # OR
+~expr_a           # NOT
+```
+
+### Constants
+
+```python
+from gcp_observability.logging import Severity, ResourceType
+
+Severity.DEBUG, Severity.INFO, Severity.NOTICE
+Severity.WARNING, Severity.ERROR, Severity.CRITICAL
+
+ResourceType.CLOUD_RUN_REVISION
+ResourceType.GKE_CONTAINER
+ResourceType.GCE_INSTANCE
+ResourceType.LOAD_BALANCER
+# ... see constants.py for full list
+```

gcp_observability-0.1.0/gcp_observability/__init__.py

@@ -0,0 +1,3 @@
+from .logging import QueryBuilder, Severity, ResourceType, F
+
+__all__ = ["QueryBuilder", "Severity", "ResourceType", "F"]

gcp_observability-0.1.0/gcp_observability/logging/__init__.py

@@ -0,0 +1,17 @@
+from .constants import ResourceType, Severity
+from .expressions import And, Comparison, Expr, F, Field, Not, Or, Raw
+from .query import QueryBuilder
+
+__all__ = [
+    "QueryBuilder",
+    "Expr",
+    "Comparison",
+    "And",
+    "Or",
+    "Not",
+    "Raw",
+    "Field",
+    "F",
+    "Severity",
+    "ResourceType",
+]

gcp_observability-0.1.0/gcp_observability/logging/constants.py

@@ -0,0 +1,40 @@
+"""Cloud Logging constants: severity levels and resource types."""
+
+from __future__ import annotations
+
+
+class Severity:
+    DEFAULT = "DEFAULT"
+    DEBUG = "DEBUG"
+    INFO = "INFO"
+    NOTICE = "NOTICE"
+    WARNING = "WARNING"
+    ERROR = "ERROR"
+    CRITICAL = "CRITICAL"
+    ALERT = "ALERT"
+    EMERGENCY = "EMERGENCY"
+
+    # Ordered list (lowest → highest) for range helpers
+    _LEVELS = [DEFAULT, DEBUG, INFO, NOTICE, WARNING, ERROR, CRITICAL, ALERT, EMERGENCY]
+
+
+class ResourceType:
+    GLOBAL = "global"
+    GCE_INSTANCE = "gce_instance"
+    GKE_CONTAINER = "k8s_container"
+    GKE_POD = "k8s_pod"
+    GKE_NODE = "k8s_node"
+    GKE_CLUSTER = "k8s_cluster"
+    CLOUD_RUN_REVISION = "cloud_run_revision"
+    CLOUD_RUN_JOB = "cloud_run_job"
+    CLOUD_FUNCTION = "cloud_function"
+    APP_ENGINE = "gae_app"
+    CLOUD_SQL = "cloudsql_database"
+    LOAD_BALANCER = "http_load_balancer"
+    PUBSUB_TOPIC = "pubsub_topic"
+    PUBSUB_SUBSCRIPTION = "pubsub_subscription"
+    BIG_QUERY = "bigquery_resource"
+    STORAGE = "gcs_bucket"
+    DATAFLOW = "dataflow_step"
+    CLOUD_TASKS_QUEUE = "cloud_tasks_queue"
+    REDIS_INSTANCE = "redis_instance"

gcp_observability-0.1.0/gcp_observability/logging/expressions.py

@@ -0,0 +1,175 @@
+"""
+Low-level expression tree for Cloud Logging filter language.
+
+Usage:
+    from gcp_observability.logging.expressions import F, And, Or, Not, Raw
+
+    expr = (
+        (F("resource.type") == "cloud_run_revision")
+        & (F("severity") >= "ERROR")
+        & ~(F("textPayload").has("healthcheck"))
+    )
+    print(expr.build())
+"""
+
+from __future__ import annotations
+
+import re
+from abc import ABC, abstractmethod
+
+_SAFE_VALUE = re.compile(r"^[a-zA-Z0-9_]+$")
+
+
+def _format_value(value: object) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (int, float)):
+        return str(value)
+    s = str(value)
+    if _SAFE_VALUE.match(s):
+        return s
+    escaped = s.replace("\\", "\\\\").replace('"', '\\"')
+    return f'"{escaped}"'
+
+
+class Expr(ABC):
+    @abstractmethod
+    def build(self) -> str: ...
+
+    def __and__(self, other: Expr) -> And:
+        if isinstance(self, And):
+            return And(*self.exprs, other)
+        return And(self, other)
+
+    def __or__(self, other: Expr) -> Or:
+        if isinstance(self, Or):
+            return Or(*self.exprs, other)
+        return Or(self, other)
+
+    def __invert__(self) -> Not:
+        return Not(self)
+
+    def __str__(self) -> str:
+        return self.build()
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({self.build()!r})"
+
+
+class Comparison(Expr):
+    def __init__(self, field: str, op: str, value: object) -> None:
+        self.field = field
+        self.op = op
+        self.value = value
+
+    def build(self) -> str:
+        return f"{self.field}{self.op}{_format_value(self.value)}"
+
+
+class And(Expr):
+    def __init__(self, *exprs: Expr) -> None:
+        flat: list[Expr] = []
+        for e in exprs:
+            if isinstance(e, And):
+                flat.extend(e.exprs)
+            else:
+                flat.append(e)
+        self.exprs = tuple(flat)
+
+    def build(self) -> str:
+        parts: list[str] = []
+        for e in self.exprs:
+            s = e.build()
+            parts.append(f"({s})" if isinstance(e, Or) else s)
+        return "\nAND ".join(parts)
+
+
+class Or(Expr):
+    def __init__(self, *exprs: Expr) -> None:
+        flat: list[Expr] = []
+        for e in exprs:
+            if isinstance(e, Or):
+                flat.extend(e.exprs)
+            else:
+                flat.append(e)
+        self.exprs = tuple(flat)
+
+    def build(self) -> str:
+        return " OR ".join(f"({e.build()})" for e in self.exprs)
+
+
+class Not(Expr):
+    def __init__(self, expr: Expr) -> None:
+        self.expr = expr
+
+    def build(self) -> str:
+        inner = self.expr.build()
+        if isinstance(self.expr, (And, Or)):
+            return f"NOT ({inner})"
+        return f"NOT {inner}"
+
+
+class Raw(Expr):
+    """Pass a raw filter string through unchanged."""
+
+    def __init__(self, filter_str: str) -> None:
+        self.filter_str = filter_str
+
+    def build(self) -> str:
+        return self.filter_str
+
+
+class Field:
+    """
+    A field reference that produces Expr objects via comparison operators.
+
+    Examples:
+        F("severity") >= "ERROR"          -> Comparison("severity", ">=", "ERROR")
+        F("resource.type") == "gce_instance"
+        F("textPayload").has("error")     -> Comparison("textPayload", ":", "error")
+        F("labels")["my-label"] == "v1"  -> labels with special-char key
+        F("resource").labels.zone == "us-central1-a"   # chained via dot
+    """
+
+    __slots__ = ("_name",)
+
+    def __init__(self, name: str) -> None:
+        object.__setattr__(self, "_name", name)
+
+    # Attribute access builds dot-notation field paths: F("resource").type
+    def __getattr__(self, attr: str) -> Field:
+        return Field(f"{self._name}.{attr}")
+
+    # Bracket access quotes the key for special-char label/field names
+    def __getitem__(self, key: str) -> Field:
+        return Field(f'{self._name}."{key}"')
+
+    def __eq__(self, value: object) -> Comparison:  # type: ignore[override]
+        return Comparison(self._name, "=", value)
+
+    def __ne__(self, value: object) -> Comparison:  # type: ignore[override]
+        return Comparison(self._name, "!=", value)
+
+    def __gt__(self, value: object) -> Comparison:
+        return Comparison(self._name, ">", value)
+
+    def __lt__(self, value: object) -> Comparison:
+        return Comparison(self._name, "<", value)
+
+    def __ge__(self, value: object) -> Comparison:
+        return Comparison(self._name, ">=", value)
+
+    def __le__(self, value: object) -> Comparison:
+        return Comparison(self._name, "<=", value)
+
+    def has(self, value: str) -> Comparison:
+        """Substring / has-field match using the `:` operator."""
+        return Comparison(self._name, ":", value)
+
+    def __repr__(self) -> str:
+        return f"Field({self._name!r})"
+
+
+def F(name: str) -> Field:
+    """Shorthand for Field(name)."""
+    return Field(name)