{"id":7975,"library":"basictracer","title":"BasicTracer Python","description":"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.","status":"active","version":"3.2.0","language":"en","source_language":"en","source_url":"https://github.com/opentracing/basictracer-python","tags":["opentracing","tracing","distributed-tracing","observability","testing","development"],"install":[{"cmd":"pip install basictracer","lang":"bash","label":"Install basictracer"}],"dependencies":[{"reason":"basictracer is an implementation of the OpenTracing API and requires the core opentracing library.","package":"opentracing","optional":false}],"imports":[{"symbol":"BasicTracer","correct":"from basictracer import BasicTracer"},{"symbol":"InMemoryRecorder","correct":"from basictracer.recorder import InMemoryRecorder"},{"note":"SpanContextCorruptedException is part of the propagator module, not directly from basictracer top-level.","wrong":"from basictracer import SpanContextCorruptedException","symbol":"SpanContextCorruptedException","correct":"from basictracer.propagator import SpanContextCorruptedException"}],"quickstart":{"code":"import opentracing\nfrom basictracer import BasicTracer\nfrom basictracer.recorder import InMemoryRecorder\n\n# Initialize an in-memory recorder to store spans\nrecorder = InMemoryRecorder()\n# Create a BasicTracer instance\ntracer = BasicTracer(recorder=recorder)\n\n# It's common practice to set the global tracer\nopentracing.set_global_tracer(tracer)\n\n# Start a new span using the global tracer\nwith opentracing.start_active_span('my_operation') as scope:\n    span = scope.span\n    span.log_kv({'event': 'start_work', 'stage': 1})\n\n    # Simulate some work\n    result = \"some data\"\n\n    span.log_kv({'event': 'finish_work', 'result_len': len(result)})\n\n# Retrieve recorded spans\nprint(f\"Recorded {len(recorder.spans)} span(s).\")\nfor s in recorder.spans:\n    print(f\"  Operation: {s.operation_name}, Duration: {s.duration}ns\")\n    print(f\"  Logs: {s.logs}\")\n\n# Example of Child-Of span\nwith opentracing.start_active_span('parent_span') as parent_scope:\n    with opentracing.start_active_span('child_span', child_of=parent_scope.span):\n        pass # Child-Of span created\n\nprint(f\"Total recorded spans after second block: {len(recorder.spans)}\")","lang":"python","description":"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."},"warnings":[{"fix":"Update your code to handle `SpanContextCorruptedException` when calling `TextPropagator.extract`. Ensure input headers are correctly formatted according to OpenTracing standards.","message":"In 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.","severity":"breaking","affected_versions":">=3.2.0"},{"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)`).","message":"As 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`.","severity":"breaking","affected_versions":">=3.2.0"},{"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.","message":"`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.","severity":"gotcha","affected_versions":"<all>"},{"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`).","message":"Versions of `basictracer` prior to 3.1.0 do not support Python 3.5+ due to older `opentracing` dependency constraints and other factors.","severity":"gotcha","affected_versions":"<3.1.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"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.","error":"basictracer.propagator.SpanContextCorruptedException: Could not extract `traceid` from carrier."},{"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)])`.","cause":"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.","error":"TypeError: 'Span' object is not iterable"},{"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'`).","cause":"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.","error":"SyntaxError: invalid syntax (on lines related to type hints or f-strings)"}]}