hyperlake-telemetry 0.1.0__tar.gz

hyperlake_telemetry-0.1.0/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: hyperlake-telemetry
+Version: 0.1.0
+Summary: Standards-first telemetry and artifact SDK for Hyperlake
+Author-email: Hyperlake <vc@hyperlake.cloud>
+License-Expression: LicenseRef-Proprietary
+Project-URL: Homepage, https://hyperlake.cloud
+Project-URL: Documentation, https://hyperlake.cloud/docs
+Keywords: opentelemetry,otlp,openinference,agents,temporal,langflow
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: certifi>=2024.2.2
+Provides-Extra: temporal
+Requires-Dist: temporalio[opentelemetry]>=1.20; extra == "temporal"
+Provides-Extra: langflow
+Requires-Dist: langflow>=1.6; extra == "langflow"
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.30; extra == "otel"
+Requires-Dist: opentelemetry-sdk>=1.30; extra == "otel"
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.30; extra == "otel"
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: twine>=6; extra == "dev"
+
+# Hyperlake Telemetry SDK for Python
+
+`hyperlake-telemetry` sends standards-compatible OTLP/HTTP JSON and can attach
+events or immutable artifacts to the same pipeline. It does not replace the
+OpenTelemetry SDK: applications with existing instrumentation should continue
+using their normal exporter and use this package only for run context, stable
+event identity, evaluations, and artifact attachment.
+
+```bash
+pip install hyperlake-telemetry
+```
+
+```python
+from hyperlake_telemetry import Client, Privacy
+
+client = Client(
+    base_url="https://us.hyperlake.cloud",
+    tenant_id="tenant-public-id",
+    pipeline_id="pipeline-public-id",
+    protocol_token="write-only-protocol-token",
+    tenant_jwt="short-lived-jwks-jwt",
+    privacy=Privacy(capture_content=False),
+)
+
+with client.run("invoice-agent", goal_id="goal-42") as run:
+    with run.span("lookup-account", kind="RETRIEVER"):
+        pass
+    run.evaluate("groundedness", score=0.97, label="pass")
+
+client.flush()
+```
+
+The authenticated credential determines the authoritative tenant and pipeline.
+The IDs supplied by the application are routing hints and must match the token.
+Prompt, response, tool argument, and tool result content is suppressed by
+default. Set `capture_content=True` only after applying an approved data policy.
+
+See the repository integration guides for Temporal, Langflow, OpenInference,
+Collector, and Alloy examples.
+

hyperlake_telemetry-0.1.0/README.md

@@ -0,0 +1,40 @@
+# Hyperlake Telemetry SDK for Python
+
+`hyperlake-telemetry` sends standards-compatible OTLP/HTTP JSON and can attach
+events or immutable artifacts to the same pipeline. It does not replace the
+OpenTelemetry SDK: applications with existing instrumentation should continue
+using their normal exporter and use this package only for run context, stable
+event identity, evaluations, and artifact attachment.
+
+```bash
+pip install hyperlake-telemetry
+```
+
+```python
+from hyperlake_telemetry import Client, Privacy
+
+client = Client(
+    base_url="https://us.hyperlake.cloud",
+    tenant_id="tenant-public-id",
+    pipeline_id="pipeline-public-id",
+    protocol_token="write-only-protocol-token",
+    tenant_jwt="short-lived-jwks-jwt",
+    privacy=Privacy(capture_content=False),
+)
+
+with client.run("invoice-agent", goal_id="goal-42") as run:
+    with run.span("lookup-account", kind="RETRIEVER"):
+        pass
+    run.evaluate("groundedness", score=0.97, label="pass")
+
+client.flush()
+```
+
+The authenticated credential determines the authoritative tenant and pipeline.
+The IDs supplied by the application are routing hints and must match the token.
+Prompt, response, tool argument, and tool result content is suppressed by
+default. Set `capture_content=True` only after applying an approved data policy.
+
+See the repository integration guides for Temporal, Langflow, OpenInference,
+Collector, and Alloy examples.
+

hyperlake_telemetry-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hyperlake-telemetry"
+version = "0.1.0"
+description = "Standards-first telemetry and artifact SDK for Hyperlake"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "LicenseRef-Proprietary"
+authors = [{name = "Hyperlake", email = "vc@hyperlake.cloud"}]
+keywords = ["opentelemetry", "otlp", "openinference", "agents", "temporal", "langflow"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: System :: Monitoring",
+]
+dependencies = ["certifi>=2024.2.2"]
+
+[project.optional-dependencies]
+temporal = ["temporalio[opentelemetry]>=1.20"]
+langflow = ["langflow>=1.6"]
+otel = [
+  "opentelemetry-api>=1.30",
+  "opentelemetry-sdk>=1.30",
+  "opentelemetry-exporter-otlp-proto-http>=1.30",
+]
+dev = ["build>=1.2", "pytest>=8", "twine>=6"]
+
+[project.urls]
+Homepage = "https://hyperlake.cloud"
+Documentation = "https://hyperlake.cloud/docs"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

hyperlake_telemetry-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

hyperlake_telemetry-0.1.0/src/hyperlake_telemetry/__init__.py

@@ -0,0 +1,7 @@
+"""Standards-first OTLP telemetry and artifact helpers."""
+
+from .client import Client, Privacy, Run, Span, stable_event_id
+
+__all__ = ["Client", "Privacy", "Run", "Span", "stable_event_id"]
+__version__ = "0.1.0"
+

hyperlake_telemetry-0.1.0/src/hyperlake_telemetry/client.py

@@ -0,0 +1,404 @@
+"""Small dependency-free OTLP/HTTP client with explicit privacy controls."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import secrets
+import ssl
+import time
+from contextlib import AbstractContextManager
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, Iterable, Mapping, Optional
+from urllib.error import HTTPError, URLError
+from urllib.parse import quote
+from urllib.request import Request, urlopen
+
+import certifi
+
+
+_SENSITIVE_KEY = re.compile(
+    r"(^|[._-])(authorization|cookie|password|passwd|secret|token|api[._-]?key|private[._-]?key)([._-]|$)",
+    re.IGNORECASE,
+)
+
+
+def stable_event_id(*parts: Any) -> str:
+    """Return a deterministic identity for a logical event or evaluation."""
+    canonical = json.dumps(parts, sort_keys=True, separators=(",", ":"), default=str)
+    return "evt_" + hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+
+
+@dataclass(frozen=True)
+class Privacy:
+    """Content and secret handling applied before telemetry leaves the process."""
+
+    capture_content: bool = False
+    redacted_keys: tuple[str, ...] = ()
+    max_string_length: int = 4096
+    replacement: str = "[REDACTED]"
+
+    def sanitize(self, value: Any, *, content: bool = False) -> Any:
+        if content and not self.capture_content:
+            return self.replacement
+        return self._walk(value)
+
+    def _walk(self, value: Any, key: str = "") -> Any:
+        if key in self.redacted_keys or _SENSITIVE_KEY.search(key):
+            return self.replacement
+        if isinstance(value, Mapping):
+            return {str(k): self._walk(v, str(k)) for k, v in value.items()}
+        if isinstance(value, (list, tuple)):
+            return [self._walk(item, key) for item in value]
+        if isinstance(value, str) and len(value) > self.max_string_length:
+            return value[: self.max_string_length] + "…[TRUNCATED]"
+        if value is None or isinstance(value, (str, bool, int, float)):
+            return value
+        return str(value)
+
+
+def _any_value(value: Any) -> Dict[str, Any]:
+    if value is None:
+        return {"stringValue": ""}
+    if isinstance(value, bool):
+        return {"boolValue": value}
+    if isinstance(value, int):
+        return {"intValue": str(value)}
+    if isinstance(value, float):
+        return {"doubleValue": value}
+    if isinstance(value, (dict, list, tuple)):
+        return {"stringValue": json.dumps(value, sort_keys=True, separators=(",", ":"))}
+    return {"stringValue": str(value)}
+
+
+def _attributes(values: Mapping[str, Any]) -> list[Dict[str, Any]]:
+    return [{"key": str(k), "value": _any_value(v)} for k, v in values.items() if v is not None]
+
+
+@dataclass
+class Span(AbstractContextManager["Span"]):
+    client: "Client"
+    name: str
+    trace_id: str
+    span_id: str
+    parent_span_id: Optional[str]
+    attributes: Dict[str, Any]
+    start_ns: int = field(default_factory=time.time_ns)
+    end_ns: Optional[int] = None
+    status_code: int = 0
+    status_message: str = ""
+    events: list[Dict[str, Any]] = field(default_factory=list)
+    _ended: bool = False
+
+    def __enter__(self) -> "Span":
+        return self
+
+    def __exit__(self, exc_type, exc, traceback) -> bool:
+        if exc is not None:
+            self.status_code = 2
+            self.status_message = str(exc)
+            self.add_event("exception", {"exception.type": exc_type.__name__, "exception.message": str(exc)})
+        self.end()
+        return False
+
+    def set_attribute(self, key: str, value: Any, *, content: bool = False) -> "Span":
+        self.attributes[key] = self.client.privacy.sanitize(value, content=content)
+        return self
+
+    def add_event(self, name: str, attributes: Optional[Mapping[str, Any]] = None) -> "Span":
+        clean = self.client.privacy.sanitize(dict(attributes or {}))
+        self.events.append({"timeUnixNano": str(time.time_ns()), "name": name, "attributes": _attributes(clean)})
+        return self
+
+    def end(self, *, error: Optional[str] = None) -> None:
+        if self._ended:
+            return
+        if error:
+            self.status_code = 2
+            self.status_message = error
+        self.end_ns = time.time_ns()
+        self._ended = True
+        self.client._finish_span(self)
+
+    def as_otlp(self) -> Dict[str, Any]:
+        body: Dict[str, Any] = {
+            "traceId": self.trace_id,
+            "spanId": self.span_id,
+            "name": self.name,
+            "kind": 1,
+            "startTimeUnixNano": str(self.start_ns),
+            "endTimeUnixNano": str(self.end_ns or time.time_ns()),
+            "attributes": _attributes(self.attributes),
+            "events": self.events,
+            "status": {"code": self.status_code, "message": self.status_message},
+        }
+        if self.parent_span_id:
+            body["parentSpanId"] = self.parent_span_id
+        return body
+
+
+class Run(AbstractContextManager["Run"]):
+    def __init__(self, client: "Client", root: Span, goal_id: Optional[str]) -> None:
+        self.client = client
+        self.root = root
+        self.goal_id = goal_id
+
+    @property
+    def trace_id(self) -> str:
+        return self.root.trace_id
+
+    @property
+    def run_id(self) -> str:
+        return str(self.root.attributes["run.id"])
+
+    def __enter__(self) -> "Run":
+        return self
+
+    def __exit__(self, exc_type, exc, traceback) -> bool:
+        return self.root.__exit__(exc_type, exc, traceback)
+
+    def span(
+        self,
+        name: str,
+        *,
+        kind: str = "CHAIN",
+        attributes: Optional[Mapping[str, Any]] = None,
+    ) -> Span:
+        merged = {
+            "openinference.span.kind": kind.upper(),
+            "run.id": self.run_id,
+            "goal.id": self.goal_id,
+            **dict(attributes or {}),
+        }
+        return self.client.start_span(
+            name,
+            trace_id=self.trace_id,
+            parent_span_id=self.root.span_id,
+            attributes=merged,
+        )
+
+    def evaluate(self, name: str, *, score: float, label: str, explanation: str = "") -> None:
+        self.root.add_event(
+            "gen_ai.evaluation",
+            {
+                "gen_ai.evaluation.name": name,
+                "gen_ai.evaluation.score.value": score,
+                "gen_ai.evaluation.score.label": label,
+                "gen_ai.evaluation.explanation": explanation,
+            },
+        )
+
+
+class Client:
+    """OTLP sender plus authenticated event and artifact helpers."""
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        tenant_id: str,
+        pipeline_id: str,
+        protocol_token: Optional[str] = None,
+        tenant_jwt: Optional[str] = None,
+        service_name: str = "application",
+        service_version: Optional[str] = None,
+        environment: Optional[str] = None,
+        privacy: Optional[Privacy] = None,
+        timeout: float = 30.0,
+        spool_directory: Optional[str] = None,
+        max_spool_files: int = 256,
+        auto_flush_spans: int = 64,
+        ssl_context: Optional[ssl.SSLContext] = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.tenant_id = tenant_id
+        self.pipeline_id = pipeline_id
+        self.protocol_token = protocol_token
+        self.tenant_jwt = tenant_jwt
+        self.service_name = service_name
+        self.service_version = service_version
+        self.environment = environment
+        self.privacy = privacy or Privacy()
+        self.timeout = timeout
+        self.max_spool_files = max_spool_files
+        self.auto_flush_spans = auto_flush_spans
+        self.ssl_context = ssl_context or ssl.create_default_context(cafile=certifi.where())
+        self._pending: list[Span] = []
+        self.spool_directory = Path(spool_directory) if spool_directory else None
+        if self.spool_directory:
+            self.spool_directory.mkdir(parents=True, exist_ok=True, mode=0o700)
+
+    def run(
+        self,
+        name: str,
+        *,
+        run_id: Optional[str] = None,
+        goal_id: Optional[str] = None,
+        agent_id: Optional[str] = None,
+        attributes: Optional[Mapping[str, Any]] = None,
+    ) -> Run:
+        actual_run_id = run_id or secrets.token_hex(16)
+        root = self.start_span(
+            name,
+            attributes={
+                "openinference.span.kind": "AGENT",
+                "gen_ai.operation.name": "invoke_agent",
+                "gen_ai.agent.id": agent_id,
+                "gen_ai.agent.name": name,
+                "run.id": actual_run_id,
+                "goal.id": goal_id,
+                **dict(attributes or {}),
+            },
+        )
+        return Run(self, root, goal_id)
+
+    def start_span(
+        self,
+        name: str,
+        *,
+        trace_id: Optional[str] = None,
+        parent_span_id: Optional[str] = None,
+        attributes: Optional[Mapping[str, Any]] = None,
+    ) -> Span:
+        clean = self.privacy.sanitize(dict(attributes or {}))
+        return Span(
+            client=self,
+            name=name,
+            trace_id=trace_id or secrets.token_hex(16),
+            span_id=secrets.token_hex(8),
+            parent_span_id=parent_span_id,
+            attributes=clean,
+        )
+
+    def _finish_span(self, span: Span) -> None:
+        self._pending.append(span)
+        if len(self._pending) >= self.auto_flush_spans:
+            self.flush()
+
+    def _otlp_payload(self, spans: Iterable[Span]) -> Dict[str, Any]:
+        resource = {
+            "service.name": self.service_name,
+            "service.version": self.service_version,
+            "deployment.environment.name": self.environment,
+        }
+        return {
+            "resourceSpans": [{
+                "resource": {"attributes": _attributes(resource)},
+                "scopeSpans": [{
+                    "scope": {"name": "hyperlake-telemetry", "version": "0.1.0"},
+                    "spans": [span.as_otlp() for span in spans],
+                }],
+            }],
+        }
+
+    def flush(self) -> None:
+        self._drain_spool()
+        if not self._pending:
+            return
+        spans, self._pending = self._pending, []
+        payload = self._otlp_payload(spans)
+        try:
+            self._request("POST", "/v1/traces", payload, protocol=True)
+        except Exception:
+            self._spool(payload)
+            raise
+
+    def record_event(
+        self,
+        event: Mapping[str, Any],
+        *,
+        idempotency_key: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        key = idempotency_key or stable_event_id(self.tenant_id, self.pipeline_id, event)
+        path = f"/v1/ingest/{quote(self.tenant_id)}/{quote(self.pipeline_id)}"
+        return self._request("POST", path, self.privacy.sanitize(dict(event)), jwt=True, extra_headers={"Idempotency-Key": key})
+
+    def upload_artifact(
+        self,
+        path: str,
+        *,
+        format: str = "auto",
+        device_id: Optional[str] = None,
+        goal_id: Optional[str] = None,
+        metadata: Optional[Mapping[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        source = Path(path)
+        base = f"/v1/artifacts/{quote(self.tenant_id)}/{quote(self.pipeline_id)}/sessions"
+        session = self._request(
+            "POST",
+            base,
+            {
+                "filename": source.name,
+                "format": format,
+                "device_id": device_id,
+                "goal_id": goal_id,
+                "metadata": self.privacy.sanitize(dict(metadata or {})),
+            },
+            jwt=True,
+        )
+        session_id = session["session_id"]
+        content = source.read_bytes()
+        self._request("PUT", f"{base}/{quote(session_id)}/content", content, jwt=True, content_type="application/octet-stream")
+        return self._request("POST", f"{base}/{quote(session_id)}/complete", None, jwt=True)
+
+    def _auth_headers(self, *, protocol: bool = False, jwt: bool = False) -> Dict[str, str]:
+        token = self.protocol_token if protocol else self.tenant_jwt if jwt else None
+        if not token:
+            needed = "protocol_token" if protocol else "tenant_jwt"
+            raise ValueError(f"{needed} is required for this operation")
+        headers = {"Authorization": f"Bearer {token}"}
+        if protocol:
+            headers.update({
+                "X-Platform-Tenant": self.tenant_id,
+                "X-Platform-Pipeline": self.pipeline_id,
+            })
+        return headers
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        payload: Any,
+        *,
+        protocol: bool = False,
+        jwt: bool = False,
+        content_type: str = "application/json",
+        extra_headers: Optional[Mapping[str, str]] = None,
+    ) -> Dict[str, Any]:
+        headers = self._auth_headers(protocol=protocol, jwt=jwt)
+        headers.update(extra_headers or {})
+        headers["Content-Type"] = content_type
+        headers["Accept"] = "application/json"
+        headers["User-Agent"] = "hyperlake-telemetry-python/0.1.0"
+        data = payload if isinstance(payload, bytes) else None if payload is None else json.dumps(payload, separators=(",", ":")).encode("utf-8")
+        request = Request(self.base_url + path, data=data, method=method, headers=headers)
+        try:
+            with urlopen(request, timeout=self.timeout, context=self.ssl_context) as response:
+                body = response.read()
+                return json.loads(body) if body else {"status": response.status}
+        except HTTPError as exc:
+            detail = exc.read().decode("utf-8", errors="replace")[:2048]
+            raise RuntimeError(f"HTTP {exc.code} from {path}: {detail}") from exc
+        except URLError as exc:
+            raise RuntimeError(f"Transport failure for {path}: {exc.reason}") from exc
+
+    def _spool(self, payload: Mapping[str, Any]) -> None:
+        if not self.spool_directory:
+            return
+        files = sorted(self.spool_directory.glob("*.json"))
+        while len(files) >= self.max_spool_files:
+            files.pop(0).unlink(missing_ok=True)
+        target = self.spool_directory / f"{time.time_ns()}-{secrets.token_hex(4)}.json"
+        target.write_text(json.dumps(payload, separators=(",", ":")), encoding="utf-8")
+        os.chmod(target, 0o600)
+
+    def _drain_spool(self) -> None:
+        if not self.spool_directory:
+            return
+        for item in sorted(self.spool_directory.glob("*.json")):
+            payload = json.loads(item.read_text(encoding="utf-8"))
+            self._request("POST", "/v1/traces", payload, protocol=True)
+            item.unlink()

hyperlake_telemetry-0.1.0/src/hyperlake_telemetry/integrations/__init__.py

@@ -0,0 +1,7 @@
+"""Helpers for established workflow and agent runtimes."""
+
+from .openinference import span_attributes
+from .temporal import temporal_attributes
+
+__all__ = ["span_attributes", "temporal_attributes"]
+

hyperlake_telemetry-0.1.0/src/hyperlake_telemetry/integrations/openinference.py

@@ -0,0 +1,19 @@
+"""OpenInference-compatible attribute construction without a second tracer."""
+
+from typing import Any, Dict, Optional
+
+
+def span_attributes(
+    kind: str,
+    *,
+    input_value: Optional[Any] = None,
+    output_value: Optional[Any] = None,
+    **attributes: Any,
+) -> Dict[str, Any]:
+    values: Dict[str, Any] = {"openinference.span.kind": kind.upper(), **attributes}
+    if input_value is not None:
+        values["input.value"] = input_value
+    if output_value is not None:
+        values["output.value"] = output_value
+    return values
+

hyperlake_telemetry-0.1.0/src/hyperlake_telemetry/integrations/temporal.py

@@ -0,0 +1,24 @@
+"""Correlation mapping for Temporal's native OpenTelemetry interceptor."""
+
+from typing import Any, Dict, Optional
+
+
+def temporal_attributes(
+    *,
+    workflow_id: str,
+    run_id: str,
+    workflow_type: Optional[str] = None,
+    task_queue: Optional[str] = None,
+    activity_id: Optional[str] = None,
+    attempt: Optional[int] = None,
+) -> Dict[str, Any]:
+    return {
+        "temporal.workflow.id": workflow_id,
+        "temporal.run.id": run_id,
+        "temporal.workflow.type": workflow_type,
+        "temporal.task_queue": task_queue,
+        "temporal.activity.id": activity_id,
+        "temporal.activity.attempt": attempt,
+        "run.id": run_id,
+    }
+

hyperlake_telemetry-0.1.0/src/hyperlake_telemetry.egg-info/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: hyperlake-telemetry
+Version: 0.1.0
+Summary: Standards-first telemetry and artifact SDK for Hyperlake
+Author-email: Hyperlake <vc@hyperlake.cloud>
+License-Expression: LicenseRef-Proprietary
+Project-URL: Homepage, https://hyperlake.cloud
+Project-URL: Documentation, https://hyperlake.cloud/docs
+Keywords: opentelemetry,otlp,openinference,agents,temporal,langflow
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: certifi>=2024.2.2
+Provides-Extra: temporal
+Requires-Dist: temporalio[opentelemetry]>=1.20; extra == "temporal"
+Provides-Extra: langflow
+Requires-Dist: langflow>=1.6; extra == "langflow"
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.30; extra == "otel"
+Requires-Dist: opentelemetry-sdk>=1.30; extra == "otel"
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.30; extra == "otel"
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: twine>=6; extra == "dev"
+
+# Hyperlake Telemetry SDK for Python
+
+`hyperlake-telemetry` sends standards-compatible OTLP/HTTP JSON and can attach
+events or immutable artifacts to the same pipeline. It does not replace the
+OpenTelemetry SDK: applications with existing instrumentation should continue
+using their normal exporter and use this package only for run context, stable
+event identity, evaluations, and artifact attachment.
+
+```bash
+pip install hyperlake-telemetry
+```
+
+```python
+from hyperlake_telemetry import Client, Privacy
+
+client = Client(
+    base_url="https://us.hyperlake.cloud",
+    tenant_id="tenant-public-id",
+    pipeline_id="pipeline-public-id",
+    protocol_token="write-only-protocol-token",
+    tenant_jwt="short-lived-jwks-jwt",
+    privacy=Privacy(capture_content=False),
+)
+
+with client.run("invoice-agent", goal_id="goal-42") as run:
+    with run.span("lookup-account", kind="RETRIEVER"):
+        pass
+    run.evaluate("groundedness", score=0.97, label="pass")
+
+client.flush()
+```
+
+The authenticated credential determines the authoritative tenant and pipeline.
+The IDs supplied by the application are routing hints and must match the token.
+Prompt, response, tool argument, and tool result content is suppressed by
+default. Set `capture_content=True` only after applying an approved data policy.
+
+See the repository integration guides for Temporal, Langflow, OpenInference,
+Collector, and Alloy examples.
+

hyperlake_telemetry-0.1.0/src/hyperlake_telemetry.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+src/hyperlake_telemetry/__init__.py
+src/hyperlake_telemetry/client.py
+src/hyperlake_telemetry.egg-info/PKG-INFO
+src/hyperlake_telemetry.egg-info/SOURCES.txt
+src/hyperlake_telemetry.egg-info/dependency_links.txt
+src/hyperlake_telemetry.egg-info/requires.txt
+src/hyperlake_telemetry.egg-info/top_level.txt
+src/hyperlake_telemetry/integrations/__init__.py
+src/hyperlake_telemetry/integrations/openinference.py
+src/hyperlake_telemetry/integrations/temporal.py
+tests/test_client.py

hyperlake_telemetry-0.1.0/src/hyperlake_telemetry.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

hyperlake_telemetry-0.1.0/src/hyperlake_telemetry.egg-info/requires.txt

@@ -0,0 +1,17 @@
+certifi>=2024.2.2
+
+[dev]
+build>=1.2
+pytest>=8
+twine>=6
+
+[langflow]
+langflow>=1.6
+
+[otel]
+opentelemetry-api>=1.30
+opentelemetry-sdk>=1.30
+opentelemetry-exporter-otlp-proto-http>=1.30
+
+[temporal]
+temporalio[opentelemetry]>=1.20

hyperlake_telemetry-0.1.0/src/hyperlake_telemetry.egg-info/top_level.txt

@@ -0,0 +1 @@
+hyperlake_telemetry

hyperlake_telemetry-0.1.0/tests/test_client.py

@@ -0,0 +1,48 @@
+import json
+
+from hyperlake_telemetry import Client, Privacy, stable_event_id
+from hyperlake_telemetry.integrations import span_attributes, temporal_attributes
+
+
+def test_stable_event_id_is_deterministic():
+    one = stable_event_id("tenant", "pipeline", {"b": 2, "a": 1})
+    two = stable_event_id("tenant", "pipeline", {"a": 1, "b": 2})
+    assert one == two
+    assert one.startswith("evt_")
+
+
+def test_privacy_redacts_secrets_content_and_long_values():
+    privacy = Privacy(max_string_length=4)
+    assert privacy.sanitize("prompt", content=True) == "[REDACTED]"
+    assert privacy.sanitize({"api_key": "abc", "safe": "123456"}) == {
+        "api_key": "[REDACTED]",
+        "safe": "1234…[TRUNCATED]",
+    }
+
+
+def test_run_builds_otlp_tree_without_exporting_content():
+    client = Client(
+        base_url="https://example.invalid",
+        tenant_id="tenant",
+        pipeline_id="pipeline",
+        protocol_token="token",
+        auto_flush_spans=100,
+    )
+    with client.run("agent", run_id="run-1", goal_id="goal-1") as run:
+        with run.span("tool", kind="TOOL") as child:
+            child.set_attribute("tool.arguments", {"password": "secret"}, content=True)
+    payload = client._otlp_payload(client._pending)
+    spans = payload["resourceSpans"][0]["scopeSpans"][0]["spans"]
+    assert len(spans) == 2
+    assert spans[0]["parentSpanId"] == spans[1]["spanId"]
+    encoded = json.dumps(payload)
+    assert "secret" not in encoded
+    assert "[REDACTED]" in encoded
+
+
+def test_integration_attribute_mappings():
+    assert span_attributes("tool")["openinference.span.kind"] == "TOOL"
+    attrs = temporal_attributes(workflow_id="wf", run_id="run", attempt=2)
+    assert attrs["run.id"] == "run"
+    assert attrs["temporal.activity.attempt"] == 2
+