graftcode-instrumentation 1.0.0__py3-none-any.whl

graftcode_instrumentation/BodyCapture.py

@@ -0,0 +1,192 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from hypertube.utils.Command import Command
+from hypertube.utils.logging.LogsRedactor import LogsRedactor
+
+from graftcode_instrumentation.OperationName import OperationName
+
+
+class BodyCaptureResult:
+    __slots__ = ("body", "truncated")
+
+    def __init__(self, body: Optional[str], truncated: bool) -> None:
+        self.body = body
+        self.truncated = truncated
+
+
+class BodyCapture:
+    TRUNCATION_MARKER = '"__truncated__"'
+
+    _MAX_DEPTH = 24
+    _CLOSING_COST_PER_LEVEL = 18
+    _SCALAR_RESERVE = 32
+
+    @staticmethod
+    def render(command: Optional[Command], max_characters: Optional[int]) -> Optional[BodyCaptureResult]:
+        if command is None:
+            return None
+
+        truncated: list[bool] = [False]
+        builder = _Builder()
+        BodyCapture._write_command(builder, command, 0, max_characters, truncated)
+
+        return BodyCaptureResult(LogsRedactor.redact_body(builder.to_string()), truncated[0])
+
+    @staticmethod
+    def _write_command(
+            builder: _Builder,
+            command: Command,
+            depth: int,
+            budget: Optional[int],
+            truncated: list[bool],
+    ) -> bool:
+        builder.append('{"runtime":"')
+        builder.append(str(command.runtime_name))
+        builder.append('","type":"')
+        builder.append(command.command_type.name)
+        builder.append('","payload":[')
+
+        payload = command.payload
+        within_budget = True
+        has_content = False
+        if budget is not None:
+            local_budget = max(
+                0,
+                budget - ((depth + 1) * BodyCapture._CLOSING_COST_PER_LEVEL) - BodyCapture._SCALAR_RESERVE,
+            )
+        else:
+            local_budget = 2 ** 30
+
+        for i, item in enumerate(payload):
+            if builder.length >= local_budget:
+                truncated[0] = True
+                within_budget = False
+                break
+
+            if has_content:
+                builder.append(",")
+
+            follows_sensitive_key = (
+                i > 0
+                and isinstance(payload[i - 1], str)
+                and LogsRedactor.is_sensitive_key(payload[i - 1]))
+
+            if not BodyCapture._write_value(
+                    builder, item, depth + 1, budget, local_budget, follows_sensitive_key, truncated):
+                has_content = True
+                within_budget = False
+                break
+
+            has_content = True
+
+        if not within_budget:
+            if has_content:
+                builder.append(",")
+
+            builder.append(BodyCapture.TRUNCATION_MARKER)
+
+        builder.append("]}")
+        return within_budget
+
+    @staticmethod
+    def _write_value(
+            builder: _Builder,
+            value: Any,
+            depth: int,
+            budget: Optional[int],
+            local_budget: int,
+            force_redact: bool,
+            truncated: list[bool],
+    ) -> bool:
+        if value is None:
+            builder.append("null")
+            return True
+
+        if depth >= BodyCapture._MAX_DEPTH:
+            truncated[0] = True
+            builder.append(BodyCapture.TRUNCATION_MARKER)
+            return True
+
+        if isinstance(value, Command):
+            return BodyCapture._write_command(builder, value, depth, budget, truncated)
+
+        if isinstance(value, str):
+            return BodyCapture._write_string(
+                builder,
+                LogsRedactor.PLACEHOLDER if force_redact else LogsRedactor.redact_value(value),
+                local_budget,
+                truncated)
+
+        if isinstance(value, bool):
+            builder.append("true" if value else "false")
+            return True
+
+        if isinstance(value, (int, float)):
+            builder.append(repr(value))
+            return True
+
+        if isinstance(value, (bytes, bytearray)):
+            builder.append('"[bytes:' + str(len(value)) + ']"')
+            return True
+
+        return BodyCapture._write_string(
+            builder,
+            LogsRedactor.PLACEHOLDER if force_redact else LogsRedactor.redact_value(BodyCapture._format(value)),
+            local_budget,
+            truncated)
+
+    @staticmethod
+    def _format(value: Any) -> str:
+        try:
+            return str(value)
+        except Exception:
+            return "[unrenderable:" + OperationName._full_name(type(value)) + "]"
+
+    @staticmethod
+    def _write_string(builder: _Builder, value: Optional[str], budget: int, truncated: List[bool]) -> bool:
+        builder.append('"')
+
+        if value is None:
+            builder.append('"')
+            return True
+
+        for character in value:
+            if builder.length >= budget:
+                truncated[0] = True
+                builder.append('"')
+                return False
+
+            if character == '"':
+                builder.append('\\"')
+            elif character == "\\":
+                builder.append("\\\\")
+            elif character == "\n":
+                builder.append("\\n")
+            elif character == "\r":
+                builder.append("\\r")
+            elif character == "\t":
+                builder.append("\\t")
+            elif character < " ":
+                builder.append("\\u%04x" % ord(character))
+            else:
+                builder.append(character)
+
+        builder.append('"')
+        return True
+
+
+class _Builder:
+    __slots__ = ("_parts", "length")
+
+    def __init__(self) -> None:
+        self._parts: list[str] = []
+        self.length = 0
+
+    def append(self, text: str) -> None:
+        self._parts.append(text)
+        self.length += len(text)
+
+    def to_string(self) -> str:
+        return "".join(self._parts)

graftcode_instrumentation/CallSpan.py

@@ -0,0 +1,227 @@
+from __future__ import annotations
+
+import random
+from typing import Any, Mapping, Optional
+
+from opentelemetry import context as otel_context
+from opentelemetry import trace
+from opentelemetry.context import Context
+from opentelemetry.propagators.textmap import Getter
+from opentelemetry.trace import NonRecordingSpan, Span, SpanContext, SpanKind, Status, StatusCode, TraceFlags, Tracer
+from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
+
+from hypertube.utils.Command import Command
+from hypertube.utils.CommandType import CommandType
+from hypertube.utils.connectionData.IConnectionData import IConnectionData
+from hypertube.utils.logging.LogsRedactor import LogsRedactor
+
+from graftcode_instrumentation.BodyCapture import BodyCapture
+from graftcode_instrumentation.GraftcodeTelemetrySettings import GraftcodeTelemetrySettings
+from graftcode_instrumentation.LibraryCatalog import LibraryCatalog
+from graftcode_instrumentation.OperationName import OperationName
+
+_SKIPPED_COMMANDS = (
+    CommandType.PassByValue,
+    CommandType.RegisterForUpdate,
+    CommandType.ValueForUpdate,
+    CommandType.InvokeDelegate,
+)
+
+
+def _header(headers: Mapping[Any, Any], key: str) -> Optional[Any]:
+    value = headers.get(key)
+    if value is not None:
+        return value
+
+    for name, candidate in headers.items():
+        if key.lower() == str(name).lower():
+            return candidate
+
+    return None
+
+
+class _HeaderGetter(Getter):
+
+    def get(self, carrier: Any, key: str) -> Optional[list[str]]:
+        value = _header(carrier, key)
+        return None if value is None else [value]
+
+    def keys(self, carrier: Any) -> list[Any]:
+        return list(carrier.keys())
+
+
+class CallSpan:
+    DEPENDENCY_TYPE = "graft.dependency.type"
+    DEPENDENCY_TARGET = "graft.dependency.target"
+    BRIDGE_DEPENDENCY_TYPE = "Graft"
+    REQUEST_BODY = "hypertube.request.body"
+    RESPONSE_BODY = "hypertube.response.body"
+    REQUEST_BODY_TRUNCATED = "hypertube.request.body.truncated"
+    RESPONSE_BODY_TRUNCATED = "hypertube.response.body.truncated"
+    TRACE_PARENT_HEADER = "traceparent"
+    TRACE_STATE_HEADER = "tracestate"
+    TRACE_ID_HEADER = "traceid"
+
+    _PROPAGATOR = TraceContextTextMapPropagator()
+    _HEADER_GETTER = _HeaderGetter()
+
+    def __init__(self, span: Span) -> None:
+        self.span = span
+        self._token: Any = otel_context.attach(trace.set_span_in_context(span))
+        self._injected_into: Optional[IConnectionData] = None
+        self._previous_headers: Optional[Mapping[str, str]] = None
+        self._completed = False
+
+    @staticmethod
+    def start_invoke(tracer: Tracer, command: Command, connection_data: IConnectionData) -> Optional[CallSpan]:
+        operation = CallSpan._resolve_operation(command)
+        if operation is None:
+            return None
+
+        LibraryCatalog.record(command, connection_data)
+        target = LibraryCatalog.describe_target(command, connection_data)
+        span = CallSpan._start(tracer, "Graft " + target, connection_data.get_headers())
+
+        if span.is_recording():
+            span.set_attribute("hypertube.runtime", str(command.runtime_name))
+            span.set_attribute("hypertube.command_type", command.command_type.name)
+            span.set_attribute("hypertube.connection_type", connection_data.connection_type.name)
+            span.set_attribute(CallSpan.DEPENDENCY_TYPE, CallSpan.BRIDGE_DEPENDENCY_TYPE)
+            CallSpan._set_if_present(span, CallSpan.DEPENDENCY_TARGET, LogsRedactor.redact_value(target))
+            CallSpan._set_if_present(span, "hypertube.operation", LogsRedactor.redact_value(operation))
+            CallSpan._set_if_present(
+                span,
+                "hypertube.target",
+                LogsRedactor.redact_value(LogsRedactor.redact_target(connection_data.hostname)),
+            )
+
+        call_span = CallSpan(span)
+        call_span._capture(command, CallSpan.REQUEST_BODY, CallSpan.REQUEST_BODY_TRUNCATED)
+        if GraftcodeTelemetrySettings.is_auto_inject_enabled():
+            call_span._inject_into(connection_data)
+
+        return call_span
+
+    @staticmethod
+    def start_handle(tracer: Tracer, command: Command, headers: Mapping[str, str]) -> Optional[CallSpan]:
+        operation = CallSpan._resolve_operation(command)
+        if operation is None:
+            return None
+
+        call_span = CallSpan(CallSpan._start(tracer, operation, headers))
+        call_span._capture(command, CallSpan.REQUEST_BODY, CallSpan.REQUEST_BODY_TRUNCATED)
+        return call_span
+
+    def complete(self, response: Any, exception: Optional[BaseException]) -> None:
+        if self._completed:
+            return
+
+        self._completed = True
+        try:
+            if response is not None:
+                self._capture(response, CallSpan.RESPONSE_BODY, CallSpan.RESPONSE_BODY_TRUNCATED)
+
+            if exception is None:
+                self.span.set_status(Status(StatusCode.OK))
+            else:
+                message = LogsRedactor.redact_value(str(exception))
+                self.span.set_attribute("exception.type", OperationName._full_name(type(exception)))
+                CallSpan._set_if_present(self.span, "exception.message", message)
+                self.span.set_status(Status(StatusCode.ERROR, message or ""))
+
+            if self._injected_into is not None:
+                self._injected_into.set_thread_local_headers(self._previous_headers)
+        finally:
+            try:
+                otel_context.detach(self._token)
+            finally:
+                self.span.end()
+
+    def dispose(self) -> None:
+        self.complete(None, None)
+
+    def close(self) -> None:
+        self.complete(None, None)
+
+    @staticmethod
+    def _resolve_operation(command: Command) -> Optional[str]:
+        if command.command_type in _SKIPPED_COMMANDS:
+            return None
+
+        operation = OperationName.resolve(command)
+        return None if operation.lower().endswith("telemetrysetup.initialize") else operation
+
+    @staticmethod
+    def _start(tracer: Tracer, name: str, headers: Mapping[Any, Any]) -> Span:
+        carrier = headers if headers is not None else {}
+
+        remote = CallSpan._PROPAGATOR.extract(carrier, context=Context(), getter=CallSpan._HEADER_GETTER)
+        if trace.get_current_span(remote).get_span_context().is_valid:
+            return tracer.start_span(name, context=remote, kind=SpanKind.INTERNAL)
+
+        trace_id = CallSpan._read_trace_id(_header(carrier, CallSpan.TRACE_ID_HEADER))
+        if trace_id is not None and trace_id != trace.get_current_span().get_span_context().trace_id:
+            parent = SpanContext(
+                trace_id=trace_id,
+                span_id=CallSpan._random_span_id(),
+                is_remote=True,
+                trace_flags=TraceFlags(TraceFlags.SAMPLED))
+            parent_context = trace.set_span_in_context(NonRecordingSpan(parent), Context())
+            return tracer.start_span(name, context=parent_context, kind=SpanKind.INTERNAL)
+
+        return tracer.start_span(name, kind=SpanKind.INTERNAL)
+
+    @staticmethod
+    def _read_trace_id(raw: Optional[str]) -> Optional[int]:
+        if raw is None:
+            return None
+
+        hex_value = str(raw).strip().replace("-", "").lower()
+        if len(hex_value) != 32 or not hex_value.replace("0", ""):
+            return None
+
+        if any(character not in "0123456789abcdef" for character in hex_value):
+            return None
+
+        return int(hex_value, 16)
+
+    @staticmethod
+    def _random_span_id() -> int:
+        span_id = 0
+        while span_id == 0:
+            span_id = random.getrandbits(64)
+        return span_id
+
+    def _inject_into(self, connection_data: IConnectionData) -> None:
+        local = connection_data.get_thread_local_headers()
+        span_context = self.span.get_span_context()
+        if (not span_context.is_valid
+                or (CallSpan.TRACE_PARENT_HEADER in connection_data.get_headers()
+                    and CallSpan.TRACE_PARENT_HEADER not in local)):
+            return
+
+        headers = dict(local)
+        headers.pop(CallSpan.TRACE_STATE_HEADER, None)
+        CallSpan._PROPAGATOR.inject(headers, context=trace.set_span_in_context(self.span, Context()))
+        headers[CallSpan.TRACE_ID_HEADER] = trace.format_trace_id(span_context.trace_id)
+
+        connection_data.set_thread_local_headers(headers)
+        self._injected_into = connection_data
+        self._previous_headers = local
+
+    def _capture(self, command: Any, body_key: str, truncated_key: str) -> None:
+        if not self.span.is_recording() or not GraftcodeTelemetrySettings.is_body_capture_enabled():
+            return
+
+        result = BodyCapture.render(command, GraftcodeTelemetrySettings.get_body_max_characters())
+        if result is None or result.body is None:
+            return
+
+        self.span.set_attribute(body_key, result.body)
+        if result.truncated:
+            self.span.set_attribute(truncated_key, True)
+
+    @staticmethod
+    def _set_if_present(span: Span, key: str, value: Optional[str]) -> None:
+        if value is not None:
+            span.set_attribute(key, value)

graftcode_instrumentation/GraftcodeInstrumentation.py

@@ -0,0 +1,197 @@
+from __future__ import annotations
+
+import logging
+import traceback
+from types import TracebackType
+from typing import Any, Dict, Mapping, Optional, Type
+
+from opentelemetry import trace
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.trace import Tracer
+
+from hypertube.utils.abstractions.HypertubeBroker import HypertubeBroker
+from hypertube.utils.abstractions.HypertubeCallContext import HypertubeCallContext
+from hypertube.utils.abstractions.IHypertubeHandling import IHypertubeHandling
+from hypertube.utils.abstractions.IHypertubeInvocation import IHypertubeInvocation
+from hypertube.utils.abstractions.IHypertubeLogging import IHypertubeLogging
+from hypertube.utils.Command import Command
+from hypertube.utils.connectionData.IConnectionData import IConnectionData
+from hypertube.utils.logging.HypertubeLogger import HypertubeLogger
+from hypertube.utils.logging.LogsCommandResolver import LogsCommandResolver
+from hypertube.utils.logging.LogsLevel import LogsLevel
+from hypertube.utils.logging.LogsRedactor import LogsRedactor
+
+from graftcode_instrumentation.CallSpan import CallSpan
+from graftcode_instrumentation.OperationName import OperationName
+
+TRACE = 5
+
+_LOG_LEVELS: Dict[LogsLevel, int] = {
+    LogsLevel.Trace: TRACE,
+    LogsLevel.Debug: logging.DEBUG,
+    LogsLevel.Info: logging.INFO,
+    LogsLevel.Warning: logging.WARNING,
+    LogsLevel.Error: logging.ERROR,
+}
+
+_ENABLED_PROBE_LEVELS = (logging.CRITICAL, logging.ERROR, logging.WARNING, logging.INFO, logging.DEBUG, TRACE)
+
+_RESERVED_RECORD_ATTRIBUTES = frozenset(
+    logging.LogRecord("", 0, "", 0, "", None, None).__dict__.keys()) | {"message", "asctime"}
+
+
+class GraftcodeInstrumentation(IHypertubeInvocation, IHypertubeHandling, IHypertubeLogging):
+    INSTRUMENTATION_NAME = "Graftcode"
+    LOGGER_NAME = "Hypertube"
+
+    def __init__(
+            self,
+            tracer_provider: Optional[TracerProvider] = None,
+            logger: Optional[logging.Logger] = None,
+    ) -> None:
+        self._tracer: Tracer = trace.get_tracer(
+            GraftcodeInstrumentation.INSTRUMENTATION_NAME,
+            tracer_provider=tracer_provider,
+        )
+        self._logger = logger
+        HypertubeBroker.attach(self)
+        HypertubeLogger.attach(self)
+
+    @staticmethod
+    def attach(
+            tracer_provider: Optional[TracerProvider] = None,
+            logger: Optional[logging.Logger] = None,
+    ) -> GraftcodeInstrumentation:
+        return GraftcodeInstrumentation(tracer_provider, logger)
+
+    def on_execute(
+            self,
+            context: HypertubeCallContext,
+            command: Command,
+            connection_data: IConnectionData,
+    ) -> None:
+        reported = LogsCommandResolver.resolve_for_invoke(command)
+        span = CallSpan.start_invoke(self._tracer, reported, connection_data)
+        if span is not None:
+            context.items.append(span)
+
+    def on_response(self, context: HypertubeCallContext, response: Any) -> None:
+        GraftcodeInstrumentation._complete_spans(context, response, None)
+
+    def on_invocation_error(self, context: HypertubeCallContext, exception: BaseException) -> None:
+        GraftcodeInstrumentation._complete_spans(context, None, exception)
+
+    def on_process(self, context: HypertubeCallContext, command: Command) -> None:
+        headers: Dict[str, str] = {}
+        reported = LogsCommandResolver.resolve_for_handle(command, headers)
+        span = CallSpan.start_handle(self._tracer, reported, headers)
+        if span is not None:
+            context.items.append(span)
+
+    def on_processed(self, context: HypertubeCallContext, response: Any) -> None:
+        GraftcodeInstrumentation._complete_spans(context, response, None)
+
+    def on_handling_error(self, context: HypertubeCallContext, exception: BaseException) -> None:
+        GraftcodeInstrumentation._complete_spans(context, None, exception)
+
+    def is_requested(self) -> bool:
+        if self._logger is None:
+            return trace.get_current_span().is_recording()
+
+        return any(self._logger.isEnabledFor(level) for level in _ENABLED_PROBE_LEVELS)
+
+    def is_log_enabled(self, level: LogsLevel) -> bool:
+        if self._logger is None:
+            return trace.get_current_span().is_recording()
+
+        python_level = _LOG_LEVELS.get(level)
+        return python_level is not None and self._logger.isEnabledFor(python_level)
+
+    def on_log(
+            self,
+            level: LogsLevel,
+            message: str,
+            properties: Mapping[str, Any],
+            exception: Optional[BaseException],
+    ) -> None:
+        if self._logger is None:
+            GraftcodeInstrumentation._record_span_event(level, message, properties, exception)
+            return
+
+        if not self.is_log_enabled(level):
+            return
+
+        extra: Dict[str, Any] = {}
+        for key, value in properties.items():
+            extra[key + "_" if key in _RESERVED_RECORD_ATTRIBUTES else key] = value
+
+        exc_info = (type(exception), exception, exception.__traceback__) if exception is not None else None
+        self._logger.log(_LOG_LEVELS[level], message, exc_info=exc_info, extra=extra)
+
+    def close(self) -> None:
+        HypertubeBroker.detach(self)
+        HypertubeLogger.detach(self)
+
+    def dispose(self) -> None:
+        self.close()
+
+    def __enter__(self) -> GraftcodeInstrumentation:
+        return self
+
+    def __exit__(
+            self,
+            exc_type: Optional[Type[BaseException]],
+            exc: Optional[BaseException],
+            exc_traceback: Optional[TracebackType],
+    ) -> bool:
+        self.close()
+        return False
+
+    @staticmethod
+    def _complete_spans(context: HypertubeCallContext, response: Any, exception: Optional[BaseException]) -> None:
+        items = context.items
+        for i in range(len(items) - 1, -1, -1):
+            item = items[i]
+            if isinstance(item, CallSpan):
+                item.complete(response, exception)
+                del items[i]
+
+    @staticmethod
+    def _record_span_event(
+            level: LogsLevel,
+            message: str,
+            properties: Mapping[str, Any],
+            exception: Optional[BaseException],
+    ) -> None:
+        span = trace.get_current_span()
+        if not span.is_recording():
+            return
+
+        attributes: Dict[str, Any] = {"log.level": GraftcodeInstrumentation._to_level_name(level)}
+        attributes.update(properties)
+
+        if exception is not None:
+            attributes["log.message"] = message
+            attributes["exception.type"] = OperationName._full_name(type(exception))
+            GraftcodeInstrumentation._put_if_present(
+                attributes, "exception.message", LogsRedactor.redact_value(str(exception)))
+            GraftcodeInstrumentation._put_if_present(
+                attributes,
+                "exception.stacktrace",
+                LogsRedactor.redact_value(GraftcodeInstrumentation._stack_trace(exception)),
+            )
+
+        span.add_event("exception" if exception is not None else message, attributes)
+
+    @staticmethod
+    def _stack_trace(exception: BaseException) -> str:
+        return "".join(traceback.format_exception(type(exception), exception, exception.__traceback__))
+
+    @staticmethod
+    def _put_if_present(attributes: Dict[str, Any], key: str, value: Any) -> None:
+        if value:
+            attributes[key] = value
+
+    @staticmethod
+    def _to_level_name(level: LogsLevel) -> str:
+        return "Information" if level == LogsLevel.Info else level.name

graftcode_instrumentation/GraftcodeTelemetrySettings.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+import os
+
+
+def _read_flag(name: str, default_value: bool) -> bool:
+    value = os.environ.get(name)
+    if value is None or not value.strip():
+        return default_value
+
+    return value.strip().lower() != "false" and value.strip() != "0"
+
+
+class GraftcodeTelemetrySettings:
+    MINIMUM_BODY_MAX_CHARS = 256
+    DEFAULT_BODY_MAX_CHARS = 8192
+    MAXIMUM_BODY_MAX_CHARS = 32768
+
+    _auto_inject: bool = _read_flag("HYPERTUBE_TELEMETRY_AUTO_INJECT", True)
+    _capture_bodies: bool = _read_flag("HYPERTUBE_TELEMETRY_CAPTURE_BODIES", False)
+    _body_max_characters: int | None = None
+
+    @staticmethod
+    def is_auto_inject_enabled() -> bool:
+        return GraftcodeTelemetrySettings._auto_inject
+
+    @staticmethod
+    def set_auto_inject_enabled(value: bool) -> None:
+        GraftcodeTelemetrySettings._auto_inject = bool(value)
+
+    @staticmethod
+    def is_body_capture_enabled() -> bool:
+        return GraftcodeTelemetrySettings._capture_bodies
+
+    @staticmethod
+    def set_body_capture_enabled(value: bool) -> None:
+        GraftcodeTelemetrySettings._capture_bodies = bool(value)
+
+    @staticmethod
+    def get_body_max_characters() -> int | None:
+        return GraftcodeTelemetrySettings._body_max_characters
+
+    @staticmethod
+    def set_body_max_characters(value: int) -> None:
+        GraftcodeTelemetrySettings._body_max_characters = (
+            GraftcodeTelemetrySettings.clamp_body_max_characters(value))
+
+    @staticmethod
+    def clamp_body_max_characters(value: int) -> int:
+        if value < GraftcodeTelemetrySettings.MINIMUM_BODY_MAX_CHARS:
+            return GraftcodeTelemetrySettings.MINIMUM_BODY_MAX_CHARS
+
+        return min(value, GraftcodeTelemetrySettings.MAXIMUM_BODY_MAX_CHARS)
+
+    @staticmethod
+    def _read_body_max_chars() -> int:
+        raw = os.environ.get("HYPERTUBE_TELEMETRY_BODY_MAX_CHARS")
+        if raw is None or not raw.strip():
+            return GraftcodeTelemetrySettings.DEFAULT_BODY_MAX_CHARS
+
+        try:
+            return GraftcodeTelemetrySettings.clamp_body_max_characters(int(raw.strip()))
+        except ValueError:
+            return GraftcodeTelemetrySettings.DEFAULT_BODY_MAX_CHARS
+
+
+GraftcodeTelemetrySettings._body_max_characters = GraftcodeTelemetrySettings._read_body_max_chars()

graftcode_instrumentation/LibraryCatalog.py

@@ -0,0 +1,195 @@
+from __future__ import annotations
+
+import os
+import threading
+import zipfile
+from typing import Any, Dict, List, Optional
+
+from hypertube.utils.Command import Command
+from hypertube.utils.CommandType import CommandType
+from hypertube.utils.connectionData.IConnectionData import IConnectionData
+
+from graftcode_instrumentation.OperationName import OperationName
+
+
+class _Library:
+    __slots__ = ("name", "version")
+
+    def __init__(self, name: str, version: str) -> None:
+        self.name = name
+        self.version = version
+
+
+class LibraryCatalog:
+    _libraries_by_connection: Dict[str, Dict[str, _Library]] = {}
+    _version_by_path: Dict[str, str] = {}
+    _lock = threading.Lock()
+
+    @staticmethod
+    def record(command: Command, connection_data: IConnectionData) -> None:
+        for load in LibraryCatalog._find_commands(command, CommandType.LoadLibrary):
+            LibraryCatalog._record_load(load, connection_data)
+
+    @staticmethod
+    def describe_target(command: Command, connection_data: IConnectionData) -> str:
+        channel = LibraryCatalog.channel(connection_data)
+        library = LibraryCatalog._resolve_library_name(command, connection_data)
+
+        if OperationName.is_blank(library):
+            return str(command.runtime_name) + " " + channel
+
+        version = LibraryCatalog._lookup_version(connection_data, library)
+        if OperationName.is_blank(version):
+            return library + " " + channel
+        return library + " " + version + " " + channel
+
+    @staticmethod
+    def channel(connection_data: IConnectionData) -> str:
+        return connection_data.connection_type.name.replace("_", "").lower()
+
+    @staticmethod
+    def _record_load(command: Command, connection_data: IConnectionData) -> None:
+        path = LibraryCatalog._resolve_library_path(command)
+        if OperationName.is_blank(path):
+            return
+
+        name = LibraryCatalog._file_name_without_extension(path)
+        if OperationName.is_blank(name):
+            return
+
+        with LibraryCatalog._lock:
+            version = LibraryCatalog._version_by_path.get(path)
+            if version is None:
+                version = LibraryCatalog._read_version(path, name)
+                LibraryCatalog._version_by_path[path] = version
+
+            libraries = LibraryCatalog._libraries_by_connection.setdefault(
+                LibraryCatalog._connection_key(connection_data), {})
+            libraries[name.lower()] = _Library(name, version)
+
+    @staticmethod
+    def _find_commands(command: Command, command_type: CommandType) -> List[Command]:
+        matches: List[Command] = []
+        LibraryCatalog._collect(command, command_type, matches)
+        return matches
+
+    @staticmethod
+    def _collect(command: Command, command_type: CommandType, matches: List[Command]) -> None:
+        if command.command_type == command_type:
+            matches.append(command)
+
+        for item in command.payload:
+            if isinstance(item, Command):
+                LibraryCatalog._collect(item, command_type, matches)
+
+    @staticmethod
+    def _resolve_library_name(command: Command, connection_data: IConnectionData) -> Optional[str]:
+        for load in LibraryCatalog._find_commands(command, CommandType.LoadLibrary):
+            path = LibraryCatalog._resolve_library_path(load)
+            name = None if OperationName.is_blank(path) else LibraryCatalog._file_name_without_extension(path)
+            if not OperationName.is_blank(name):
+                return name
+
+        type_name = OperationName.resolve_target_type_name(command)
+        if OperationName.is_blank(type_name):
+            return None
+
+        libraries = LibraryCatalog._libraries_by_connection.get(LibraryCatalog._connection_key(connection_data))
+        if not libraries:
+            return LibraryCatalog._root_namespace(type_name)
+
+        best_match: Optional[str] = None
+        for library in list(libraries.values()):
+            if not LibraryCatalog._is_type_of_library(type_name, library.name):
+                continue
+
+            if best_match is None or len(library.name) > len(best_match):
+                best_match = library.name
+
+        return best_match if best_match is not None else LibraryCatalog._root_namespace(type_name)
+
+    @staticmethod
+    def _root_namespace(type_name: str) -> str:
+        separator = type_name.find(".")
+        return type_name if separator < 0 else type_name[:separator]
+
+    @staticmethod
+    def _is_type_of_library(type_name: str, library_name: str) -> bool:
+        type_lower = type_name.lower()
+        library_lower = library_name.lower()
+        return type_lower == library_lower or type_lower.startswith(library_lower + ".")
+
+    @staticmethod
+    def _lookup_version(connection_data: IConnectionData, library: str) -> Optional[str]:
+        libraries = LibraryCatalog._libraries_by_connection.get(LibraryCatalog._connection_key(connection_data))
+        if not libraries:
+            return None
+
+        entry = libraries.get(library.lower())
+        return None if entry is None else entry.version
+
+    @staticmethod
+    def _connection_key(connection_data: IConnectionData) -> str:
+        return connection_data.connection_type.name + "|" + str(connection_data.hostname)
+
+    @staticmethod
+    def _resolve_library_path(command: Command) -> Optional[str]:
+        payload = command.payload
+        for i in range(len(payload) - 1, -1, -1):
+            path = LibraryCatalog._as_text(payload[i])
+            if not OperationName.is_blank(path):
+                return path
+
+        return None
+
+    @staticmethod
+    def _as_text(payload_item: Any) -> Optional[str]:
+        if isinstance(payload_item, Command):
+            if (payload_item.command_type == CommandType.Value
+                    and payload_item.payload
+                    and isinstance(payload_item.payload[0], str)):
+                return payload_item.payload[0]
+            return None
+
+        return payload_item if isinstance(payload_item, str) else None
+
+    @staticmethod
+    def _file_name_without_extension(path: str) -> str:
+        name = os.path.basename(path.rstrip("/\\"))
+        dot = name.rfind(".")
+        return name[:dot] if dot > 0 else name
+
+    @staticmethod
+    def _read_version(path: str, name: str) -> str:
+        if path.lower().endswith(".jar") and os.path.isfile(path):
+            return LibraryCatalog._read_jar_version(path)
+
+        if os.path.isdir(path) or path.lower().endswith(".py"):
+            return LibraryCatalog._read_distribution_version(name)
+
+        return ""
+
+    @staticmethod
+    def _read_jar_version(path: str) -> str:
+        try:
+            with zipfile.ZipFile(path) as jar:
+                manifest = jar.read("META-INF/MANIFEST.MF").decode("utf-8", errors="replace")
+        except (OSError, KeyError, zipfile.BadZipFile):
+            return ""
+
+        attributes: Dict[str, str] = {}
+        for line in manifest.splitlines():
+            key, separator, value = line.partition(":")
+            if separator:
+                attributes[key.strip()] = value.strip()
+
+        version = attributes.get("Implementation-Version") or attributes.get("Bundle-Version")
+        return "" if OperationName.is_blank(version) else version.strip()
+
+    @staticmethod
+    def _read_distribution_version(name: str) -> str:
+        try:
+            from importlib import metadata
+            return metadata.version(name).strip()
+        except Exception:
+            return ""

graftcode_instrumentation/OperationName.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+from typing import Any, Optional, Type
+
+from hypertube.utils.Command import Command
+from hypertube.utils.CommandType import CommandType
+
+_MAX_DEPTH = 32
+
+_MEMBER_COMMANDS = (
+    CommandType.InvokeStaticMethod,
+    CommandType.InvokeInstanceMethod,
+    CommandType.InvokeGenericStaticMethod,
+    CommandType.InvokeGenericMethod,
+    CommandType.GetStaticField,
+    CommandType.SetStaticField,
+    CommandType.GetInstanceField,
+    CommandType.SetInstanceField,
+    CommandType.GetStaticMethodAsDelegate,
+    CommandType.GetInstanceMethodAsDelegate,
+)
+
+_NAMED_BY_PAYLOAD = (
+    CommandType.GetType,
+    CommandType.Cast,
+    CommandType.CreateNull,
+)
+
+_TYPED_BY_FIRST_PAYLOAD = (
+    CommandType.CreateClassInstance,
+    CommandType.SetInstanceField,
+    CommandType.InvokeStaticMethod,
+    CommandType.InvokeInstanceMethod,
+    CommandType.GetStaticField,
+    CommandType.GetInstanceField,
+)
+
+
+class OperationName:
+
+    @staticmethod
+    def resolve(command: Command) -> str:
+        command_type = command.command_type
+
+        if command_type in _MEMBER_COMMANDS:
+            qualified = OperationName._qualify(
+                OperationName._resolve_type_name_core(OperationName._payload_at(command, 0), 0),
+                OperationName._resolve_text(OperationName._payload_at(command, 1), 0))
+            return qualified if qualified is not None else OperationName._fallback(command)
+
+        if command_type == CommandType.CreateClassInstance:
+            created_type = OperationName._resolve_type_name_core(OperationName._payload_at(command, 0), 0)
+            return OperationName._fallback(command) if created_type is None else created_type + ".ctor"
+
+        if command_type in (CommandType.InvokeGlobalFunction, CommandType.GetGlobalField):
+            name = OperationName._resolve_text(OperationName._payload_at(command, 0), 0)
+            return name if name is not None else OperationName._fallback(command)
+
+        return OperationName._fallback(command)
+
+    @staticmethod
+    def resolve_target_type_name(command: Command) -> Optional[str]:
+        command_type = command.command_type
+
+        if command_type in _MEMBER_COMMANDS or command_type == CommandType.CreateClassInstance:
+            return OperationName._resolve_type_name_core(OperationName._payload_at(command, 0), 0)
+
+        if command_type == CommandType.GetType:
+            return OperationName._resolve_type_name_core(command, 0)
+
+        return None
+
+    @staticmethod
+    def is_blank(value: Any) -> bool:
+        return value is None or not str(value).strip()
+
+    @staticmethod
+    def _fallback(command: Command) -> str:
+        return "hypertube." + command.command_type.name
+
+    @staticmethod
+    def _qualify(type_name: Optional[str], member_name: Optional[str]) -> Optional[str]:
+        if OperationName.is_blank(member_name):
+            return None
+
+        return member_name if OperationName.is_blank(type_name) else type_name + "." + member_name
+
+    @staticmethod
+    def _payload_at(command: Command, index: int) -> Any:
+        payload = command.payload
+        return payload[index] if len(payload) > index else None
+
+    @staticmethod
+    def _resolve_text(payload_item: Any, depth: int) -> Optional[str]:
+        if depth > _MAX_DEPTH:
+            return None
+
+        if isinstance(payload_item, str):
+            return payload_item
+
+        if isinstance(payload_item, Command) and payload_item.command_type == CommandType.Value:
+            return OperationName._resolve_text(OperationName._payload_at(payload_item, 0), depth + 1)
+
+        return None
+
+    @staticmethod
+    def _resolve_type_name_core(target: Any, depth: int) -> Optional[str]:
+        if depth > _MAX_DEPTH or target is None:
+            return None
+
+        if isinstance(target, str):
+            return target
+
+        if isinstance(target, type):
+            return OperationName._full_name(target)
+
+        if isinstance(target, Command):
+            return OperationName._resolve_type_name_from_command(target, depth)
+
+        return OperationName._full_name(type(target))
+
+    @staticmethod
+    def _resolve_type_name_from_command(command: Command, depth: int) -> Optional[str]:
+        command_type = command.command_type
+
+        if command_type == CommandType.Value:
+            return OperationName._resolve_type_name_core(OperationName._payload_at(command, 0), depth + 1)
+
+        if command_type in _NAMED_BY_PAYLOAD:
+            for item in command.payload:
+                name = OperationName._resolve_text(item, depth + 1)
+                if not OperationName.is_blank(name):
+                    return name
+            return None
+
+        if command_type in _TYPED_BY_FIRST_PAYLOAD:
+            return OperationName._resolve_type_name_core(OperationName._payload_at(command, 0), depth + 1)
+
+        return None
+
+    @staticmethod
+    def _full_name(value_type: Type[Any]) -> str:
+        module = value_type.__module__
+        if module in (None, "builtins"):
+            return value_type.__qualname__
+        return module + "." + value_type.__qualname__

graftcode_instrumentation/__init__.py

@@ -0,0 +1,12 @@
+from graftcode_instrumentation.GraftcodeInstrumentation import GraftcodeInstrumentation
+from graftcode_instrumentation.GraftcodeTelemetrySettings import GraftcodeTelemetrySettings
+
+INSTRUMENTATION_NAME = GraftcodeInstrumentation.INSTRUMENTATION_NAME
+LOGGER_NAME = GraftcodeInstrumentation.LOGGER_NAME
+
+__all__ = [
+    "GraftcodeInstrumentation",
+    "GraftcodeTelemetrySettings",
+    "INSTRUMENTATION_NAME",
+    "LOGGER_NAME",
+]

graftcode_instrumentation-1.0.0.dist-info/METADATA

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: graftcode-instrumentation
+Version: 1.0.0
+Summary: OpenTelemetry instrumentation for Graftcode / Hypertube calls in Python
+Author-email: "Graftcode S.A." <support@graftcode.com>
+License: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: opentelemetry-api>=1.20
+Requires-Dist: hypertube-python-sdk>=3.0.0
+Provides-Extra: dev
+Requires-Dist: opentelemetry-sdk>=1.20; extra == "dev"
+Requires-Dist: graftcode-context>=1.0.3; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+
+# graftcode-instrumentation (Python)
+
+OpenTelemetry instrumentation for Graftcode (Hypertube) calls in Python. It produces a caller span and a callee span per call, propagates W3C trace context, and forwards Hypertube log lines. It is a port of the .NET (`Graftcode.Instrumentation`) and Java (`com.graftcode.instrumentation`) packages. Class names, span names, attribute keys and header names are the same in all three.
+
+Hypertube exposes a broker (`HypertubeBroker`, in `hypertube.utils.abstractions`) and a log listener registry (`HypertubeLogger`, in `hypertube.utils.logging`). Nothing is monkey-patched. `GraftcodeInstrumentation.attach(...)` registers one object as an invocation listener, a handling listener and a log listener; `close()` removes all three. The Hypertube SDK itself has no OpenTelemetry dependency.
+
+## Usage
+
+```python
+import logging
+from opentelemetry.sdk.trace import TracerProvider
+from graftcode_instrumentation import GraftcodeInstrumentation, LOGGER_NAME
+
+provider = TracerProvider()
+instrumentation = GraftcodeInstrumentation.attach(provider, logging.getLogger(LOGGER_NAME))
+...
+instrumentation.close()
+```
+
+| Argument | Meaning |
+|----------|---------|
+| `tracer_provider` | Provider used to create the `Graftcode` tracer. Defaults to the global provider. |
+| `logger` | A standard-library `logging.Logger`. Plays the role of `ILogger` in .NET or the OpenTelemetry logs bridge in Java. If it is omitted, Hypertube log lines are recorded as events on the current span. |
+
+Names: `INSTRUMENTATION_NAME = "Graftcode"` (tracer name), `LOGGER_NAME = "Hypertube"` (logger name used by the App Insights connector).
+
+## Settings (`GraftcodeTelemetrySettings`)
+
+Static getters and setters, as in Java:
+
+| Setting | Environment variable | Default |
+|---------|----------------------|---------|
+| `is_auto_inject_enabled` / `set_auto_inject_enabled` | `HYPERTUBE_TELEMETRY_AUTO_INJECT` | `true` |
+| `is_body_capture_enabled` / `set_body_capture_enabled` | `HYPERTUBE_TELEMETRY_CAPTURE_BODIES` | `false` |
+| `get_body_max_characters` / `set_body_max_characters` | `HYPERTUBE_TELEMETRY_BODY_MAX_CHARS` | `8192`, clamped to 256–32768 |
+
+## Span model (`CallSpan`)
+
+- **Caller** (`on_execute`): span `Graft <library> [version] <channel>`, kind `INTERNAL`. Attributes are `graft.dependency.type = Graft`, `graft.dependency.target`, `hypertube.runtime`, `hypertube.command_type`, `hypertube.connection_type`, `hypertube.operation`, and `hypertube.target` (with user info stripped).
+- **Callee** (`on_process`): span named after the operation, for example `TestGgPythonLib.RandomService.RandomService.fetch`, kind `INTERNAL`.
+- No span is opened for `PassByValue`, `RegisterForUpdate`, `ValueForUpdate`, `InvokeDelegate`, or any operation ending in `TelemetrySetup.Initialize`.
+- When a call fails, the span gets `exception.type`, a redacted `exception.message`, and status `ERROR`.
+- The span becomes current while the call runs (`opentelemetry.context.attach`) and is detached when the call completes. Code inside the called method therefore sees the callee span as its parent.
+
+## Trace context
+
+- **Outgoing:** the caller copies the thread-local connection headers without `tracestate`, injects W3C `traceparent`/`tracestate` plus `traceid`, and restores the previous headers when the call completes. A `traceparent` that the application set on the connection is never overwritten.
+- **Incoming:** W3C headers from the `ContextMetadata` command are preferred. If only a `traceid` header arrives and it differs from the current trace, the callee joins that trace under a synthetic remote parent.
+- **Called side:** on the called side, `ContextMetadata` is handled through `graftcode.context.request_context.RequestContext`, so the hosted library needs `graftcode-context` installed.
+
+## Operation names (`OperationName`)
+
+| Command | Name |
+|---------|------|
+| Member access (static/instance method, field, delegate) | `Type.member` |
+| `CreateClassInstance` | `Type.ctor` |
+| `InvokeGlobalFunction` / `GetGlobalField` | the function or field name |
+| Anything else | `hypertube.<CommandType>` |
+
+## Library catalog (`LibraryCatalog`)
+
+`record` remembers the libraries loaded on a connection (`LoadLibrary`). `describe_target` formats `<library> [version] <channel>`, where the channel is the lowercased connection type. The library name is chosen in this order:
+
+1. The `LoadLibrary` file stem.
+2. The longest recorded library that prefixes the target type.
+3. The root namespace of the target type.
+
+Versions come from the jar manifest (`Implementation-Version`) or from `importlib.metadata` for Python packages. Without a library the target is `<runtime> <channel>`.
+
+## Body capture (`BodyCapture`)
+
+Body capture is off by default. When it is enabled, request and response commands are rendered as JSON-like text (`{"runtime":..,"type":..,"payload":[..]}`) on `hypertube.request.body` / `hypertube.response.body`:
+
+- Sensitive keys, connection strings, bearer tokens and JWTs are redacted.
+- Output is cut at the character budget; a cut body gets the `"__truncated__"` marker and the `.truncated` attribute.
+
+## Logs
+
+Hypertube writes its own console lines asynchronously (`AsyncLogSink`, writer thread `hypertube-log-writer`). Independently of that, the instrumentation receives every rendered line together with its template properties:
+
+- **With a logger:** the line is forwarded at the matching level (`Trace`→5, `Debug`→10, `Info`→20, `Warning`→30, `Error`→40). Template properties are passed as `extra`, and the exception as `exc_info`. Names that clash with `LogRecord` attributes get a trailing `_`.
+- **Without a logger:** the line becomes a span event carrying `log.level`. Exceptions become an `exception` event with redacted `exception.message` / `exception.stacktrace`.
+
+## Tests
+
+```powershell
+$env:PYTHONPATH = "<HYPERTUBE>\src\python"
+python -m pip install -e .[dev]
+python -m pytest
+```

graftcode_instrumentation-1.0.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+graftcode_instrumentation/BodyCapture.py,sha256=eaMyZK1qkPukOpVRRnLwk9zGEPUsd_8mBy5jOuswalE,5708
+graftcode_instrumentation/CallSpan.py,sha256=ZAj0PmuB9VM1C9-TFWDrdoNvpX10dc1pc8Gvu3t8x7Y,9153
+graftcode_instrumentation/GraftcodeInstrumentation.py,sha256=zz1r3_ha32tcNtY7aPpQu_ikURLzJ5v722Wa8ifc1Yc,7530
+graftcode_instrumentation/GraftcodeTelemetrySettings.py,sha256=pXQdXNlUCNqki9SGydXwnERfX2diywE9Df8uCfQKG2g,2298
+graftcode_instrumentation/LibraryCatalog.py,sha256=TDMLmn5-wUxI9BlhZYj9eUsWSQaaGd1KHIbVIzjo6Iw,7472
+graftcode_instrumentation/OperationName.py,sha256=Qyo1QKqePP-WTdzJ7CIw7oM7-G2_zoHvTwBVR2zSCEw,5098
+graftcode_instrumentation/__init__.py,sha256=uZiLKbyDhNP4jz0nBRt1U5N3oLt7rVI9zYRlpFukJSs,429
+graftcode_instrumentation-1.0.0.dist-info/METADATA,sha256=CD1E0W_fGYr2XpRtNf5QAfKu3yv17Je9m_fBqbBeAto,6473
+graftcode_instrumentation-1.0.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+graftcode_instrumentation-1.0.0.dist-info/top_level.txt,sha256=cmcsqjzhcRirpveVx7r4P7CK2x6bCXTks33DEoMq4_Q,26
+graftcode_instrumentation-1.0.0.dist-info/RECORD,,

graftcode_instrumentation-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

graftcode_instrumentation-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+graftcode_instrumentation