graftcode-instrumentation 1.0.0__tar.gz

graftcode_instrumentation-1.0.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,90 @@
+# 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/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-1.0.0/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)