Registry / observability / basictracer

basictracer

JSON →
library3.2.0pypypi✓ verified 85d ago

basictracer is a Python implementation of the OpenTracing API, providing a simple, in-memory tracer suitable for development and testing. It allows applications to instrument code with spans, logs, and baggage, adhering to the OpenTracing specification. The current version is 3.2.0, and its release cadence is infrequent, with the last major update in 2021.

pip install basictracer
INSTALL
IMPORT
SIG · BASICTRACER
B
basictracer
observabilitypythonv3.2.0
Install
3.7s avg
Import
22ms
Disk
19MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v3.2.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 0.022s · 21.4MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 3.7s · import 0.021s · 22MB
19MB installed
● package 19MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

BasicTracer
from basictracer import BasicTracer
InMemoryRecorder
from basictracer.recorder import InMemoryRecorder
SpanContextCorruptedException
from basictracer.propagator import SpanContextCorruptedException
from basictracer import SpanContextCorruptedException
SpanContextCorruptedException is part of the propagator module, not directly from basictracer top-level.

This quickstart demonstrates how to initialize `BasicTracer` with an `InMemoryRecorder`, set it as the global OpenTracing tracer, and create a basic span with logs. It also shows how to retrieve the recorded spans. Remember that `BasicTracer` stores spans in memory and does not export them.

import opentracing from basictracer import BasicTracer from basictracer.recorder import InMemoryRecorder # Initialize an in-memory recorder to store spans recorder = InMemoryRecorder() # Create a BasicTracer instance tracer = BasicTracer(recorder=recorder) # It's common practice to set the global tracer opentracing.set_global_tracer(tracer) # Start a new span using the global tracer with opentracing.start_active_span('my_operation') as scope: span = scope.span span.log_kv({'event': 'start_work', 'stage': 1}) # Simulate some work result = "some data" span.log_kv({'event': 'finish_work', 'result_len': len(result)}) # Retrieve recorded spans print(f"Recorded {len(recorder.spans)} span(s).") for s in recorder.spans: print(f" Operation: {s.operation_name}, Duration: {s.duration}ns") print(f" Logs: {s.logs}") # Example of Child-Of span with opentracing.start_active_span('parent_span') as parent_scope: with opentracing.start_active_span('child_span', child_of=parent_scope.span): pass # Child-Of span created print(f"Total recorded spans after second block: {len(recorder.spans)}")
Debug
Known issues
breakingIn version 3.2.0, `TextPropagator.extract` now explicitly raises `SpanContextCorruptedException` when encountering malformed or unextractable tracing headers. Previously, it might have silently failed or returned a default context.
fix
Update your code to handle `SpanContextCorruptedException` when calling `TextPropagator.extract`. Ensure input headers are correctly formatted according to OpenTracing standards.
affects: >=3.2.0
breakingAs of version 3.2.0, `Tracer.start_span` performs stricter type validation for the `references` argument. Passing an incorrect type (e.g., a `Span` object directly instead of an `opentracing.Reference`) will now raise a `TypeError`.
fix
Ensure the `references` argument passed to `Tracer.start_span` is an iterable of `opentracing.Reference` objects (e.g., `opentracing.ChildOf(parent_span)` or `opentracing.FollowsFrom(span_context)`).
affects: >=3.2.0
gotcha`basictracer` is an in-memory tracer, primarily designed for development, testing, and understanding OpenTracing concepts. It does not persist or export trace data to external systems.
fix
For production environments requiring distributed tracing and data persistence, integrate your application with a full-featured OpenTracing-compatible tracer like Jaeger, Zipkin, or AWS X-Ray.
affects: <all>
gotchaVersions of `basictracer` prior to 3.1.0 do not support Python 3.5+ due to older `opentracing` dependency constraints and other factors.
fix
If using Python 3.5 or newer, ensure you are using `basictracer` version 3.1.0 or higher. If you must use an older Python, downgrade `basictracer` to a compatible version (e.g., `<3.1.0`).
affects: <3.1.0
Errors
Common errors & fixes
basictracer.propagator.SpanContextCorruptedException: Could not extract `traceid` from carrier.
This error occurs when `TextPropagator.extract` (used internally by the tracer for header propagation) fails to parse expected tracing headers (e.g., `x-b3-traceid`) from the provided carrier due to malformation or absence.
fix
Verify that the incoming HTTP headers or other carrier data contain valid OpenTracing-compatible tracing information. If malformed headers are possible, wrap the extraction call in a `try...except SpanContextCorruptedException` block.
TypeError: 'Span' object is not iterable
You are likely passing an `opentracing.Span` object directly to the `references` argument of `tracer.start_span()`. This argument expects an iterable of `opentracing.Reference` objects, not a raw Span.
fix
Correctly use `opentracing.ChildOf(parent_span)` or `opentracing.FollowsFrom(span_context)` to create `Reference` objects, and pass them within a list or tuple to the `references` argument, e.g., `tracer.start_span('child', references=[opentracing.ChildOf(parent_span)])`.
SyntaxError: invalid syntax (on lines related to type hints or f-strings)
You are attempting to run `basictracer` version 3.1.0 or newer on a Python environment older than 3.5. These versions leverage newer Python features.
fix
Upgrade your Python environment to version 3.5 or higher. Alternatively, if you are stuck on an older Python version, install an older `basictracer` release (e.g., `pip install 'basictracer<3.1.0'`).
Upgrade
Version history
3.2.0latest on PyPI · released Apr 12, 2021
Audit
Dependencies
opentracingrequiredbasictracer is an implementation of the OpenTracing API and requires the core opentracing library.
Agent activity
31 hits · last 30 days
node
24
Amazon
1
OpenAI (training)
1
Resources