Skip to main content

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

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

$env:PYTHONPATH = "<HYPERTUBE>\src\python"
python -m pip install -e .[dev]
python -m pytest

Metadata

Release files for graftcode-instrumentation 1.0.5

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for graftcode-instrumentation 1.0.5
File Size Uploaded Provenance Actions
graftcode_instrumentation-1.0.5.tar.gz 18.6 kB Without provenance Details for graftcode_instrumentation-1.0.5.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for graftcode-instrumentation 1.0.5
File Interpreter ABI Platform Actions
graftcode_instrumentation-1.0.5-py3-none-any.whl Python 3 none any Details for graftcode_instrumentation-1.0.5-py3-none-any.whl

Total release size: 33.3 kB

Release files / graftcode_instrumentation-1.0.5.tar.gz

Download URL graftcode_instrumentation-1.0.5.tar.gz
Size 18.6 kB
Tags Source
SHA-256 checksum
How to use checksums
e4bcdbff7d6ec2c0ab93247fe03d5546c0fff05f22878770aea31ecbf0d4bb83
BLAKE2b-256 checksum
How to use checksums
00eea939f4c96a43cad9c495543282368dbcfff66b68a298933c01f40d95fd7e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / graftcode_instrumentation-1.0.5-py3-none-any.whl

Download URL graftcode_instrumentation-1.0.5-py3-none-any.whl
Size 14.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5f4da530f1dc25ce7970ee54821bf7aa54723f3cef551924208c81b6313f2cfe
BLAKE2b-256 checksum
How to use checksums
25e6975059f0ad6e26757281c9f2da40e2c1b794b15a027aece2ed1e2f69ba02
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Security for graftcode-instrumentation 1.0.5

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page