servicedna 0.1.0__tar.gz

servicedna-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+*.pyc
+.venv/
+dist/

servicedna-0.1.0/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.5
+Name: servicedna
+Version: 0.1.0
+Summary: Connect a Python service to ServiceDNA: traces, self-registration and health heartbeats with two environment variables.
+Project-URL: Source, https://github.com/varuns2903/servicedna/tree/main/sdks/python
+License-Expression: MIT
+Requires-Python: >=3.9
+Requires-Dist: opentelemetry-api~=1.45
+Requires-Dist: opentelemetry-exporter-otlp-proto-http~=1.45
+Requires-Dist: opentelemetry-instrumentation-aiohttp-client==0.66b0
+Requires-Dist: opentelemetry-instrumentation-asgi==0.66b0
+Requires-Dist: opentelemetry-instrumentation-confluent-kafka==0.66b0
+Requires-Dist: opentelemetry-instrumentation-django==0.66b0
+Requires-Dist: opentelemetry-instrumentation-fastapi==0.66b0
+Requires-Dist: opentelemetry-instrumentation-flask==0.66b0
+Requires-Dist: opentelemetry-instrumentation-grpc==0.66b0
+Requires-Dist: opentelemetry-instrumentation-httpx==0.66b0
+Requires-Dist: opentelemetry-instrumentation-kafka-python==0.66b0
+Requires-Dist: opentelemetry-instrumentation-psycopg2==0.66b0
+Requires-Dist: opentelemetry-instrumentation-redis==0.66b0
+Requires-Dist: opentelemetry-instrumentation-requests==0.66b0
+Requires-Dist: opentelemetry-instrumentation-sqlalchemy==0.66b0
+Requires-Dist: opentelemetry-instrumentation-urllib3==0.66b0
+Requires-Dist: opentelemetry-instrumentation-wsgi==0.66b0
+Requires-Dist: opentelemetry-instrumentation==0.66b0
+Requires-Dist: opentelemetry-sdk~=1.45
+Provides-Extra: test
+Requires-Dist: fastapi; extra == 'test'
+Requires-Dist: grpcio; extra == 'test'
+Requires-Dist: grpcio-health-checking; extra == 'test'
+Requires-Dist: httpx; extra == 'test'
+Requires-Dist: pytest; extra == 'test'
+Requires-Dist: pytest-asyncio; extra == 'test'
+Requires-Dist: uvicorn; extra == 'test'
+Description-Content-Type: text/markdown
+
+# servicedna (Python)
+
+Connect a Python service to [ServiceDNA](https://github.com/varuns2903/servicedna) with one
+dependency and two environment variables. You get:
+
+- **Distributed traces** for FastAPI, Flask, Django, ASGI/WSGI, requests, httpx, urllib3,
+  aiohttp, gRPC, SQLAlchemy, psycopg2, Redis and Kafka (OpenTelemetry auto-instrumentation —
+  only libraries you actually use are instrumented)
+- **Self-registration** — the service appears in ServiceDNA on first start
+- **Health heartbeats** — the service's own `/health` is checked and reported every 15 s
+
+## Install
+
+```bash
+pip install servicedna
+```
+
+## Run
+
+Prefix your usual command with `servicedna-run`:
+
+```bash
+SERVICEDNA_URL=https://servicedna.example.com \
+SERVICEDNA_KEY=sdna_ik_... \
+servicedna-run uvicorn app.main:app --host 0.0.0.0 --port 8000
+```
+
+Or start it from code, first thing in your entry point:
+
+```python
+import servicedna
+servicedna.start()
+```
+
+`servicedna-run` is preferred: it instruments libraries before your code imports them. Without
+`SERVICEDNA_URL` and `SERVICEDNA_KEY` both do nothing, so the same build runs anywhere.
+
+## Configuration
+
+| Variable | Default | |
+|---|---|---|
+| `SERVICEDNA_URL` | — | ServiceDNA base URL (required) |
+| `SERVICEDNA_KEY` | — | Organization ingestion key, from Settings → Integrations (required) |
+| `SERVICEDNA_ENV` | — | Environment (`dev`, `staging`, `prod`…); each is tracked separately |
+| `OTEL_SERVICE_NAME` / `SERVICEDNA_SERVICE` | working directory name | Service name |
+| `SERVICEDNA_VERSION` | — | |
+| `SERVICEDNA_HEALTH_URL` | — | Health URL **ServiceDNA** can reach, so it can also probe the service itself |
+| `SERVICEDNA_HEALTH_PATH` | `/health` | Path the heartbeat checks on `http://127.0.0.1:$PORT` |
+| `SERVICEDNA_LOCAL_HEALTH_URL` | from `PORT` + path | Full URL the heartbeat checks, if not on `PORT` |
+| `SERVICEDNA_HEARTBEAT_MS` | `15000` | `0` disables heartbeats |
+| `SERVICEDNA_DEGRADED_MS` | `2000` | Health response slower than this is reported DEGRADED |
+
+Standard `OTEL_*` variables still apply and win over these defaults.

servicedna-0.1.0/README.md

@@ -0,0 +1,53 @@
+# servicedna (Python)
+
+Connect a Python service to [ServiceDNA](https://github.com/varuns2903/servicedna) with one
+dependency and two environment variables. You get:
+
+- **Distributed traces** for FastAPI, Flask, Django, ASGI/WSGI, requests, httpx, urllib3,
+  aiohttp, gRPC, SQLAlchemy, psycopg2, Redis and Kafka (OpenTelemetry auto-instrumentation —
+  only libraries you actually use are instrumented)
+- **Self-registration** — the service appears in ServiceDNA on first start
+- **Health heartbeats** — the service's own `/health` is checked and reported every 15 s
+
+## Install
+
+```bash
+pip install servicedna
+```
+
+## Run
+
+Prefix your usual command with `servicedna-run`:
+
+```bash
+SERVICEDNA_URL=https://servicedna.example.com \
+SERVICEDNA_KEY=sdna_ik_... \
+servicedna-run uvicorn app.main:app --host 0.0.0.0 --port 8000
+```
+
+Or start it from code, first thing in your entry point:
+
+```python
+import servicedna
+servicedna.start()
+```
+
+`servicedna-run` is preferred: it instruments libraries before your code imports them. Without
+`SERVICEDNA_URL` and `SERVICEDNA_KEY` both do nothing, so the same build runs anywhere.
+
+## Configuration
+
+| Variable | Default | |
+|---|---|---|
+| `SERVICEDNA_URL` | — | ServiceDNA base URL (required) |
+| `SERVICEDNA_KEY` | — | Organization ingestion key, from Settings → Integrations (required) |
+| `SERVICEDNA_ENV` | — | Environment (`dev`, `staging`, `prod`…); each is tracked separately |
+| `OTEL_SERVICE_NAME` / `SERVICEDNA_SERVICE` | working directory name | Service name |
+| `SERVICEDNA_VERSION` | — | |
+| `SERVICEDNA_HEALTH_URL` | — | Health URL **ServiceDNA** can reach, so it can also probe the service itself |
+| `SERVICEDNA_HEALTH_PATH` | `/health` | Path the heartbeat checks on `http://127.0.0.1:$PORT` |
+| `SERVICEDNA_LOCAL_HEALTH_URL` | from `PORT` + path | Full URL the heartbeat checks, if not on `PORT` |
+| `SERVICEDNA_HEARTBEAT_MS` | `15000` | `0` disables heartbeats |
+| `SERVICEDNA_DEGRADED_MS` | `2000` | Health response slower than this is reported DEGRADED |
+
+Standard `OTEL_*` variables still apply and win over these defaults.

servicedna-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "servicedna"
+version = "0.1.0"
+description = "Connect a Python service to ServiceDNA: traces, self-registration and health heartbeats with two environment variables."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+dependencies = [
+  "opentelemetry-api~=1.45",
+  "opentelemetry-sdk~=1.45",
+  "opentelemetry-exporter-otlp-proto-http~=1.45",
+  "opentelemetry-instrumentation==0.66b0",
+  # Instrumentations only activate when their library is installed, so the common ones ship by default.
+  "opentelemetry-instrumentation-asgi==0.66b0",
+  "opentelemetry-instrumentation-wsgi==0.66b0",
+  "opentelemetry-instrumentation-fastapi==0.66b0",
+  "opentelemetry-instrumentation-flask==0.66b0",
+  "opentelemetry-instrumentation-django==0.66b0",
+  "opentelemetry-instrumentation-requests==0.66b0",
+  "opentelemetry-instrumentation-httpx==0.66b0",
+  "opentelemetry-instrumentation-urllib3==0.66b0",
+  "opentelemetry-instrumentation-aiohttp-client==0.66b0",
+  "opentelemetry-instrumentation-grpc==0.66b0",
+  "opentelemetry-instrumentation-sqlalchemy==0.66b0",
+  "opentelemetry-instrumentation-psycopg2==0.66b0",
+  "opentelemetry-instrumentation-redis==0.66b0",
+  "opentelemetry-instrumentation-kafka-python==0.66b0",
+  "opentelemetry-instrumentation-confluent-kafka==0.66b0",
+]
+
+[project.optional-dependencies]
+test = ["pytest", "pytest-asyncio", "fastapi", "httpx", "uvicorn", "grpcio", "grpcio-health-checking"]
+
+[project.urls]
+Source = "https://github.com/varuns2903/servicedna/tree/main/sdks/python"
+
+[project.scripts]
+servicedna-run = "servicedna.run:main"
+
+[project.entry-points.opentelemetry_distro]
+servicedna = "servicedna.distro:ServiceDnaDistro"
+
+[project.entry-points.opentelemetry_configurator]
+servicedna = "servicedna.distro:ServiceDnaConfigurator"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/servicedna"]

servicedna-0.1.0/src/servicedna/__init__.py

@@ -0,0 +1,40 @@
+"""ServiceDNA SDK for Python.
+
+Run a program with telemetry (recommended — instruments libraries before they're imported):
+
+    servicedna-run uvicorn app.main:app
+
+Or start it from code, first thing in your entry point:
+
+    import servicedna
+    servicedna.start()
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+
+from . import config as _config
+from .bodies import capture, tag
+
+__all__ = ["start", "capture", "tag"]
+__version__ = "0.1.0"
+
+log = logging.getLogger("servicedna")
+
+
+def start() -> bool:
+    """Configures tracing, instruments installed libraries, and starts heartbeats. Returns False
+    (and does nothing) when SERVICEDNA_URL and SERVICEDNA_KEY aren't set."""
+    cfg = _config.resolve()
+    if not cfg.enabled:
+        log.warning("[servicedna] SERVICEDNA_URL and SERVICEDNA_KEY are not set; not sending telemetry")
+        return False
+    for key, value in _config.otel_environment(cfg).items():
+        os.environ.setdefault(key, value)
+
+    from opentelemetry.instrumentation.auto_instrumentation import initialize
+
+    initialize()  # loads the servicedna distro (which starts the heartbeat) and configurator
+    return True

servicedna-0.1.0/src/servicedna/bodies.py

@@ -0,0 +1,127 @@
+"""Request/response body capture for ServiceDNA. Requests carrying the baggage entry
+``sdna.capture=1`` (test runs) are always captured. With ``SERVICEDNA_CAPTURE_ON_ERROR=true``,
+every other request's bodies are held until its response and recorded only if it failed (5xx) —
+successful traffic ships no payloads. Bodies are masked and truncated before being recorded on the
+request's server span."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+
+from opentelemetry import baggage, trace
+
+MAX_BYTES = int(os.getenv("SERVICEDNA_CAPTURE_MAX_BYTES", "16384"))
+_SENSITIVE = re.compile(r"pass(word|wd)?|secret|token|api[-_.]?key|authorization|cookie|session|card|cvv|ssn", re.I)
+_SCOPE_KEY = "servicedna.capture"
+
+
+def capture_on_error() -> bool:
+    return os.getenv("SERVICEDNA_CAPTURE_ON_ERROR", "").lower() in ("1", "true", "yes")
+
+
+def capture_requested() -> bool:
+    return baggage.get_baggage("sdna.capture") == "1"
+
+
+def redact(text: str) -> str:
+    """Masks credential-like fields in JSON; other text is kept. Always truncates."""
+    try:
+        text = json.dumps(_mask(json.loads(text)), separators=(",", ":"))
+    except (ValueError, TypeError):
+        pass
+    return text if len(text) <= MAX_BYTES else text[:MAX_BYTES] + "…[truncated]"
+
+
+def _mask(value):
+    if isinstance(value, dict):
+        return {k: "[masked]" if _SENSITIVE.search(str(k)) else _mask(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_mask(v) for v in value]
+    return value
+
+
+def capture(name: str, value) -> None:
+    """Records a value computed inside the service on the current span, for test runs:
+    ``servicedna.capture("order.total", total)``. Does nothing outside a capture run."""
+    if not capture_requested():
+        return
+    span = trace.get_current_span()
+    if span.is_recording():
+        text = value if isinstance(value, str) else json.dumps(value, default=str)
+        span.set_attribute(f"sdna.capture.{name}", redact(text))
+
+
+def tag(name: str, value) -> None:
+    """Tags the current span with a business key, so ServiceDNA can follow it across services,
+    traces and logs — even where trace context was lost: ``servicedna.tag("orderId", order_id)``.
+    Unlike capture(), it applies to all traffic; use ids, not personal data."""
+    if value is None:
+        return
+    span = trace.get_current_span()
+    if span.is_recording():
+        span.set_attribute(f"sdna.key.{name}", str(value))
+
+
+# ASGI instrumentation hooks (FastAPI, Starlette). The receive/send hooks run on the
+# instrumentation's own receive/send spans, so the server span is remembered on the ASGI scope.
+
+
+def server_request_hook(span, scope):
+    if span is None or not span.is_recording():
+        return
+    if capture_requested():
+        scope[_SCOPE_KEY] = {"span": span, "on_error": False, "status": None, "request": bytearray(), "response": bytearray()}
+    elif capture_on_error():
+        scope[_SCOPE_KEY] = {"span": span, "on_error": True, "status": None, "request": bytearray(), "response": bytearray()}
+
+
+def client_request_hook(span, scope, message):
+    state = scope.get(_SCOPE_KEY)
+    if state is not None and message.get("type") == "http.request":
+        _append(state["request"], message.get("body", b""))
+
+
+def client_response_hook(span, scope, message):
+    state = scope.get(_SCOPE_KEY)
+    if state is None:
+        return
+    if message.get("type") == "http.response.start":
+        state["status"] = message.get("status")
+        return
+    if message.get("type") != "http.response.body":
+        return
+    _append(state["response"], message.get("body", b""))
+    if not message.get("more_body", False):
+        scope.pop(_SCOPE_KEY, None)
+        server_span = state["span"]
+        if state["on_error"]:
+            if (state["status"] or 0) < 500:
+                return
+            server_span.set_attribute("sdna.captured_on_error", True)
+        else:
+            server_span.set_attribute("sdna.captured", True)
+        if state["request"]:
+            server_span.set_attribute("sdna.request.body", redact(state["request"].decode("utf-8", "replace")))
+        if state["response"]:
+            server_span.set_attribute("sdna.response.body", redact(state["response"].decode("utf-8", "replace")))
+
+
+def _append(buffer: bytearray, chunk: bytes) -> None:
+    if chunk and len(buffer) <= MAX_BYTES:
+        buffer.extend(chunk)
+
+
+def instrument_fastapi() -> bool:
+    """Instruments FastAPI with body capture. Returns False if FastAPI instrumentation isn't installed."""
+    try:
+        from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor
+    except ImportError:
+        return False
+    FastAPIInstrumentor().instrument(
+        server_request_hook=server_request_hook,
+        client_request_hook=client_request_hook,
+        client_response_hook=client_response_hook,
+    )
+    return True

servicedna-0.1.0/src/servicedna/config.py

@@ -0,0 +1,88 @@
+"""Resolves SDK settings from environment variables. Only SERVICEDNA_URL and SERVICEDNA_KEY are
+required; everything else has a default."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Mapping, Optional
+
+
+@dataclass(frozen=True)
+class Config:
+    url: str
+    key: str
+    service_name: str
+    environment: Optional[str]
+    version: Optional[str]
+    health_url: Optional[str]  # what ServiceDNA probes; only reported when set
+    local_health_url: Optional[str]  # what the heartbeat checks, over loopback
+    heartbeat_seconds: float
+    degraded_ms: int
+    logs: bool = True  # SERVICEDNA_LOGS=false stops sending the logging module's records
+
+    @property
+    def enabled(self) -> bool:
+        return bool(self.url and self.key)
+
+
+def resolve(env: Mapping[str, str] = os.environ) -> Config:
+    port = env.get("PORT")
+    health_path = env.get("SERVICEDNA_HEALTH_PATH", "/health")
+    return Config(
+        url=env.get("SERVICEDNA_URL", "").rstrip("/"),
+        key=env.get("SERVICEDNA_KEY", ""),
+        service_name=env.get("OTEL_SERVICE_NAME") or env.get("SERVICEDNA_SERVICE") or _default_service_name(),
+        environment=env.get("SERVICEDNA_ENV") or None,
+        version=env.get("SERVICEDNA_VERSION") or None,
+        health_url=env.get("SERVICEDNA_HEALTH_URL") or None,
+        local_health_url=env.get("SERVICEDNA_LOCAL_HEALTH_URL")
+        or (f"http://127.0.0.1:{port}{health_path}" if port else None),
+        heartbeat_seconds=int(env.get("SERVICEDNA_HEARTBEAT_MS", "15000")) / 1000,
+        degraded_ms=int(env.get("SERVICEDNA_DEGRADED_MS", "2000")),
+        logs=env.get("SERVICEDNA_LOGS", "true").lower() not in ("0", "false", "no", "off"),
+    )
+
+
+def _default_service_name() -> str:
+    return os.path.basename(os.getcwd()) or "unknown_service:python"
+
+
+def otel_environment(config: Config) -> dict:
+    """The OTEL_* settings that send this service's traces and logs to ServiceDNA. Values the user already
+    set are respected by the caller (setdefault), so standard OpenTelemetry configuration still
+    works."""
+    attributes = [f"telemetry.sdk.language=python"]
+    if config.environment:
+        attributes.append(f"deployment.environment.name={config.environment}")
+    if config.version:
+        attributes.append(f"service.version={config.version}")
+    if config.health_url:
+        attributes.append(f"servicedna.health.url={config.health_url}")
+    excluded = [config.local_health_url.split("://", 1)[1].split("/", 1)[1]] if config.local_health_url else []
+    logs = (
+        {
+            # Records from the logging module, with the active trace and span ids.
+            "OTEL_LOGS_EXPORTER": "otlp",
+            "OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED": "true",
+            "OTEL_EXPORTER_OTLP_LOGS_PROTOCOL": "http/protobuf",
+            "OTEL_EXPORTER_OTLP_LOGS_ENDPOINT": f"{config.url}/api/v1/otlp/v1/logs",
+            "OTEL_EXPORTER_OTLP_LOGS_HEADERS": f"x-servicedna-key={config.key}",
+        }
+        if config.logs
+        else {"OTEL_LOGS_EXPORTER": "none"}
+    )
+    return {
+        "OTEL_SERVICE_NAME": config.service_name,
+        "OTEL_RESOURCE_ATTRIBUTES": ",".join(attributes),
+        "OTEL_TRACES_EXPORTER": "otlp",
+        "OTEL_METRICS_EXPORTER": "none",
+        **logs,
+        "OTEL_EXPORTER_OTLP_TRACES_PROTOCOL": "http/protobuf",
+        "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT": f"{config.url}/api/v1/otlp/v1/traces",
+        "OTEL_EXPORTER_OTLP_TRACES_HEADERS": f"x-servicedna-key={config.key}",
+        # Health probes (ServiceDNA's and the heartbeat's) aren't traffic worth tracing.
+        "OTEL_PYTHON_EXCLUDED_URLS": ",".join(f"/{path}" for path in excluded),
+        "OTEL_PYTHON_DISTRO": "servicedna",
+        "OTEL_PYTHON_CONFIGURATOR": "servicedna",
+    }

servicedna-0.1.0/src/servicedna/distro.py

@@ -0,0 +1,61 @@
+"""OpenTelemetry distro and configurator entry points, selected by OTEL_PYTHON_DISTRO /
+OTEL_PYTHON_CONFIGURATOR=servicedna (set by servicedna-run and servicedna.start)."""
+
+from __future__ import annotations
+
+import logging
+import os
+
+from opentelemetry.instrumentation.distro import BaseDistro
+from opentelemetry.sdk._configuration import _OTelSDKConfigurator
+
+from . import bodies as _bodies
+from . import grpc_capture as _grpc_capture
+from . import config as _config
+from . import heartbeat
+
+
+class ServiceDnaDistro(BaseDistro):
+    def _configure(self, **kwargs):
+        cfg = _config.resolve()
+        if not cfg.enabled:
+            return
+        for key, value in _config.otel_environment(cfg).items():
+            os.environ.setdefault(key, value)
+        # FastAPI is instrumented here, with body-capture hooks, instead of by auto-instrumentation.
+        if _bodies.instrument_fastapi():
+            disabled = [d for d in os.environ.get("OTEL_PYTHON_DISABLED_INSTRUMENTATIONS", "").split(",") if d]
+            os.environ["OTEL_PYTHON_DISABLED_INSTRUMENTATIONS"] = ",".join(disabled + ["fastapi"])
+        # gRPC request/response messages, for test runs (and failures with capture on error).
+        _grpc_capture.install()
+        if cfg.logs:
+            _bridge_uvicorn_logs()
+        heartbeat.start(cfg)
+
+
+def _bridge_uvicorn_logs() -> None:
+    """uvicorn's loggers don't propagate to the root logger, where OpenTelemetry's handler sits.
+    Once uvicorn has configured logging, its "uvicorn" logger (startup, errors and tracebacks —
+    not per-request access lines, which spans already cover) gets that handler too."""
+    try:
+        import uvicorn.config
+    except ImportError:
+        return
+    original = uvicorn.config.Config.configure_logging
+    if getattr(original, "_servicedna", False):
+        return
+
+    def configure_logging(self):
+        original(self)
+        handlers = [h for h in logging.getLogger().handlers if type(h).__name__ == "LoggingHandler"]
+        target = logging.getLogger("uvicorn")
+        for handler in handlers:
+            if handler not in target.handlers:
+                target.addHandler(handler)
+
+    configure_logging._servicedna = True
+    uvicorn.config.Config.configure_logging = configure_logging
+
+
+class ServiceDnaConfigurator(_OTelSDKConfigurator):
+    """The standard OpenTelemetry SDK setup (tracer provider, batch span processor, exporter)."""

servicedna-0.1.0/src/servicedna/grpc_capture.py

@@ -0,0 +1,127 @@
+"""gRPC message capture: the request and response messages of unary calls a service handles,
+recorded on its server span as JSON (masked and truncated like HTTP bodies) — for ServiceDNA test
+runs (baggage ``sdna.capture=1``), and for failed calls with ``SERVICEDNA_CAPTURE_ON_ERROR=true``.
+
+Installed by the distro: servers made with ``grpc.server`` / ``grpc.aio.server`` get the
+interceptor after OpenTelemetry's, so the server span and the caller's baggage are current."""
+
+from __future__ import annotations
+
+import functools
+
+from opentelemetry import trace
+
+from .bodies import capture_on_error, capture_requested, redact
+
+
+def _json(message) -> str:
+    try:
+        from google.protobuf.json_format import MessageToJson
+
+        return MessageToJson(message, preserving_proto_field_name=True, indent=None)
+    except Exception:  # not a protobuf message
+        return str(message)
+
+
+def _record(span, request, response, requested: bool) -> None:
+    if not span.is_recording():
+        return
+    span.set_attribute("sdna.request.body", redact(_json(request)))
+    if response is not None:
+        span.set_attribute("sdna.response.body", redact(_json(response)))
+    span.set_attribute("sdna.captured" if requested else "sdna.captured_on_error", True)
+
+
+def _wrap_handler(handler, aio: bool):
+    import grpc
+
+    if handler is None or handler.unary_unary is None:
+        return handler  # streaming calls aren't captured
+    behavior = handler.unary_unary
+
+    if aio:
+
+        async def unary_unary(request, context):
+            requested = capture_requested()
+            if not requested and not capture_on_error():
+                return await behavior(request, context)
+            span = trace.get_current_span()
+            try:
+                response = await behavior(request, context)
+            except BaseException:
+                _record(span, request, None, requested)
+                raise
+            if requested:
+                _record(span, request, response, True)
+            return response
+
+    else:
+
+        def unary_unary(request, context):
+            requested = capture_requested()
+            if not requested and not capture_on_error():
+                return behavior(request, context)
+            span = trace.get_current_span()
+            try:
+                response = behavior(request, context)
+            except BaseException:
+                _record(span, request, None, requested)
+                raise
+            if requested:
+                _record(span, request, response, True)
+            return response
+
+    return grpc.unary_unary_rpc_method_handler(
+        unary_unary, request_deserializer=handler.request_deserializer, response_serializer=handler.response_serializer
+    )
+
+
+def server_interceptor():
+    import grpc
+
+    class CaptureInterceptor(grpc.ServerInterceptor):
+        def intercept_service(self, continuation, handler_call_details):
+            return _wrap_handler(continuation(handler_call_details), aio=False)
+
+    return CaptureInterceptor()
+
+
+def aio_server_interceptor():
+    import grpc.aio
+
+    class AioCaptureInterceptor(grpc.aio.ServerInterceptor):
+        async def intercept_service(self, continuation, handler_call_details):
+            return _wrap_handler(await continuation(handler_call_details), aio=True)
+
+    return AioCaptureInterceptor()
+
+
+def install() -> bool:
+    """Adds the capture interceptor to every gRPC server made from now on. False without grpcio."""
+    try:
+        import grpc
+        import grpc.aio
+    except ImportError:
+        return False
+    if getattr(grpc.server, "_servicedna", False):
+        return True
+
+    def patch(module, name, make):
+        original = getattr(module, name)
+
+        @functools.wraps(original)
+        def server(*args, **kwargs):
+            interceptors = list(kwargs.pop("interceptors", None) or [])
+            # grpc.server(thread_pool, handlers, interceptors, ...) also takes them positionally.
+            if module is grpc and len(args) >= 3:
+                interceptors = list(args[2] or []) + interceptors
+                args = args[:2] + args[3:]
+            interceptors.append(make())
+            return original(*args, interceptors=interceptors, **kwargs)
+
+        server._servicedna = True
+        setattr(module, name, server)
+
+    patch(grpc, "server", server_interceptor)
+    patch(grpc.aio, "server", aio_server_interceptor)
+    return True

servicedna-0.1.0/src/servicedna/heartbeat.py

@@ -0,0 +1,84 @@
+"""Checks the service's own health endpoint on an interval and reports the result to ServiceDNA,
+which registers the service on first contact. Its HTTP calls are made with tracing suppressed so
+heartbeats don't show up as the service's traffic."""
+
+from __future__ import annotations
+
+import json
+import logging
+import threading
+import time
+import urllib.error
+import urllib.request
+
+from opentelemetry import context
+
+from .config import Config
+
+log = logging.getLogger("servicedna")
+_started = False
+
+
+def start(config: Config) -> None:
+    global _started
+    if _started or not config.local_health_url or config.heartbeat_seconds <= 0:
+        return
+    _started = True
+    thread = threading.Thread(target=_loop, args=(config,), name="servicedna-heartbeat", daemon=True)
+    thread.start()
+
+
+def _loop(config: Config) -> None:
+    while True:
+        time.sleep(config.heartbeat_seconds)
+        token = context.attach(context.set_value(context._SUPPRESS_INSTRUMENTATION_KEY, True))
+        try:
+            _beat(config)
+        except Exception as e:  # never let the heartbeat thread die
+            log.warning("[servicedna] heartbeat failed: %s", e)
+        finally:
+            context.detach(token)
+
+
+def _beat(config: Config) -> None:
+    start = time.monotonic()
+    status, message = "DOWN", "health check failed"
+    try:
+        with urllib.request.urlopen(config.local_health_url, timeout=5) as res:
+            body = res.read()
+            elapsed_ms = (time.monotonic() - start) * 1000
+            status = "DEGRADED" if elapsed_ms > config.degraded_ms else "HEALTHY"
+            message = _message(body) or f"HTTP {res.status}"
+    except urllib.error.HTTPError as e:
+        message = _message(e.read()) or f"HTTP {e.code}"
+    except Exception as e:
+        message = str(e) or type(e).__name__
+    latency_ms = int((time.monotonic() - start) * 1000)
+
+    payload = json.dumps(
+        {
+            "status": status,
+            "latencyMs": latency_ms,
+            "message": message[:500],
+            "service": config.service_name,
+            "environment": config.environment,
+        }
+    ).encode()
+    request = urllib.request.Request(
+        f"{config.url}/api/v1/ping",
+        data=payload,
+        headers={"Content-Type": "application/json", "X-API-Key": config.key},
+        method="POST",
+    )
+    try:
+        urllib.request.urlopen(request, timeout=5).close()
+    except urllib.error.HTTPError as e:
+        log.warning("[servicedna] heartbeat rejected: HTTP %s", e.code)
+
+
+def _message(body: bytes):
+    try:
+        data = json.loads(body)
+        return str(data.get("message") or data.get("status") or "") or None
+    except (ValueError, AttributeError):
+        return None

servicedna-0.1.0/src/servicedna/run.py

@@ -0,0 +1,32 @@
+"""servicedna-run: run a Python program with ServiceDNA telemetry, e.g.
+
+    SERVICEDNA_URL=... SERVICEDNA_KEY=sdna_ik_... servicedna-run uvicorn app.main:app
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+from . import config as _config
+
+
+def main() -> None:
+    cfg = _config.resolve()
+    if not cfg.enabled:
+        print("[servicedna] SERVICEDNA_URL and SERVICEDNA_KEY are not set; not sending telemetry", file=sys.stderr)
+    else:
+        for key, value in _config.otel_environment(cfg).items():
+            os.environ.setdefault(key, value)
+        print(
+            f"[servicedna] sending {cfg.service_name}"
+            + (f" ({cfg.environment})" if cfg.environment else "")
+            + f" telemetry to {cfg.url}",
+            file=sys.stderr,
+        )
+
+    # Same mechanism as opentelemetry-instrument: re-executes the command with auto-instrumentation
+    # loaded via sitecustomize, which picks up the servicedna distro and configurator.
+    from opentelemetry.instrumentation.auto_instrumentation import run
+
+    run()

servicedna-0.1.0/tests/test_capture.py

@@ -0,0 +1,118 @@
+import json
+
+import pytest
+from fastapi import FastAPI, HTTPException, Request
+from fastapi.testclient import TestClient
+from opentelemetry import propagate, trace
+from opentelemetry.baggage.propagation import W3CBaggagePropagator
+from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor
+from opentelemetry.propagators.composite import CompositePropagator
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import SimpleSpanProcessor
+from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
+from opentelemetry.trace import SpanKind
+from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
+
+from servicedna import bodies as sdna
+
+exporter = InMemorySpanExporter()
+provider = TracerProvider()
+provider.add_span_processor(SimpleSpanProcessor(exporter))
+trace.set_tracer_provider(provider)
+propagate.set_global_textmap(CompositePropagator([TraceContextTextMapPropagator(), W3CBaggagePropagator()]))
+
+app = FastAPI()
+
+
+@app.post("/charge")
+async def charge(request: Request):
+    body = await request.json()
+    sdna.capture("computed.total", {"amount": body["amount"] * 2})
+    if body.get("fail"):
+        raise HTTPException(status_code=503, detail="processor unavailable")
+    if body.get("crash"):
+        raise RuntimeError("bug")
+    if body.get("reject"):
+        raise HTTPException(status_code=402, detail="declined")
+    return {"status": "CAPTURED", "amount": body["amount"], "apiKey": "secret"}
+
+
+FastAPIInstrumentor.instrument_app(
+    app,
+    server_request_hook=sdna.server_request_hook,
+    client_request_hook=sdna.client_request_hook,
+    client_response_hook=sdna.client_response_hook,
+)
+client = TestClient(app)
+
+
+def server_span():
+    return next(s for s in exporter.get_finished_spans() if s.kind == SpanKind.SERVER)
+
+
+@pytest.fixture(autouse=True)
+def reset():
+    exporter.clear()
+
+
+def test_records_bodies_of_a_capture_run_masking_credentials():
+    client.post(
+        "/charge",
+        json={"amount": 59, "password": "hunter2"},
+        headers={
+            "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
+            "baggage": "sdna.run=run_1,sdna.capture=1",
+        },
+    )
+    attrs = server_span().attributes
+    assert json.loads(attrs["sdna.request.body"]) == {"amount": 59, "password": "[masked]"}
+    assert json.loads(attrs["sdna.response.body"]) == {"status": "CAPTURED", "amount": 59, "apiKey": "[masked]"}
+    assert attrs["sdna.captured"] is True
+
+
+def test_capture_records_computed_values_on_the_current_span():
+    client.post("/charge", json={"amount": 5}, headers={"baggage": "sdna.capture=1"})
+    captured = [s.attributes.get("sdna.capture.computed.total") for s in exporter.get_finished_spans()]
+    assert '{"amount":10}' in [c for c in captured if c]
+
+
+def test_leaves_ordinary_requests_alone():
+    client.post("/charge", json={"amount": 1})
+    attrs = server_span().attributes
+    assert "sdna.request.body" not in attrs
+    assert "sdna.response.body" not in attrs
+    assert all("sdna.capture.computed.total" not in s.attributes for s in exporter.get_finished_spans())
+
+
+def test_with_capture_on_error_only_failed_requests_carry_their_bodies(monkeypatch):
+    monkeypatch.setenv("SERVICEDNA_CAPTURE_ON_ERROR", "true")
+
+    client.post("/charge", json={"amount": 1})
+    client.post("/charge", json={"amount": 2, "reject": True})
+    assert all("sdna.request.body" not in s.attributes for s in exporter.get_finished_spans())
+
+    exporter.clear()
+    client.post("/charge", json={"amount": 3, "fail": True, "password": "x"})
+    attrs = server_span().attributes
+    assert json.loads(attrs["sdna.request.body"]) == {"amount": 3, "fail": True, "password": "[masked]"}
+    assert json.loads(attrs["sdna.response.body"]) == {"detail": "processor unavailable"}
+    assert attrs["sdna.captured_on_error"] is True
+    assert "sdna.captured" not in attrs
+
+
+def test_capture_on_error_includes_unhandled_exceptions(monkeypatch):
+    monkeypatch.setenv("SERVICEDNA_CAPTURE_ON_ERROR", "true")
+    TestClient(app, raise_server_exceptions=False).post("/charge", json={"amount": 4, "crash": True})
+    attrs = server_span().attributes
+    assert json.loads(attrs["sdna.request.body"]) == {"amount": 4, "crash": True}
+    assert attrs["sdna.captured_on_error"] is True
+
+
+def test_tag_records_a_business_key_outside_capture_runs_too():
+    tracer = trace.get_tracer("t")
+    with tracer.start_as_current_span("job"):
+        sdna.tag("orderId", 17)
+        sdna.tag("skipped", None)
+    span = next(s for s in exporter.get_finished_spans() if s.name == "job")
+    assert span.attributes["sdna.key.orderId"] == "17"
+    assert "sdna.key.skipped" not in span.attributes

servicedna-0.1.0/tests/test_config.py

@@ -0,0 +1,83 @@
+from servicedna import config
+
+
+def test_disabled_without_url_and_key():
+    assert not config.resolve({}).enabled
+    assert not config.resolve({"SERVICEDNA_URL": "http://x"}).enabled
+
+
+def test_two_variables_are_enough():
+    cfg = config.resolve({"SERVICEDNA_URL": "http://sdna:8080/", "SERVICEDNA_KEY": "sdna_ik_x", "OTEL_SERVICE_NAME": "payments"})
+    assert cfg.enabled
+    assert cfg.url == "http://sdna:8080"
+    assert cfg.service_name == "payments"
+    assert cfg.health_url is None
+
+
+def test_heartbeat_checks_health_on_port():
+    assert config.resolve({"PORT": "4005"}).local_health_url == "http://127.0.0.1:4005/health"
+    assert config.resolve({"PORT": "8000", "SERVICEDNA_HEALTH_PATH": "/healthz"}).local_health_url == "http://127.0.0.1:8000/healthz"
+
+
+def test_otel_environment_points_exporter_at_servicedna():
+    cfg = config.resolve(
+        {
+            "SERVICEDNA_URL": "http://sdna:8080",
+            "SERVICEDNA_KEY": "sdna_ik_x",
+            "OTEL_SERVICE_NAME": "payments",
+            "SERVICEDNA_ENV": "prod",
+            "SERVICEDNA_HEALTH_URL": "http://payments:4005/health",
+            "PORT": "4005",
+        }
+    )
+    env = config.otel_environment(cfg)
+    assert env["OTEL_EXPORTER_OTLP_TRACES_ENDPOINT"] == "http://sdna:8080/api/v1/otlp/v1/traces"
+    assert env["OTEL_EXPORTER_OTLP_TRACES_HEADERS"] == "x-servicedna-key=sdna_ik_x"
+    assert env["OTEL_EXPORTER_OTLP_TRACES_PROTOCOL"] == "http/protobuf"
+    assert "deployment.environment.name=prod" in env["OTEL_RESOURCE_ATTRIBUTES"]
+    assert "servicedna.health.url=http://payments:4005/health" in env["OTEL_RESOURCE_ATTRIBUTES"]
+    assert "telemetry.sdk.language=python" in env["OTEL_RESOURCE_ATTRIBUTES"]
+    assert env["OTEL_PYTHON_EXCLUDED_URLS"] == "/health"
+
+
+def test_logs_go_to_servicedna_unless_turned_off():
+    base = {"SERVICEDNA_URL": "http://sdna:8080", "SERVICEDNA_KEY": "sdna_ik_x"}
+    env = config.otel_environment(config.resolve(base))
+    assert env["OTEL_LOGS_EXPORTER"] == "otlp"
+    assert env["OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED"] == "true"
+    assert env["OTEL_EXPORTER_OTLP_LOGS_ENDPOINT"] == "http://sdna:8080/api/v1/otlp/v1/logs"
+    assert env["OTEL_EXPORTER_OTLP_LOGS_HEADERS"] == "x-servicedna-key=sdna_ik_x"
+    off = config.otel_environment(config.resolve({**base, "SERVICEDNA_LOGS": "false"}))
+    assert off["OTEL_LOGS_EXPORTER"] == "none"
+    assert "OTEL_EXPORTER_OTLP_LOGS_ENDPOINT" not in off
+
+
+def test_uvicorn_logs_reach_the_opentelemetry_handler():
+    import logging
+
+    import pytest
+
+    uvicorn_config = pytest.importorskip("uvicorn.config")
+    from servicedna import distro
+
+    class LoggingHandler(logging.Handler):  # stands in for OpenTelemetry's
+        def __init__(self):
+            super().__init__()
+            self.records = []
+
+        def emit(self, record):
+            self.records.append(record)
+
+    handler = LoggingHandler()
+    logging.getLogger().addHandler(handler)
+    original = uvicorn_config.Config.configure_logging
+    try:
+        distro._bridge_uvicorn_logs()
+        uvicorn_config.Config(app="x:y").configure_logging()
+        logging.getLogger("uvicorn.error").error("Exception in ASGI application")
+        logging.getLogger("uvicorn.access").info("GET /health 200")
+        assert [r.getMessage() for r in handler.records] == ["Exception in ASGI application"]
+    finally:
+        uvicorn_config.Config.configure_logging = original
+        logging.getLogger().removeHandler(handler)
+        logging.getLogger("uvicorn").removeHandler(handler)

servicedna-0.1.0/tests/test_grpc_capture.py

@@ -0,0 +1,100 @@
+import json
+
+import grpc
+import pytest
+from grpc_health.v1 import health_pb2, health_pb2_grpc
+from opentelemetry import baggage, context, trace
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import SimpleSpanProcessor
+from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
+
+from servicedna import grpc_capture
+
+exporter = InMemorySpanExporter()
+provider = TracerProvider()
+provider.add_span_processor(SimpleSpanProcessor(exporter))
+tracer = provider.get_tracer("test")
+
+
+class Health(health_pb2_grpc.HealthServicer):
+    async def Check(self, request, context):
+        if request.service == "broken":
+            await context.abort(grpc.StatusCode.UNAVAILABLE, "down")
+        return health_pb2.HealthCheckResponse(status=health_pb2.HealthCheckResponse.SERVING)
+
+
+class SpanAndBaggage(grpc.aio.ServerInterceptor):
+    """Stands in for OpenTelemetry's server interceptor: a server span, with the caller's baggage."""
+
+    def __init__(self, capture):
+        self.capture = capture
+
+    async def intercept_service(self, continuation, details):
+        handler = await continuation(details)
+        behavior = handler.unary_unary
+
+        async def unary_unary(request, ctx):
+            token = context.attach(baggage.set_baggage("sdna.capture", "1") if self.capture else context.get_current())
+            try:
+                with tracer.start_as_current_span("grpc.health.v1.Health/Check", kind=trace.SpanKind.SERVER):
+                    return await behavior(request, ctx)
+            finally:
+                context.detach(token)
+
+        return grpc.unary_unary_rpc_method_handler(
+            unary_unary, request_deserializer=handler.request_deserializer, response_serializer=handler.response_serializer
+        )
+
+
+async def check(service: str, capture: bool):
+    server = grpc.aio.server(interceptors=[SpanAndBaggage(capture), grpc_capture.aio_server_interceptor()])
+    health_pb2_grpc.add_HealthServicer_to_server(Health(), server)
+    port = server.add_insecure_port("127.0.0.1:0")
+    await server.start()
+    try:
+        async with grpc.aio.insecure_channel(f"127.0.0.1:{port}") as channel:
+            try:
+                await health_pb2_grpc.HealthStub(channel).Check(health_pb2.HealthCheckRequest(service=service))
+            except grpc.aio.AioRpcError:
+                pass
+    finally:
+        await server.stop(None)
+    return next(s for s in exporter.get_finished_spans() if s.kind == trace.SpanKind.SERVER).attributes
+
+
+@pytest.fixture(autouse=True)
+def reset(monkeypatch):
+    exporter.clear()
+    monkeypatch.delenv("SERVICEDNA_CAPTURE_ON_ERROR", raising=False)
+
+
+@pytest.mark.asyncio
+async def test_a_capture_run_records_the_messages():
+    attrs = await check("payments", capture=True)
+    assert json.loads(attrs["sdna.request.body"]) == {"service": "payments"}
+    assert json.loads(attrs["sdna.response.body"]) == {"status": "SERVING"}
+    assert attrs["sdna.captured"] is True
+
+
+@pytest.mark.asyncio
+async def test_ordinary_calls_are_left_alone():
+    attrs = await check("payments", capture=False)
+    assert "sdna.request.body" not in attrs
+
+
+@pytest.mark.asyncio
+async def test_capture_on_error_records_failed_calls_only(monkeypatch):
+    monkeypatch.setenv("SERVICEDNA_CAPTURE_ON_ERROR", "true")
+    assert "sdna.request.body" not in await check("payments", capture=False)
+    exporter.clear()
+    attrs = await check("broken", capture=False)
+    assert json.loads(attrs["sdna.request.body"]) == {"service": "broken"}
+    assert attrs["sdna.captured_on_error"] is True
+
+
+def test_install_adds_the_interceptor_to_new_servers():
+    import grpc.aio
+
+    assert grpc_capture.install()
+    assert getattr(grpc.aio.server, "_servicedna", False)
+    assert grpc_capture.install()  # idempotent