kensa-sdk 0.1.0__tar.gz

kensa_sdk-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+node_modules
+.next
+next-env.d.ts
+out
+coverage
+.env
+.env.local
+.env.*.local
+*.tsbuildinfo
+.DS_Store
+.pnpm-store
+.coverage
+.pytest_cache
+.ruff_cache
+.venv
+__pycache__
+.vercel
+.wrangler/
+.zed
+.specs
+.worktrees
+.codex/
+.claude/
+.agents/
+.env*
+!.env.example

kensa_sdk-0.1.0/LICENSE

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

kensa_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.5
+Name: kensa-sdk
+Version: 0.1.0
+Summary: Thin OpenTelemetry wrapper that exports agent traces to Kensa
+Project-URL: Homepage, https://kensa.sh
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: opentelemetry-api>=1.42.0
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.42.0
+Requires-Dist: opentelemetry-sdk>=1.42.0
+Description-Content-Type: text/markdown
+
+# kensa-sdk
+
+Send your agent's OpenTelemetry traces to [Kensa](https://kensa.sh).
+
+```bash
+pip install kensa-sdk
+```
+
+The package installs as `kensa-sdk` and imports as `kensa`.
+
+## Quick start
+
+```python
+import os
+
+import kensa
+
+kensa.init(api_key=os.environ.get("KENSA_API_KEY"))
+```
+
+Spans are sent in the background. Automatic process-exit cleanup uses OpenTelemetry's
+standard shutdown, which currently waits up to 30 seconds to drain its queue. Slow exports
+can therefore leave queued spans unsent, even though each export allows 120 seconds.
+
+For a finite run, stop producing spans and call `kensa.flush()` before exiting. In a
+serverless function, flush before the response ends. The installed OpenTelemetry processor
+does not enforce an overall flush deadline, so multiple batches can take longer than
+120 seconds to drain.
+
+```python
+kensa.flush()
+```
+
+`kensa.init()` sends spans; your existing instrumentation produces them. Without an API
+key it does nothing and logs a warning, and nothing the SDK does raises into your
+application.
+
+## Already using OpenTelemetry?
+
+`kensa.init()` attaches to the tracer provider your application installed instead of
+replacing it, so call it after that provider is set up. Pass `provider=` if you have
+not registered yours globally:
+
+```python
+kensa.init(api_key=os.environ.get("KENSA_API_KEY"), provider=my_provider)
+```
+
+Your provider's resource is fixed when it is created, so set the service name,
+`service.version`, and `deployment.environment.name` on it yourself, from your
+platform's variables (table below); Kensa logs a warning when the deployment is
+missing. `service_name` only applies when Kensa installs its own provider.
+
+## Configuration
+
+| Setting      | Set with                                         | Default                     |
+| ------------ | ------------------------------------------------ | --------------------------- |
+| API key      | `init(api_key=...)` or `KENSA_API_KEY`           | Required                    |
+| Service name | `init(service_name=...)` or `OTEL_SERVICE_NAME`  | `unknown_service`           |
+| Deployment   | `OTEL_RESOURCE_ATTRIBUTES`                       | Detected from your platform |
+
+Kensa checks a fix against the traces from the deployment that shipped it, so it needs
+the deployed commit and the environment. `kensa.init()` detects them:
+
+| Platform         | Commit                   | Environment                |
+| ---------------- | ------------------------ | -------------------------- |
+| Vercel           | `VERCEL_GIT_COMMIT_SHA`  | `VERCEL_ENV`               |
+| Railway          | `RAILWAY_GIT_COMMIT_SHA` | `RAILWAY_ENVIRONMENT_NAME` |
+| Render           | `RENDER_GIT_COMMIT`      |                            |
+
+On Render, set the environment yourself (below). CI and local runs are never detected
+as a deployment.
+
+Anywhere else, or to override detection, set the standard OpenTelemetry variable:
+
+```bash
+OTEL_RESOURCE_ATTRIBUTES="service.version=<commit sha>,deployment.environment.name=production"
+```
+
+Requires Python 3.12 or later.

kensa_sdk-0.1.0/README.md

@@ -0,0 +1,79 @@
+# kensa-sdk
+
+Send your agent's OpenTelemetry traces to [Kensa](https://kensa.sh).
+
+```bash
+pip install kensa-sdk
+```
+
+The package installs as `kensa-sdk` and imports as `kensa`.
+
+## Quick start
+
+```python
+import os
+
+import kensa
+
+kensa.init(api_key=os.environ.get("KENSA_API_KEY"))
+```
+
+Spans are sent in the background. Automatic process-exit cleanup uses OpenTelemetry's
+standard shutdown, which currently waits up to 30 seconds to drain its queue. Slow exports
+can therefore leave queued spans unsent, even though each export allows 120 seconds.
+
+For a finite run, stop producing spans and call `kensa.flush()` before exiting. In a
+serverless function, flush before the response ends. The installed OpenTelemetry processor
+does not enforce an overall flush deadline, so multiple batches can take longer than
+120 seconds to drain.
+
+```python
+kensa.flush()
+```
+
+`kensa.init()` sends spans; your existing instrumentation produces them. Without an API
+key it does nothing and logs a warning, and nothing the SDK does raises into your
+application.
+
+## Already using OpenTelemetry?
+
+`kensa.init()` attaches to the tracer provider your application installed instead of
+replacing it, so call it after that provider is set up. Pass `provider=` if you have
+not registered yours globally:
+
+```python
+kensa.init(api_key=os.environ.get("KENSA_API_KEY"), provider=my_provider)
+```
+
+Your provider's resource is fixed when it is created, so set the service name,
+`service.version`, and `deployment.environment.name` on it yourself, from your
+platform's variables (table below); Kensa logs a warning when the deployment is
+missing. `service_name` only applies when Kensa installs its own provider.
+
+## Configuration
+
+| Setting      | Set with                                         | Default                     |
+| ------------ | ------------------------------------------------ | --------------------------- |
+| API key      | `init(api_key=...)` or `KENSA_API_KEY`           | Required                    |
+| Service name | `init(service_name=...)` or `OTEL_SERVICE_NAME`  | `unknown_service`           |
+| Deployment   | `OTEL_RESOURCE_ATTRIBUTES`                       | Detected from your platform |
+
+Kensa checks a fix against the traces from the deployment that shipped it, so it needs
+the deployed commit and the environment. `kensa.init()` detects them:
+
+| Platform         | Commit                   | Environment                |
+| ---------------- | ------------------------ | -------------------------- |
+| Vercel           | `VERCEL_GIT_COMMIT_SHA`  | `VERCEL_ENV`               |
+| Railway          | `RAILWAY_GIT_COMMIT_SHA` | `RAILWAY_ENVIRONMENT_NAME` |
+| Render           | `RENDER_GIT_COMMIT`      |                            |
+
+On Render, set the environment yourself (below). CI and local runs are never detected
+as a deployment.
+
+Anywhere else, or to override detection, set the standard OpenTelemetry variable:
+
+```bash
+OTEL_RESOURCE_ATTRIBUTES="service.version=<commit sha>,deployment.environment.name=production"
+```
+
+Requires Python 3.12 or later.

kensa_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kensa-sdk"
+version = "0.1.0"
+description = "Thin OpenTelemetry wrapper that exports agent traces to Kensa"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+dependencies = [
+  "opentelemetry-api>=1.42.0",
+  "opentelemetry-sdk>=1.42.0",
+  "opentelemetry-exporter-otlp-proto-http>=1.42.0",
+]
+
+[project.urls]
+Homepage = "https://kensa.sh"
+
+[dependency-groups]
+dev = ["pytest>=8.0", "ruff>=0.16.4", "ty>=0.0.1a14"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kensa"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
+
+[tool.pytest.ini_options]
+addopts = "--strict-markers"
+testpaths = ["tests"]

kensa_sdk-0.1.0/src/kensa/__init__.py

@@ -0,0 +1,6 @@
+"""Send OpenTelemetry traces to Kensa."""
+
+from kensa.tracing import _VERSION, flush, init
+
+__all__ = ["flush", "init"]
+__version__: str = _VERSION or "unknown"

kensa_sdk-0.1.0/src/kensa/tracing.py

@@ -0,0 +1,197 @@
+"""Send OpenTelemetry spans to Kensa."""
+
+from __future__ import annotations
+
+import logging
+import os
+from collections.abc import Iterator, Mapping
+from contextlib import contextmanager
+from importlib.metadata import PackageNotFoundError, version
+from typing import Final
+
+from opentelemetry import trace
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import SpanProcessor, TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+__all__ = ["flush", "init"]
+
+_LOGGER = logging.getLogger("kensa")
+_DEFAULT_ENDPOINT: Final = "https://ingest.kensa.sh/v1/traces"
+# Ingest accepts at most 4 MiB per request and GenAI spans carry whole prompts, so
+# batches stay far below the exporter's default of 512 spans.
+_MAX_EXPORT_BATCH_SIZE: Final = 24
+_IDENTITY_KEYS: Final = ("service.version", "deployment.environment.name")
+
+# Full commit SHAs that hosting platforms expose at runtime. Kensa matches a reported
+# fix's commit against the service.version of later traces. Deploy platforms only: CI
+# and local runs must never pass for production traffic.
+_COMMIT_VARIABLES: Final = (
+    "VERCEL_GIT_COMMIT_SHA",
+    "RENDER_GIT_COMMIT",
+    "RAILWAY_GIT_COMMIT_SHA",
+)
+_ENVIRONMENT_VARIABLES: Final = ("VERCEL_ENV", "RAILWAY_ENVIRONMENT_NAME")
+_ENVIRONMENT_KEYS: Final = ("deployment.environment.name", "deployment.environment")
+_FOREIGN_EXPORTER_PREFIXES: Final = ("OTEL_EXPORTER_OTLP_", "OTEL_PYTHON_EXPORTER_OTLP_")
+_DEFAULT_MAX_QUEUE_SIZE: Final = 2048
+
+
+def _package_version() -> str | None:
+    # pyproject.toml is the only place the version is written; installing stamps it into
+    # the package metadata. Frozen or vendored copies may lack that metadata.
+    try:
+        return version("kensa-sdk")
+    except PackageNotFoundError:
+        return None
+
+
+_VERSION: Final = _package_version()
+
+_processor: SpanProcessor | None = None
+_warned_missing_key = False
+
+
+def _first(env: Mapping[str, str], names: tuple[str, ...]) -> str | None:
+    for name in names:
+        value = env.get(name, "").strip()
+        if value:
+            return value
+    return None
+
+
+def _detected_attributes(env: Mapping[str, str]) -> dict[str, str]:
+    attributes: dict[str, str] = {}
+    if commit := _first(env, _COMMIT_VARIABLES):
+        attributes["service.version"] = commit
+    if environment := _first(env, _ENVIRONMENT_VARIABLES):
+        # Both spellings: semantic conventions renamed the attribute, and Kensa prefers
+        # the new one.
+        attributes["deployment.environment.name"] = environment
+        attributes["deployment.environment"] = environment
+    return attributes
+
+
+def _resource(service_name: str | None, env: Mapping[str, str]) -> Resource:
+    # Detected values, overridden by OTEL_SERVICE_NAME and OTEL_RESOURCE_ATTRIBUTES
+    # (which Resource.create reads), overridden by an explicit service name.
+    explicit: dict[str, str] = {"service.name": service_name} if service_name else {}
+    configured = Resource.create(explicit)
+    detected = _detected_attributes(env)
+    # An environment set through OTEL_RESOURCE_ATTRIBUTES, in either spelling, replaces
+    # the detected one entirely rather than leaving the two spellings disagreeing.
+    if any(key in configured.attributes for key in _ENVIRONMENT_KEYS):
+        for key in _ENVIRONMENT_KEYS:
+            detected.pop(key, None)
+    resource = Resource(detected).merge(configured)
+    if _VERSION:
+        resource = resource.merge(Resource({"kensa.instrumentation.version": _VERSION}))
+    return resource
+
+
+@contextmanager
+def _without_otlp_environment() -> Iterator[None]:
+    # OTLPSpanExporter reads OTEL_EXPORTER_OTLP_* (certificates, client keys, timeout) and
+    # a credential-provider session when constructed. Those belong to whatever other
+    # backend the application exports to, so hide them while Kensa's exporter is built.
+    hidden = {k: v for k, v in os.environ.items() if k.startswith(_FOREIGN_EXPORTER_PREFIXES)}
+    for name in hidden:
+        del os.environ[name]
+    try:
+        yield
+    finally:
+        os.environ.update(hidden)
+
+
+def _batch_size() -> int:
+    # BatchSpanProcessor rejects a batch larger than its queue, so honour a smaller one.
+    try:
+        queue = int(os.environ.get("OTEL_BSP_MAX_QUEUE_SIZE", _DEFAULT_MAX_QUEUE_SIZE))
+    except ValueError:
+        queue = _DEFAULT_MAX_QUEUE_SIZE
+    return max(1, min(_MAX_EXPORT_BATCH_SIZE, queue))
+
+
+def _warn_missing_key() -> None:
+    global _warned_missing_key
+    if not _warned_missing_key:
+        _warned_missing_key = True
+        _LOGGER.warning("KENSA_API_KEY is not set, so no traces are sent to Kensa.")
+
+
+def _warn_missing_identity(provider: TracerProvider) -> None:
+    attributes = provider.resource.attributes
+    missing = [key for key in _IDENTITY_KEYS if not attributes.get(key)]
+    if missing:
+        _LOGGER.warning(
+            "Kensa attached to this application's tracer provider and cannot set %s on "
+            "it. Add them to your own Resource so Kensa can tell which deployment a fix "
+            "shipped in.",
+            ", ".join(missing),
+        )
+
+
+def init(
+    *,
+    api_key: str | None = None,
+    service_name: str | None = None,
+    provider: TracerProvider | None = None,
+) -> None:
+    """Start sending this process's traces to Kensa.
+
+    Only the first call with an API key (``api_key`` or ``KENSA_API_KEY``) takes
+    effect. Attaches to the application's tracer provider if it has one, or to
+    ``provider`` if given; otherwise installs its own. Call it after any code that sets
+    up a tracer provider, or that provider cannot be installed.
+    """
+    global _processor
+    if _processor is not None:
+        return
+    key = api_key or os.environ.get("KENSA_API_KEY")
+    if not key:
+        _warn_missing_key()
+        return
+
+    try:
+        with _without_otlp_environment():
+            exporter = OTLPSpanExporter(
+                endpoint=os.environ.get("KENSA_ENDPOINT") or _DEFAULT_ENDPOINT,
+                headers={"authorization": f"Bearer {key}"},
+                # Ingest redacts prompt-rich batches before acknowledging them.
+                timeout=120,
+            )
+        processor = BatchSpanProcessor(exporter, max_export_batch_size=_batch_size())
+        existing = provider if provider is not None else trace.get_tracer_provider()
+        if isinstance(existing, TracerProvider):
+            existing.add_span_processor(processor)
+            _warn_missing_identity(existing)
+        else:
+            # Keep OpenTelemetry's default automatic shutdown and its drain deadline.
+            installed = TracerProvider(resource=_resource(service_name, os.environ))
+            installed.add_span_processor(processor)
+            trace.set_tracer_provider(installed)
+            if trace.get_tracer_provider() is not installed:
+                # Another vendor's non-SDK provider holds the global slot and cannot take
+                # Kensa's processor.
+                processor.shutdown()
+                _LOGGER.error(
+                    "Another tracer provider is registered and Kensa cannot attach to it. "
+                    "Pass your OpenTelemetry SDK TracerProvider as kensa.init(provider=...)."
+                )
+                return
+    except Exception as error:  # Instrumentation must never break the application.
+        _LOGGER.warning("Not sending traces to Kensa: %s", error)
+        return
+    _processor = processor
+
+
+def flush() -> None:
+    """Send any buffered spans now.
+
+    Call after span production stops, including before a serverless response. Automatic
+    shutdown uses OpenTelemetry's default deadline and may drop slow batches. The installed
+    processor does not enforce an overall flush deadline. A failed send is logged.
+    """
+    if _processor is not None and not _processor.force_flush(timeout_millis=120_000):
+        _LOGGER.warning("Some spans could not be sent to Kensa.")