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): spanGraft <library> [version] <channel>, kindINTERNAL. Attributes aregraft.dependency.type = Graft,graft.dependency.target,hypertube.runtime,hypertube.command_type,hypertube.connection_type,hypertube.operation, andhypertube.target(with user info stripped). - Callee (
on_process): span named after the operation, for exampleTestGgPythonLib.RandomService.RandomService.fetch, kindINTERNAL. - No span is opened for
PassByValue,RegisterForUpdate,ValueForUpdate,InvokeDelegate, or any operation ending inTelemetrySetup.Initialize. - When a call fails, the span gets
exception.type, a redactedexception.message, and statusERROR. - 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 W3Ctraceparent/tracestateplustraceid, and restores the previous headers when the call completes. Atraceparentthat the application set on the connection is never overwritten. - Incoming: W3C headers from the
ContextMetadatacommand are preferred. If only atraceidheader arrives and it differs from the current trace, the callee joins that trace under a synthetic remote parent. - Called side: on the called side,
ContextMetadatais handled throughgraftcode.context.request_context.RequestContext, so the hosted library needsgraftcode-contextinstalled.
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:
- The
LoadLibraryfile stem. - The longest recorded library that prefixes the target type.
- 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.truncatedattribute.
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 asextra, and the exception asexc_info. Names that clash withLogRecordattributes get a trailing_. - Without a logger: the line becomes a span event carrying
log.level. Exceptions become anexceptionevent with redactedexception.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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.